Writing procedures to process XML

In your processing procedure, code statements to handle XML events.

For each event that the parser encounters, the parser passes information to the processing procedure in several special registers. Use the content of those special registers to populate COBOL data structures and to control the processing.

Examine the XML-EVENT special register to determine which event the parser passed to the processing procedure. XML-EVENT contains an event name, such as 'START-OF-ELEMENT'. Obtain the text associated with the event from the XML-TEXT or XML-NTEXT special register.

If the XMLPARSE(XMLSS) option is in effect, you can use special register XML-NAMESPACE or XML-NNAMESPACE to determine the namespace identifier, if any, that is associated with the XML event, and examine the XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX special register to determine the associated prefix, if any.

When used in nested programs, the XML special registers are implicitly defined as GLOBAL in the outermost program.

For additional details about the XML special registers, see the following table.

Table 1. Special registers used by the XML parser
Special register Implicit definition and usage Content
XML-EVENT1

PICTURE X(30) USAGE DISPLAY VALUE SPACE
The name of the XML event
XML-CODE2

PICTURE S9(9) USAGE BINARY VALUE ZERO
An exception code or zero for each XML event
XML-INFORMATION1

PICTURE S9(9) USAGE BINARY VALUE 0
A mechanism to easily determine whether an XML EVENT is complete
XML-TEXT1 Variable-length elementary category alphanumeric item Text (corresponding to the event that the parser encountered) from the XML document if you specify an alphanumeric item for the XML PARSE identifier3
XML-NTEXT1 Variable-length elementary category national item Text (corresponding to the event that the parser encountered) from the XML document if you specify a national item for the XML PARSE identifier3
XML-NAMESPACE1, 4 Variable-length elementary category alphanumeric item The namespace identifier for a NAMESPACE-DECLARATION XML event or for an element or attribute name that is in a namespace, if the XML document is in an alphanumeric data item3
XML-NNAMESPACE1, 4 Variable-length elementary category national item The namespace identifier for a NAMESPACE-DECLARATION XML event or for an element or attribute name that is in a namespace, if the XML document is in a national data item or the RETURNING NATIONAL phrase is specified in the XML PARSE statement
XML-NAMESPACE-PREFIX1, 4 Variable-length elementary category national item The prefix, if any, for a NAMESPACE-DECLARATION XML event or for an element or attribute name that is in a nondefault namespace, if the XML document is in an alphanumeric data item3
XML-NNAMESPACE-PREFIX1, 4 Variable-length elementary category national item The prefix, if any, for a NAMESPACE-DECLARATION XML event or for an element or attribute name that is in a nondefault namespace, if the XML document is in a national data item or the RETURNING NATIONAL phrase is specified in the XML PARSE statement
  1. You cannot use this special register as a receiving data item.
  2. The XML GENERATE statement also uses XML-CODE. Therefore, if you have an XML GENERATE statement in the processing procedure, save the value of XML-CODE before the XML GENERATE statement, and restore the saved value after the XML GENERATE statement.
  3. If you specify the RETURNING NATIONAL phrase in the XML PARSE statement for an alphanumeric data item, text is returned in the corresponding national special register. You can specify the RETURNING NATIONAL phrase only if the XMLPARSE(XMLSS) option is in effect.
  4. The parser sets the namespace special registers only if the XMLPARSE(XMLSS) option is in effect.

Restrictions:

  • A processing procedure must not directly execute an XML PARSE statement. However, if a processing procedure passes control to a method or outermost program by using an INVOKE or CALL statement, the target method or program can execute the same or a different XML PARSE statement. You can also execute the same XML statement or different XML statements simultaneously from a program that is running on multiple threads.
  • The range of the processing procedure must not cause the execution of any GOBACK or EXIT PROGRAM statement, except to return control from a method or program to which control was passed by an INVOKE or CALL statement, respectively, that is executed in the range of the processing procedure.

    You can code a STOP RUN statement in a processing procedure to end the run unit.

The compiler inserts a return mechanism after the last statement in each processing procedure.

Example: program for processing XML

related concepts    
XML events  
XML-CODE  
XML-TEXT and XML-NTEXT  
XML-NAMESPACE and XML-NNAMESPACE  
XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX  

related tasks  
Parsing XML documents one segment at a time  
Parsing XML documents with validation  
Terminating XML parsing  

related references  
XMLPARSE (compiler option)  
XML-EVENT (Enterprise COBOL for z/OS® Language Reference)