Rational Developer for System z
COBOL for Windows, Version 7.5, Programming Guide


Writing procedures to process XML

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

For each event that the parser encounters, it passes information to your processing procedure in several special registers, as shown in the following table. Use these registers to populate the data structures and to control the processing.

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

Table 47. Special registers used by the XML parser
Special register Content Implicit definition and usage
XML-EVENT1,3 The name of the XML event PICTURE X(30) USAGE DISPLAY
VALUE SPACE
XML-CODE2 An exception code or zero for each XML event PICTURE S9(9) USAGE BINARY
VALUE ZERO
XML-TEXT1,4 Text (corresponding to the event that the parser encountered) from the XML document if you specify an alphanumeric item for the XML PARSE identifier Variable-length elementary category alphanumeric item; size limit of 2,147,483,646 bytes
XML-NTEXT1 Text (corresponding to the event that the parser encountered) from the XML document if you specify a national item for the XML PARSE identifier Variable-length elementary category national item; size limit of 2,147,483,646 bytes
  1. You cannot use this special register as a receiving data item.
  2. The XML GENERATE statement also uses XML-CODE. Therefore, if you code 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. The content of this special register is encoded according to the setting of the CHAR compiler option (EBCDIC, NATIVE, or S390).
  4. The content of XML-TEXT depends on the encoding of the source XML document:
    • If the source XML document is encoded in EBCDIC, the content of XML-TEXT is encoded in EBCDIC.
    • If the source XML document is encoded in ASCII in a NATIVE alphanumeric data item, the content of XML-TEXT is encoded in ASCII. You can however convert the ASCII content of XML-TEXT to EBCDIC as follows:

      Function DISPLAY-OF(Function NATIONAL-OF(XML-TEXT 819))

Restriction: 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 compiler inserts a return mechanism after the last statement in each processing procedure. You can code a STOP RUN statement in a processing procedure to end the run unit. However, an EXIT PROGRAM statement (when a CALL statement is active) or a GOBACK statement does not return control to the parser. Using either of these statements in a processing procedure results in a severe error.

Example: parsing XML

related concepts
The content of XML-CODE
The content of XML-TEXT and XML-NTEXT

related tasks
Transforming XML text to COBOL data items
Converting to or from national (Unicode) representation

related references
XML PARSE exceptions that allow continuation
XML PARSE exceptions that do not allow continuation
XML-CODE (COBOL for Windows Language Reference)
XML-EVENT (COBOL for Windows Language Reference)
XML-NTEXT (COBOL for Windows Language Reference)
XML-TEXT (COBOL for Windows Language Reference)


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)