%XML_ATTR_GETVALUEHANDLE

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
handle = %XML_ATTR_GETVALUEHANDLE(attr)

Return value

handle

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

Arguments

attr

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

Discussion

%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.

Important

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.

Examples

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))
    else
      writes(1, "Unable to get value handle for attribute")
    close 1