%XML_OPTION

Set an XML option value

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
 
status = %XML_OPTION(option, value)

Return value

status

One of the following values:

XML_SUCCESS = A valid value is provided and the option is set successfully.

XML_FAIL = A valid value is not provided and the option is not set successfully.

Arguments

option

The XML option to set. (a)

value

The value for the option. (n)

Discussion

%XML_OPTION sets a value for the following options:

Option

Value

Behavior

ENCODE

SYNESCAPE_OFF (default)

Does not escape or unescape any items.

SYNESCAPE_ESCAPE

Escapes text or attribute values according to XML escape rules (see the Escape Codes for Characters in XML Strings table) when calling %XML_ELEM_SETTEXT, %XML_ELEM_SETATTRIBUTE, or %XML_ATTR_SETVALUE, and escapes the text or attribute values set by %XML_PARSER_PARSEFILE or %XML_PARSER_PARSESTRING.

SYNESCAPE_UNESCAPE

Unescapes text or attribute values when calling %XML_ELEM_GETTEXT or %XML_ATTR_GETVALUE, according to XML escape rules (see the Escape Codes for Characters in XML Strings table).

PARSER

SYNPARSER_KEEP_LEADING_
SPACE

Keep leading spaces in element text when calling %XML_ELEM_GETTEXT and %XML_ELEM_GETTEXTHANDLE

SYNPARSER_NO_LINE_
TERMINATORS

Read XML file with GETS instead of READS, causing the file to be read with no line terminators. This value also sets SYNPARSER_KEEP_LEADING_SPACE. On OpenVMS, only stream files are supported; any other file type generates an error.

SYNPARSER_DEFAULT

Strip leading spaces in element text when calling %XML_ELEM_GETTEXT and %XML_ELEM_GETTEXTHANDLE

To keep leading spaces in text elements (instead of stripping them) when calling %XML_ELEM_GETTEXT and %XML_ELEM_GETTEXTHANDLE, call

%XML_OPTION("PARSER", SYNPARSER_KEEP_LEADING_SPACE)

before parsing the XML file with either %XML_PARSER_PARSEFILE or %XML_PARSER_PARSESTRING.

Important

On .NET, %XML_OPTION affects all threads and should not be used by multiple concurrent threads of the Synergy XML API.
Note

When serializing an XML document to a string or a file, %XML_DOC_TOSTRING and %XML_DOC_TOFILE won’t unescape any escaped text or attribute values in the XML document.

This function is defined as ^VAL.

Examples

The following example uses XML_OPTION to engage the unescape behavior for XML_ELEM_GETTEXT.

    doc         ,XML_DOC_TYPE
    root        ,XML_ELEM_TYPE
    elem        ,XML_ELEM_TYPE
    children    ,XML_ELEMLIST_TYPE
    text        ,a100

; Find the element that contains the text

    root = %xml_doc_getroot(doc)
    children = %xml_elem_children(root)
    elem = %xml_elemlist_findtag(children, "MaxwellHouse")

; Set an option to have the text string unescaped

    xcall xml_option("ENCODE", SYNESCAPE_UNESCAPE)
    xcall xml_elem_gettext(elem, text)