Parsing XML documents

To parse XML documents, when the XML document is in a data item, use the XML PARSE statement, as in the following example:

XML PARSE XMLDOCUMENT
    PROCESSING PROCEDURE XMLEVENT-HANDLER
  ON EXCEPTION
     DISPLAY 'XML document error ' XML-CODE
     STOP RUN
  NOT ON EXCEPTION
     DISPLAY 'XML document was successfully parsed.'
END-XML

In the XML PARSE statement you first identify the data item (XMLDOCUMENT in the example) that contains the XML document character stream. In the DATA DIVISION, you can declare the identifier as an alphanumeric data item or as a national data item. If it is alphanumeric, its contents must be encoded with one of the supported single-byte EBCDIC or ASCII character sets. If it is a national data item, its contents must be encoded with Unicode UCS-2 CCSID specified in the National CCSID compiler option or in the NTLCCSID PROCESS option. Alphanumeric XML documents that do not contain an encoding declaration are parsed with the CCSID of the COBOL source member, or if COBOL source is in an IFS stream file, the CCSID of the stream file is used.

Next you specify the name of the procedure (XMLEVENT-HANDLER in the example) that is to handle the XML events from the document.

In addition, you can specify either or both of the following imperative statements to receive control at the end of the parse:

  • ON EXCEPTION, to receive control when an unhandled exception occurs
  • NOT ON EXCEPTION, to receive control otherwise

You can end the XML PARSE statement with END-XML. Use this scope terminator to nest your XML PARSE statement in a conditional statement or in another XML PARSE statement.

The exchange of control between the XML parser and your processing procedure continues until one of the following occurs:

  • The entire XML document has been parsed, indicated by the END-OF-DOCUMENT event.
  • The parser detects an error in the document and signals an EXCEPTION event. Your processing procedure does not reset the special register XML-CODE to zero before returning to the parser.
  • You terminate the parsing process deliberately by setting the special register XML-CODE to -1 before returning to the parser.

related tasks Understanding XML document encoding

related references XML PARSE statement (ILE COBOL Language Reference) Control flow (ILE COBOL Language Reference)