XML PARSE statement

Function

The XML PARSE statement parses an XML document sequentially into its syntax units. Data on known units is available for further processing in special registers in a processing procedure.

Format

---

XML PARSE identifier-1

  PROCESSING PROCEDURE IS procedure-name-1 [{THRU | THROUGH} procedure-name-2]

  [ON EXCEPTION imperative-statement-1]

  [NOT ON EXCEPTION imperative-statement-2]

  [END-XML]

---

Syntax rules

1. identifier-1 must be an alphanumeric or national data item.
2. identifier-1 may not be a function identifier.
3. If both procedure-name-1 and procedure-name-2 are specified and one of these is the name of a procedure within declarative sections, the other procedure name must be contained within the same declarative section.

General rules

1. While the XML PARSE statement is executed, identifier-1 contains the document to be parsed.
2. If the content of identifier-1 is modified while the XML PARSE statement is being executed, the further behavior is undefined.
3. When the XML PARSE statement is executed, control is transferred to the parser, which parses the document and makes the syntax units available to the program as 'events' in special registers.
4. The PROCESSING PROCEDURE specification defines the processing procedure to which the parser transfers control for every 'event' while the XML statement is being executed. The processing procedure is executed as if it were activated by the parser using PERFORM.
5. The processing procedure may not be exited using EXIT PROGRAM, EXIT METHOD or GOBACK. When the processing procedure’s last statement has been executed, control is automatically returned to the parser.
6. If the parser detects an error while it is parsing an XML document, it transfers control to the processing procedure with the 'EXCEPTION' event in the XML-EVENT special register. The XML-CODE special register then contains the value of the extended I-O status, see the "COBOL2000 User Guide" [1], section 10.6 "Extended I-O status for XML statements (CBX code).” With all other events the XML-CODE special register has the value 0.

7. The content of the XML-CODE special register XML-CODE when the processing procedure is exited controls how the XML PARSE statement is continued. The processing procedure can signal how it wants the statement to be continued by setting the appropriate values:

    

   Values of XML CODE special register at the end of the processing procedure	Value of XML-EVENT special register at the start of the processing procedure
   	EXCEPTION	Other event
   0	Attempt to continue the statement1	Continuation of the statement
   -1	Immediate termination of the statement with 'error'	Immediate termination of the statement with 'error'
   Unchanged error code	Immediate termination of the statement with 'error'	–
   Other value	Further behavior undefined	Further behavior undefined

   ¹Continuation is, however, only possible in the case of 'minor' errors and is then generally restricted to the search for further errors. When 'serious' errors occur, the XML statement is nevertheless always terminated with ’error’.

   Values which are not equal to -1 will in future be assigned their own semantics. On account of this, do not set any values which are not equal to -1.
8. After control is returned from the parser, the XML-CODE special register contains the value which it had the last time it exited the processing procedure.
9. If parsing of the document is completed without an error, imperative-statement-2 (if it is specified) is executed when control is returned from the parser and the end of the XML PARSE statement is branched to.
10. If the XML PARSE statement was terminated with 'error', imperative-statement-1 (if it is specified) is executed when control is returned from the parser and the end of the XML PARSE statement is branched to.