Return the handle for an XML attribute’s value

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS

Return value


The handle that contains the value for the specified attribute, or 0 if no value is assigned. (D_HANDLE)



The XML attribute instance to get the value handle for. (XML_ATTR_TYPE)


%XML_ATTR_GETVALUEHANDLE returns the memory handle that contains the value of an XML attribute.

Since %XML_ATTR_GETVALUEHANDLE may be used instead of %XML_ATTR_GETVALUE for performance reasons, %XML_ATTR_GETVALUEHANDLE does not honor %XML_OPTION with regard to unescaping attribute values. If you use %XML_ATTR_GETVALUEHANDLE, unescaping certain characters (for example, ampersands and double quotation marks) is your responsibility. You can unescape characters using %SYN_UNESCAPE_HANDLE after calling this method. See %SYN_UNESCAPE_HANDLE for more information.


If you call %XML_ATTR_GETVALUEHANDLE and then do an unescape on the handle, any document that contains that attribute will be modified. Therefore, if you don’t want to modify your document, you should make a copy of the handle before performing any escaping or unescaping.

This function is defined as ^VAL.


The following example returns the value for the Starbucks grind attribute as a handle.

    doc         ,XML_DOC_TYPE
    attr        ,XML_ATTR_TYPE
    root        ,XML_ELEM_TYPE
    elem        ,XML_ELEM_TYPE
    attrlist    ,XML_ATTRLIST_TYPE
    children    ,XML_ELEMLIST_TYPE
    h           ,D_HANDLE
    root = %xml_doc_getroot(doc)
    children = %xml_elem_children(root)
    elem = %xml_elemlist_findtag(children, "Starbucks")
    attrlist = %xml_elem_attributes(elem)
    attr = %xml_attrlist_find(attrlist, "grind")
    open(1,o, "outfile.txt")
    h = %xml_attr_getvaluehandle(attr)
    if (h) then
      writes(1, ^m(h))
      writes(1, "Unable to get value handle for attribute")
    close 1