action.skip

XML PARSE Statement

The XML PARSE statement parses an XML document and returns data values to their corresponding data elements. This data can then be processed by the COBOL program.

General Format:

       XML PARSE identifier-1
       PROCESSING PROCEDURE [IS]
              procedure-name-1 [THROUGH procedure-name-2]
                                THRU
              [[ON] EXCEPTION imperative-statement-1]
              [NOT [ON] EXCEPTION imperative-statement-2]
              [END-XML]

Syntax Rules:

  1. identifier-1 is an alphanumeric data item that holds an XML document.
  2. The PROCESSING PROCEDURE phrase specifies the name of a procedure to respond to the events generated by the XML PARSE statement.
  3. procedure-name-1 and procedure-name-2 define a consecutive sequence of operations to execute, beginning at the procedure named by procedure-name-1 and ending with the execution of the procedure named by procedure-name-2.
  4. procedure-name-1, procedure-name-2 indicates a section or paragraph in the PROCEDURE DIVISION. Procedure-name-1 and procedure-name-2 may not be in a declarative section.

General Rules:

  1. Control passes between the parser and procedure-name-1. The parser generates an XML event, procedure-name-1 (or the code executed in procedure-name-1 through procedure-name-2) handles the event, and control is then returned to the parser.
  2. The processing procedure interprets the information returned from the parser, and handles it programmatically. When the processing procedure (or procedures) is complete control is returned to the XML parser.
  3. The processing procedure can terminate the run unit with a STOP RUN statement.

ON EXCEPTION phrase

An EXCEPTION condition exists when an error occurs during the XML PARSE operation. The parser signals the exception by passing control to the processing procedure and updating XML-EVENT and XML-CODE special registers. If the ON EXCEPTION phrase is specified, control passes to imperative-statement-1. For details on the XML-EVENT and XML-CODE special registers, see your IBM documentation.

NOT ON EXCEPTION phrase

If the ON EXCEPTION phrase is specified, and no EXCEPTION condition is triggered, then control passes to imperative-statement-2.

END-XML phrase

The END-XML phrase delimits the scope of both XML GENERATE and XML PARSE statements.

Nested XML statements

An XML GENERATE or XML PARSE statement located in an ON EXCEPTION imperative-statement is referred to as a nested (or conditional) XML statement. The scope of a conditional XML GENERATE or XML PARSE statement is terminated by either an END-XML phrase at the same level of nesting, or by a separator period.

Special Registers

In the control flow between the parser and the processing procedure, the parser returns control to the processing procedure, and updates the special registers XML-CODE, XML-EVENT, and XML-TEXT.

XML-CODE

  1. The XML-CODE special register is implicitly defineds as:

    01 XML-CODE PICTURE S9(9) USAGE BINARY VALUE 0.
  2. The XML-CODE special register communicates status between the XML parser and the processing procedure defined in an XML PARSE statement. The XML CODE special register also indicates whether an XML GENERATE statement executed successfully or an exception occurred dur ing XML generation.
  3. When an XML PARSE statement terminates, the special register XML-CODE is populated either with a "0" to indicate a successful operation, or with a non zero error code.
  4. Details on handling non zero error codes is detailed in the IBM Enterprise COBOL Programming Guide, in the "Handling XML Parse exceptions" chapter.LINK

XML-EVENT

  1. The XML_EVENT special register is implicitly defined as:

    01 XML-EVENT USAGE DISPLAY PICTURE X(30) VALUE SPACE.
  2. The XML-EVENT special register communicates event information from the XML parser to the processing procedure defined in an XML PARSE statement.
  3. The XML-EVENT special register is set to the name of the XML event.
  4. XML events and associated special register contents are listed in the IBM COBOL Enterprise COBOL Programming Guide.

XML-TEXT

  1. XML-TEXT is an elementary alphanumeric data item of the length of the contained XML document fragment. The length of XML-TEXT can vary from 0 to 16,777,215 bytes. There is no equivalent COBOL data description entry.
  2. The XML-TEXT special register contains document fragments that are of class alphanumeric.
  3. The XML parser sets XML-TEXT to the document fragment associated with an XML-EVENT before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item. Use the LENGTH function for XML-TEXT to determine the number of bytes that XML-TEXT contains.
  4. XML-TEXT cannot be used as a receiving item.
  5. XML EVENT's and associated XML-TEXT contents are listed in the IBM COBOL Enterprise COBOL Programming Guide.