| Free-Form Syntax | XML-SAX{(E)} %HANDLER(handlerProc : commArea) %XML(xmlDoc {: options }); |
| Code | Factor 1 | Extended Factor 2 | ||||
|---|---|---|---|---|---|---|
| XML-SAX{(E)} | %HANDLER(handlerProc : commArea) %XML(xmlDoc {: options }) | |||||
Tip: If you are not familiar with the basic concepts of XML and of processing XML documents, you may find it helpful to read the "Processing XML Documents" section in IBM Rational Development Studio for i: ILE RPG Programmer's Guide before reading further in this section.
XML-SAX initiates a SAX parse for an XML document. The XML-SAX operation code begins by calling an XML parser which begins to parse the document. When an event occurs such as the parser finding the start of an element, finding an attribute name, finding the end of an element and so on, the parser calls the handling procedure handlerProc with parameters describing the event. When the handling procedure returns, the parser continues to parse until it finds the next event and calls the handling procedure again. When the parser has finished parsing the document, control passes to the statement following the XML-SAX operation.
The first operand must be the %HANDLER built-in function; handlerProc is a prototype name that specifies the procedure to be called to handle the SAX events and commArea is the communication-area parameter to be passed by the parser to the handling procedure. The communication-area parameter must be the same type as the first prototyped parameter of the handling procedure. It provides a way for the procedure specifying the XML-SAX operation code to communicate with the handling procedure, and for the handling procedure to save information related to the parse from one event to the next. See %HANDLER (handlingProcedure : communicationArea ) for more information on %HANDLER.
The second operand must be the %XML built-in function, identifying the XML document to be parsed and the options controlling the way the parsing is done. See %XML (xmlDocument {:options}) for more information on %XML.
Operation extender E can be specified to handle the following status codes:
For status 00351, the return code from the parser will be placed in the subfield "External return code" in positions 368-371 of the PSDS. This subfield will be set to zero at the beginning of the operation and set to the value returned by the parser at the end of the operation. This subfield is relevant only in a module that has an XML-SAX operation. SAX event-handling procedures receive the information from the parser as parameters.
The event-handling procedure will not be called if an exception occurs before parsing begins. For example, if the specified file is not found, the operation will end immediately with status 00354 and the event-handling procedure will never get control.
If an error occurs during parsing, the handling procedure will be called with a *XML_EXCEPTION event, and when the handling procedure returns, parsing will end and the XML-SAX operation will fail with status code 00351. The return code from the parser will be placed in the "External return code" subfield in positions 368 - 371 of the PSDS.
If an unknown, invalid or unrelated option is found in the %XML options string, XML-SAX will fail with status code 00352. The External return code subfield in positions 368 - 371 of the PSDS will not be updated from the initial value of zero, set when the operation begins.