1. XML PARSE

The XML PARSE statement is the COBOL language interface to an XML parser depending on the setting of the XMLPARSE compiler option.

There are two XML parsers: XMLPARSE(XMLSS) and XMLPARSE(COMPAT). OFCOBOL uses XMLPARSE(XMLSS).

The XML PARSE statement parses an XML document into its individual pieces and passes each piece to a user-written processing procedure.

figure pd xml parse
XML PARSE Format

The following items are specified in the statement.

  • identifier-1

    • Contains XML document characters. Must be an alphanumeric data item or alphanumeric group data item.

  • PROCESSING PROCEDURE phrase

    • Procedure name to handle various events generated by the XML parser.

      • procedure-name-1, procedure-name-2

        Section or paragraph names in the procedure division. If both procedure-name-1 and procedure-name-2 are specified, they must be in the same procedure. If either is a name in a declarative procedure, both of them must be in the declarative procedure.

      • procedure-name-1

        First or only section or paragraph in the processing procedure.

      • procedure-name-2

        Last section or paragraph in the processing procedure.

    • For each XML event, the parser sends control to the first statement in the procedure named procedure-name-1. Control is always returned from the processing procedure to the XML parser.

      The point from which control is returned is determined as follows:

      • If procedure-name-1 is a paragraph name and procedure-name-2 is not specified, the control is returned after the last statement in the procedure-name-1 paragraph is executed.

      • If procedure-name-1 is a section name and procedure-name-2 is not specified, the control is returned after the last statement in the last paragraph in the procedure-name-1 section is executed.

      • If procedure-name-2 is specified as a paragraph name, the control is returned after the last statement in the procedure-name-2 paragraph is executed.

      • If procedure-name-2 is specified as a section name, the control is returned after the last statement in the last paragraph in the procedure-name-2 section is executed.

      An execution sequence from the procedure named procedure-name-1 to the procedure named procedure-name-2 must be defined. If there are two or more paths to a return point, procedure-name-2 can be a name of a paragraph that consists of only an EXIT statement. All the paths to the return point must lead to the paragraph.

    • The processing procedure consists of all the statements for handling XML events. The procedure range includes all statements executed by CALL, EXIT, GO TO, GOBACK, and PERFORM statements in the range. The range must not cause a GOBACK or EXIT PROGRAM statement execution. The procedure can end the run unit with a STOP RUN statement.

  • ON EXCEPTION phrase

    • Executed when the XML PARSE statement causes an exception condition.

    • An exception condition exists when the XML parser detects an error during XML document processing. The parser signals an XML exception by sending control to the processing procedure by using the XML-EVENT special register containing 'EXCEPTION'. An exception condition also exists when the processing procedure sets XML-CODE to -1. In this case, XML-EVENT does not contain 'EXCEPTION' and the parsing ends.

    • If this phrase is specified, the parser sends control to imperative-statement-1. If this phrase is not specified and the NOT ON EXCEPTION phrase is specified, the NOT ON EXCEPTION phrase is ignored and control is sent to the end of the XML PARSE statement. If the processing procedure handles an XML exception event, sets XML-CODE to 0, and then sends control to the parser, the exception condition no longer exists.

  • NOT ON EXCEPTION phrase

    • Executed when there is no exception condition at the end of XML PARSE processing.

      If an exception condition does not exist when XML PARSE processing ends, control is sent to imperative-statement-2 in the NOT ON EXCEPTION phrase if the phrase is specified. If the phrase is not specified, control is sent to the end of the XML PARSE statement. If the ON EXCEPTION phrase is specified, it is ignored.

    • The special register XML-CODE contains 0 after the XML PARSE statement execution.

  • END-XML phrase

    • Indicates the end of the XML GENERATE or XML PARSE statement.