RXS_DOMBuild
From Wiki
|
| User Guide |
| v2.00+ |
Contents |
Description
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.
Call this subprocedure to build a DOM of either an XML document residing in the IFS or the contents of an RPG variable that contains XML.
Prototype
D RXS_DOMBuild pr D pFilePathOrData... D value like(RXS_XmlData) D pType value like(RXS_Type) D pError likeds(RXS_Error) D pOptions 10i 0 value options(*nopass) D pStartXPath value like(RXS_XPath) options(*nopass) D pEndXPath value like(RXS_XPath) options(*nopass)
Parameters
- pFilePathOrData
- 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.’
- pType
- This parameter can either have RXS_STMF or RXS_VAR specified as its value. 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.
- pError
- A structure which can be used to trap for errors on return from RXS_DOMBuild.
- pOptions
- 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.
- pStartXPath
- An optional path specifying the XPath within the DOM where parsing should start.
- pEndXPath
- An optional path specifying the XPath within the DOM where parsing should stop.
Return value
None.
Notes / Examples
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.