%XML (xmlDocument {:options})

%XML is used as the second operand of the XML-SAX and XML-INTO operation codes to specify the XML document to be parsed, and the options to control how the document is parsed. %XML does not return a value, and it cannot be specified anywhere other than for the XML-SAX and XML-INTO operation codes.

The first operand specifies the document to be parsed. It can be a constant or variable character or UCS-2 expression containing either an XML document or the name of a file containing an XML document.

The second operand specifies options that control how the XML document is to be interpreted and parsed. It can be a constant or variable character expression. The value of the character expression is a list of zero or more options specified in the form

    optionname1=value1 optionname2=value2

No spaces are allowed between the option name and the equal sign or between the equal sign and the value. However, any number of spaces can appear before, between or following the options. The options can be specified in any case. The following are all valid ways to specify the "doc=file" and "allowextra=yes" options for XML-INTO:

   'doc=file allowextra=yes'
   '        doc=file     allowextra=yes     '
   'ALLOWEXTRA=YES DOC=FILE     '
   'AllowExtra=Yes Doc=File     '

The following are not valid option strings:

The valid options and values depend on the context of the %XML built-in function. See XML-SAX (Parse an XML Document) and XML-INTO (Parse an XML Document into a Variable) for a complete list of valid options and values.

When an option is specified more than once, the last value specified is the value that is used. For example, if the options parameter has the value

   'doc=file doc=string'

then the parser will use the value "string" for the "doc" option.

If the parser discovers an invalid option or invalid value, the operation will fail with status code 00352.

// The "options" parameter is omitted.  Default values are used for
// all options.  Since the default value for the "doc" option is
// always "string", the parser will correctly assume that the first
// parameter contains an XML document.

xmldocument = '<myfld>new value</myfld>';
XML-INTO myfld %XML(xmldocument);

// The "options" parameter is specified as a literal with two options.

XML-INTO myds %XML(xmldocument : 'allowmissing=yes allowextra=yes');

// The "options" parameter is specified as a variable expression
// with two options.

ccsidOpt = 'ccsid=' + %char(ccsid);
XML-SAX %HANDLER(mySaxHandler : myCommArea)
        %XML('myinfo.xml' : 'doc=file ' + ccsidOpt);

For more examples of %XML, see XML-SAX (Parse an XML Document) and XML-INTO (Parse an XML Document into a Variable).

For more information, see XML Operations or Built-in Functions.