XML-INTO (Parse an XML Document into a Variable)

XML-INTO can operate in two different ways:

• Reading XML data directly into an RPG variable
• Reading XML data gradually into an array parameter that it passes to the procedure specified by %HANDLER(handlerProc).

If the first operand is a variable name:

• Parsing will be done directly into the variable.
• The name of the variable will be used to establish the name of the XML element to parse; this can be overridden using the path option.
• If the variable is a data structure, some subfields may be set by the operation even if the operation ends in error.
• If the variable is an array, the parsing will only search for as much data as will fit in the array. The "Number of XML Elements" subfield in positions 372 - 379 of the PSDS will be set to the number of elements successfully set by the operation. For an array of data structures, this value will not include the element being set if a parsing error occurs while parsing the data for the subfields of the element; however, this array element may have some of its subfields set by the operation.

If the first operand is the %HANDLER built-in function:

• The procedure specified as the first operand of %HANDLER will be called when the parser has parsed enough XML data to fill the specified number of RPG array elements handled by the procedure. When the handler returns, the parser will continue to parse the XML data until it has parsed enough XML data to again fill the specified number of array elements to call the handling procedure. This continues until the document is completely parsed, or until the procedure returns a return code indicating that the parsing should halt.

  The final call to the handling procedure may have fewer RPG array elements than the handling procedure can handle. The handling procedure should always refer to the "number of elements" parameter to ensure it does not access array elements that do not have any XML data.

  The communication-area variable specified as the second operand of %HANDLER will be passed by the parser as the first parameter to the handling procedure, allowing the procedure coding the XML-INTO operation to communicate with the handling procedure, and allowing the handling procedure to save information from one call to the next.

• Each element of the temporary variable used to hold the array parameter for the procedure will be cleared to its default value before it is loaded from the XML data.
• The path option must be used to specify the name of the XML element to search for. See %DATA and %XML options for DATA-GEN, DATA-INTO, and XML-INTO and Expected format of XML data and for information about the path option.
• The array-handling procedure may be called several times during the XML-INTO operaton. When the parser has found the number of elements specified by the DIM keyword on the second parameter, the procedure will be called. The final time the procedure is called may have fewer elements than specified by the DIM keyword. If there are no elements found, the procedure will not be called.
  The handling procedure must have the following parameters and return type:

  Parameter number or return value	Data type and passing mode	Description
  Return value	4-byte integer (10I 0)	Returning a value of zero indicates that parsing should continue; returning any other value indictes that parsing should end.
  1	Any type, passed by reference	Used to communicate between the XML-INTO operation and the handler, and between successive calls to the handler.
  2	Array, or array of data structures, passed by read-only reference (CONST keyword)	The array elements contain the data from the XML elements specified by the path option.
  3	4-byte unsigned (10U 0), passed by value	The number of array elements in the second parameter that represent XML data.

• See %HANDLER (handlingProcedure : communicationArea ) for more information on %HANDLER.

Operation extender H can be specified to cause numeric data to be assigned half-adjusted. Operation extender E can be specified to handle the following status codes:

00351

Error in XML parsing

00352

Invalid XML option

00353

XML document does not match RPG variable

00354

Error preparing for XML parsing

The XML document is expected to match the RPG variable with respect to the names of the XML elements or attributes.

• The XML data for an RPG data structure is expected to have an XML element with the same name as the data structure and child elements and/or attributes with the same names as the RPG subfields.
• The XML data for an RPG array is expected to have a series of elements with the same name as the RPG array.

The path option can be used to set the name of the XML element matching the name of the specified variable, but it cannot be used to set the names of the XML elements and/or attributes matching a specified variable's subfields. For example, if variable DS1 has a subfield SF1, the XML element for DS1 can have any name, but the XML element or attribute for SF1 must have the name "sf1" (or "SF1", "Sf1", etc., depending on the case option).

When the RPG variable is an array or array of data structures, or when the %HANDLER built-in function is specified, the XML elements corresponding to the array elements are expected to be contained in another XML element. By default, the XML elements will be expected to be child elements of the outermost XML element in the document. The path option can be used to specify the exact path to the XML elements corresponding to the array elements. For example, if the outermost XML element is named "transaction", and it has a child element named "parts" which itself has several child elements named "part", then to read the "part" XML elements into an array, you would specify the option 'path=transaction/parts/part'.

  <transaction>
    <parts>
       <part type = "bracket" size="15" num="100"/>
       <part type="frame" size="2" num="500"/>
    </parts>
  <transaction>