When the XML parser receives control from an XML PARSE statement, the parser analyzes the XML document and transfers control to procedure-name-1 at the following points in the process:
Control returns to the XML parser when the end of the processing procedure is reached.
The exchange of control between the parser and the processing procedure continues until either:
Then, the parser terminates and returns control to the XML PARSE statement with the XML-CODE special register containing the most recent value set by the parser or the processing procedure.
For each XML event passed to the processing procedure, the XML-CODE, XML-EVENT, and XML-TEXT or XML-NTEXT special registers contain information about the particular event. The content of the XML-CODE special register is defined during and after execution of an XML PARSE statement. The contents of all other XML special registers is undefined outside the range of the processing procedure.
For normal events, special register XML-CODE contains zero when the processing procedure receives control. For EXCEPTION events, XML-CODE contains one of the XML exception codes specified in the ILE COBOL Programmer's Guide. Special register XML-EVENT is set to the event name, such as 'START-OF-DOCUMENT'. Either XML-TEXT or XML-NTEXT contains the piece of the document corresponding with the event, as described in XML-EVENT.
For more information about the XML special registers, see Special registers.
For all kinds of XML events, if XML-CODE is not zero when the processing procedure returns control to the parser, the parser terminates without a further EXCEPTION event. Setting XML-CODE to -1 before returning to the parser from the processing procedure for an event other than EXCEPTION forces the parser to terminate with a user-initiated exception condition. For some EXCEPTION events, the processing procedure can set XML-CODE to zero to force the parser to continue, although subsequent results are unpredictable. When XML-CODE is zero, parsing continues until the entire XML document has been parsed or an unhandled exception condition occurs.
During parsing, the program that specified the XML PARSE statement must not be called recursively.
The XML PARSE statement must not be specified in a nested program, although the XML special registers may be referenced in nested programs.
For more information about the EXCEPTION event and exception processing, see the ILE COBOL Programmer's Guide.