Control flow

When the XML parser receives control from an XML PARSE statement, the parser analyzes the XML document and transfers control at specific points in the process.

The points are:

  • The start of the parsing process
  • When a document fragment is found
  • When the parser detects an error in parsing the XML document
  • The end of processing the XML document

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:

  • The entire XML document has been parsed, ending with the END-OF-DOCUMENT event.
  • The processing procedure terminates parsing deliberately by setting XML-CODE to -1 before returning to the parser.
  • When the XMLPARSE(XMLSS) compiler option is in effect: The parser detects an exception of any kind.
  • When the XMLPARSE(COMPAT) compiler option is in effect: The parser detects an exception (other than an encoding conflict) and the processing procedure does not reset special register XML-CODE to zero before to returning to the parser.
  • When the XMLPARSE(COMPAT) compiler option is in effect: The parser detects an encoding conflict exception and the processing procedure does not reset special register XML-CODE to zero or to the CCSID of the document encoding.

In each case, the processing procedure returns control to the parser. 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 -1 (which might have been set by the parser or by the processing procedure).

For each XML event passed to the processing procedure, the XML-CODE and XML-EVENT special registers contain information about the particular event. Special register XML-EVENT is set to the event name, such as 'START-OF-DOCUMENT'. For most events, the XML-TEXT or XML-NTEXT special register contains document text. Additionally, when the XMLPARSE(XMLSS) compiler option is in effect, the XML-NAMESPACE and XML-NAMESPACE-PREFIX or the XML-NNAMESPACE and XML-NNAMESPACE-PREFIX special registers contain a namespace identifier and namespace prefix when applicable. See XML-EVENT for details.

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 are undefined outside the range of the processing procedure.

For normal XML events, special register XML-CODE contains zero when the processing procedure receives control. For XML exception events, XML-CODE contains an XML exception code as described in XML PARSE exceptions in the Enterprise COBOL Programming Guide.

For more information about the XML special registers, see:

For an introduction to special registers, see Special registers

For more information about the EXCEPTION event and exception processing, see Handling XML PARSE exceptions in the Enterprise COBOL Programming Guide.