RXS_DOMBuild()

NOTE: The RXS_DOM* APIs were created to allow for a different approach to parsing XML documents. Depending on the complexity of your XML and what data elements you are parsing, the RXS_DOM* APIs can make the syntax for parsing simpler. The simpler syntax comes with a cost because the entire XML document is parsed and stored in memory so you can access any element data at any time (think of it as being able to “CHAIN” to the XML structure - random access). Performance for smaller XML files is comparable for the two XML parsers within RPG-XML Suite, but the larger the XML file the bigger the divide. For example, a large 4MB XML file will take 200 seconds with the event based parser and 600 seconds with the DOM parser. So make sure to factor that into your decision on whether to use the RXS_DOM* APIs to parse or the event based parser.

The following rules apply when specifying non-blank values for either pStartXPath or pEndXPath:

  • If pStartXPath is specified as non-blank, although the entire document will be parsed, the building of the DOM will only start when the first instance of that XPath is found.
  • If pEndXPath is specified as non-blank and pStartXPath is specified as blank, parsing will stop when the first instance of pEndXPath path is found.
  • If pStartXPath is specified as non-blank and pEndXPath is also specified as non-blank, DOM building will start when the first instance of the pStartXPath is found and will stop when the first subsequent instance of pEndXPath is found.
  • If pStartXPath is specified as non-blank but pEndXPath is not specified (or is specified as blank), DOM building will start when the first instance of the gStartXPath is found (same as rule 1 above) and will stop when that XML ‘section’ has ended.

Subprocedure Prototype

D RXS_DOMBuild    pr

Builds a DOM tree from XML.

 
D  pFilePathOrData...
D                                     value like(RXS_XmlData)

Used to specify a file in the IFS or actual XML residing in an RPG variable. If an IFS file is specified it must either be fully qualified (i.e. /home/user/mydoc.xml) or must reside in the default transaction directory (i.e. /www/rxs/trans.) If it resides in the default transaction directory then you can just specify it as 'mydoc.xml.'

 
D  pType                              value like(RXS_Type)

Use RXS_STMF if the value passed in pFilePathOrData is a path to an IFS file. Use RXS_VAR if the value passed in pFilePathOrData contains XML.

Valid Values:

  • RXS_STMF
  • RXS_VAR

 
D  pError                             likeds(RXS_Error)

A structure which can be used to trap for errors on return from RXS_DOMBuild().

 
D  pOptions                     10i 0 value options(*nopass)

An optional integer which can contain various options used by RXS_DOMBuild(). See the documentation for the RXS_DOMSetOpt() procedure for details of the various allows options. Passing this parameter directly to RXS_DOMBuild() is the same as performing a separate call to RXS_DOMSetOpt() prior to calling RXS_DOMBuild().

 
D  pStartXPath                        value like(RXS_XPath)
D                                     options(*nopass)

An optional path specifying the XPath within the DOM where parsing should start.

 
D  pEndXPath                          value like(RXS_XPath)
D                                     options(*nopass)

An optional path specifying the XPath within the DOM where parsing should stop.