%XML_ELEM_SETTEXTHANDLE

Assign a handle as the text for an XML element

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
 
status = %XML_ELEM_SETTEXTHANDLE(element, handle)

Return value

status

One of the following values:

XML_SUCCESS = The handle is assigned successfully.

XML_FAIL = The handle is not assigned successfully.

Arguments

element

The XML element instance to set a text handle for. (XML_ELEM_TYPE)

handle

The handle of the text for the XML element. (D_HANDLE)

Discussion

The maximum length of the element text is 65,534 characters.

For performance reasons, %XML_ELEM_SETTEXTHANDLE does not honor %XML_OPTION with regard to escaping text. If you use %XML_ELEM_SETTEXTHANDLE, escaping certain characters (for example, ampersands and double quotation marks) is your responsibility. You can escape characters using %SYN_ESCAPE_HANDLE before calling this method.

Important

If the handle being set is different from the current one, you should release the old handle, if it isn’t being used somewhere else, before setting the new one. If you don’t, memory leaks will occur.

This function is defined as ^VAL.

Examples

The example below uses a handle to set the text for an element.

    doc         ,XML_DOC_TYPE
    root        ,XML_ELEM_TYPE
    elem        ,XML_ELEM_TYPE
    children    ,XML_ELEMLIST_TYPE
    h           ,D_HANDLE
 
; Find the element FolgersCoffee to receive the text

    root = %xml_doc_getroot(doc)
    children = %xml_elem_children(root)
    elem = %xml_elemlist_findtag(children, "FolgersCoffee")

    h = %mem_proc(DM_ALLOC+DM_STATIC+DM_BLANK, 200)
    ^m(h) = 'here is the string we want to add'

    xcall xml_elem_settexthandle(elem, h)