%XML_ATTR_SETVALUEHANDLE

Assign a handle as an XML attribute’s value

status = %XML_ATTR_SETVALUEHANDLE(attr, handle)

Return value

status

One of the following values:

XML_SUCCESS = The value is set successfully.

XML_FAIL = The value is not set successfully.

Arguments

attr

The XML attribute instance to set a value handle for. (XML_ATTR_TYPE)

handle

The handle of the value for the attribute. (D_HANDLE)

Discussion

%XML_ATTR_SETVALUEHANDLE assigns a handle as the value for an XML attribute. The length of the attribute value cannot be larger than 65,502.

For performance reasons, %XML_ATTR_SETVALUEHANDLE does not honor %XML_OPTION with regard to escaping attribute values. If you use %XML_ATTR_SETVALUEHANDLE, 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.

Examples

The following example uses a handle to set the value of an attribute.

    doc         ,XML_DOC_TYPE
    attr        ,XML_ATTR_TYPE
    root        ,XML_ELEM_TYPE
    elem        ,XML_ELEM_TYPE
    children    ,XML_ELEMLIST_TYPE
    attrlist    ,XML_ATTRLIST_TYPE
    h           ,D_HANDLE

; Find the PeetsCoffee element and get the location attribute

    root = %xml_doc_getroot(doc)
    children = %xml_elem_children(root)
    elem = %xml_elemlist_findtag(children, "PeetsCoffee")
    attrlist = %xml_elem_attributes(elem)
    attr = %xml_attrlist_find(attrlist, "location")

    h = %mem_proc(DM_ALLOC+DM_STATIC+DM_BLANK, 200)

; Set a new value for the location attribute

    ^m(h)  = 'Seattle, Washington, USA' 

    xcall xml_attr_setvaluehandle(attr, h)