%XML_ELEM_GETTEXTHANDLE

Return handle containing text for an element

handle = %XML_ELEM_GETTEXTHANDLE(element)

Return value

handle

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

Arguments

element

The XML element instance to get the text handle for. (XML_ELEM_TYPE)

Discussion

%XML_ELEM_GETTEXTHANDLE returns the memory handle that contains the text for an XML attribute.

Since %XML_ELEM_GETTEXTHANDLE may be used instead of %XML_ELEM_GETTEXT for performance reasons, %XML_ELEM_GETTEXTHANDLE does not honor the ENCODE option of %XML_OPTION. If you use %XML_ELEM_GETTEXTHANDLE, 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.

If you call %XML_ELEM_GETTEXTHANDLE and then do an unescape on the handle, any document that contains that element 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.

%XML_ELEM_GETTEXTHANDLE does honor the PARSER option of %XML_OPTION to control whether leading and trailing blanks are stripped in the text element.

This function is defined as ^VAL.

Examples

The example below finds the element that contains the text.

    doc         ,XML_DOC_TYPE
    root        ,XML_ELEM_TYPE
    elem        ,XML_ELEM_TYPE
    children    ,XML_ELEMLIST_TYPE
    h           ,D_HANDLE
    
    root = %xml_doc_getroot(doc)
    children = %xml_elem_children(root)
    elem = %xml_elemlist_findtag(children, "PeetsCoffee")

    h = %xml_elem_gettexthandle(elem)

    open(1, o, "outfile.txt")

    if (h) then
      writes(1, ^m(h))
    else
      writes(1, "Unable to get the texthandle")
    close 1