Assign a handle as the text for an XML element

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
status = %XML_ELEM_SETTEXTHANDLE(element, handle)

Return value


One of the following values:

XML_SUCCESS = The handle is assigned successfully.

XML_FAIL = The handle is not assigned successfully.



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


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


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. See %SYN_ESCAPE_HANDLE for more information.


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.


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)