
The XML PARSE Statement
The XML PARSE statement is used to interface with an XML parser that
is part of the COBOL run-time system. The XML PARSE statement parses an XML
document into its individual pieces and passes each piece, one at a time, to a
user-written processing procedure.
General Format

Syntax Rules
- Identifier-1 must be an alphanumeric or national data item,
cannot be a function-identifier, and should contain the XML document character
stream. If identifier-1 is a national data item, its contents must be encoded
using CCSID 1200 (Unicode UTF-16). It must not contain any character entities
that are represented using multiple encoding units. Use a character reference,
for example "" or "", to represent any such characters.
- Procedure-name-1 specifies the first or only section or paragraph
in the processing procedure
- Procedure-name-2 specifies the last section or paragraph in the
processing procedure.
General Rules
- The PROCESSING PROCEDURE phrase specifies the name of a procedure
to handle the various events that the XML parser generates. The processing
procedure consists of the statements that handle XML events. The range of the
processing procedure also includes all statements executed by CALL, EXIT, GO
TO, GOBACK, INVOKE, and PERFORM statements in the processing procedure. The
Compiler inserts a return mechanism after the last statement in the processing
procedure. The processing procedure can terminate the run unit with a STOP RUN
statement. It must not attempt to return to the parser with a GOBACK or EXIT
PROGRAM statement.
- The ON EXCEPTION phrase specifies imperative statements that are
executed when the XML PARSE statement raises an exception condition. An
exception condition occurs when the XML parser detects an error in processing
the XML document. The parser first signals an exception XML event by passing
control to the processing procedure with special register XML-EVENT set to
contain "EXCEPTION". The parser provides a numeric error code in special
register XML-CODE, as detailed in
Table
2 of the Special Registers section of the
Concepts of the COBOL Language.
An exception condition also occurs if the processing procedure
deliberately terminates parsing by setting XML-CODE to -1 before returning to
the parser from any normal XML event. In this case, the parser does not signal
an EXCEPTION XML event. The following applies:
- If the ON EXCEPTION phrase is specified, the parser then
transfers control to imperative-statement-1.
- If the ON EXCEPTION phrase is not specified, the NOT ON
EXCEPTION phrase, if any, is ignored, and control is transferred to the end of
the XML PARSE statement.
- If the XML processing procedure handles the exception XML
event and sets XML-CODE to zero before returning control to the parser, the
exception condition no longer exists.
- If no other unhandled exceptions occur before the termination
of the parser, control is transferred to imperative-statement-2 of the NOT ON
EXCEPTION phrase, if specified.
- The NOT ON EXCEPTION phrase specifies imperative statements that
are executed when no exception condition exists at the termination of XML PARSE
processing. The following applies:
- If an exception condition does not exist at termination of
XML PARSE processing, control is transferred to imperative-statement-2 of the
NOT ON EXCEPTION phrase, if specified.
- If the NOT ON EXCEPTION phrase is not specified, control is
transferred to the end of the XML PARSE statement. In this case, ON EXCEPTION,
if specified, is ignored. Special register XML-CODE contains zero after
execution of the XML PARSE statement.
Related Topics: