The XML-CODE special register is used for the following purposes:
The XML parser sets XML-CODE prior to transferring control to the processing procedure for each event and at parser termination. You can reset XML-CODE prior to returning control from the processing procedure to the XML parser.
The XML-CODE special register has the implicit definition:
01 XML-CODE PICTURE S9(9) USAGE BINARY VALUE 0.
When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program.
When the XML parser encounters an XML event, it sets XML-CODE and then passes control to the processing procedure. For all events except an EXCEPTION event, XML-CODE contains zero when the processing procedure receives control.
For an EXCEPTION event, the parser sets XML-CODE to an exception code indicating the nature of the exception. Exception codes are detailed in the ILE COBOL Programmer's Guide.
You can set XML-CODE before returning to the parser, as follows:
If you set XML-CODE to any other value before returning to the parser, results are undefined.
When the parser returns control to the XML PARSE statement, XML-CODE contains the most recent value set either by the parser or by the processing procedure.
At termination of an XML GENERATE statement, XML-CODE contains either zero, indicating successful completion of XML generation, or a nonzero error code, indicating that an exception occurred during XML generation. XML GENERATE exception codes are detailed in the ILE COBOL Programmer's Guide.
The XML-EVENT special register is used to communicate event information from the XML parser to the processing procedure that was identified in the XML PARSE statement. Prior to passing control to the processing procedure, the XML parser sets the XML-EVENT special register to the name of the XML event, as described in Table 36.
The XML-CODE special register has the implicit definition:
01 XML-EVENT USAGE DISPLAY PICTURE X(30) VALUE SPACE.
When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program.
XML-EVENT cannot be used as a receiving data item.
Table 36. Contents of XML-EVENT and XML-TEXT or XML-NTEXT special registers
| XML event (content of XML-EVENT) | Content of XML-TEXT or XML-NTEXT |
| ATTRIBUTE-CHARACTER | The single character corresponding with the predefined entity reference in the attribute value. |
| ATTRIBUTE-CHARACTERS | The value within quotes or apostrophes. This can be a substring of the attribute value if the value includes an entity reference. |
| ATTRIBUTE-NAME | The attribute name, the string to the left of =. |
| ATTRIBUTE-NATIONAL-CHARACTER | Regardless of the type of the XML document specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty and XML-NTEXT contains the single national character corresponding with the (numeric) character reference. |
| COMMENT | The text of the comment between the opening character sequence "<!--" and the closing character sequence "-->". |
| CONTENT-CHARACTER | The single character corresponding with the predefined entity reference in the element content. |
| CONTENT-CHARACTERS | The element content between start and end tags. This can be a sub-string of the element content if the content contains an entity reference or another element. |
| CONTENT-NATIONAL-CHARACTER | Regardless of the type of the XML document specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty and XML-NTEXT contains the single national character corresponding with the (numeric) character reference. |
| DOCUMENT-TYPE-DECLARATION | The entire document type declaration including the opening and closing character sequences, "<!DOCTYPE" and ">". |
| ENCODING-DECLARATION | The value, between quotes or apostrophes, of the encoding declaration in the XML declaration. |
| END-OF-CDATA-SECTION | Always contains the string "]]>". |
| END-OF-DOCUMENT | Null, zero-length. |
| END-OF-ELEMENT | The name of the end element tag or empty element tag. |
| EXCEPTION | The part of the document successfully scanned, up to and including the point at which the exception was detected. 1 |
| PROCESSING-INSTRUCTION-DATA | The rest of the processing instruction, not including the closing sequence, "?>", but including trailing, and not leading, white space characters. |
| PROCESSING-INSTRUCTION-TARGET | The processing instruction target name, which occurs immediately after the processing instruction opening sequence, "<?". |
| STANDALONE-DECLARATION | The value, between quotes or apostrophes, of the standalone declaration in the XML declaration. |
| START-OF-CDATA-SECTION | Always contains the string "<![CDATA[". |
| START-OF-DOCUMENT | The entire document. |
| START-OF-ELEMENT | The name of the start element tag or empty element tag, also known as the element type. |
| UNKNOWN-REFERENCE-IN-CONTENT | The entity reference name, not including the "&" and ";" delimiters. |
| UNKNOWN-REFERENCE-IN-ATTRIBUTE | The entity reference name, not including the "&" and ";" delimiters. |
| VERSION-INFORMATION | The value, between quotes or apostrophes, of the version declaration in the XML declaration. This is currently always "1.0". |
Notes:
The XML-NTEXT special register is defined during XML parsing to contain document fragments that are USAGE NATIONAL.
XML-NTEXT is an elementary national data item of the length of the contained XML document fragment. The length of XML-NTEXT can vary from zero through 8,000,000 national character positions. The maximum byte length is 16,000,000.
When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program.
The parser sets XML-NTEXT to the document fragment associated with an event before transferring control to the processing procedure, in these cases:
When XML-NTEXT is set, the XML-TEXT special register has a length of zero. At any given time, only one of the two special registers XML-NTEXT and XML-TEXT has a non-zero length.
Use the LENGTH function to determine the number of national characters that XML-NTEXT contains. The LENGTH OF special register for XML-NTEXT has the number of bytes, rather than the number of national characters, contained in XML-NTEXT.
XML-NTEXT cannot be used as a receiving item.
The XML-TEXT special register is defined during XML parsing to contain document fragments that are of class alphanumeric.
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 zero through 16,000,000 bytes.
When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program.
The parser sets XML-TEXT to the document fragment associated with an event before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item, except for the ATTRIBUTE-NATIONAL-CHARACTER event and the CONTENT-NATIONAL-CHARACTER event.
When XML-TEXT is set, the XML-NTEXT special register has a length of zero. At any given time, only one of the two special registers XML-NTEXT and XML-TEXT has a non-zero length.
Use the LENGTH function or the LENGTH OF special register for XML-TEXT to determine the number of bytes that XML-TEXT contains.
XML-TEXT cannot be used as a receiving item.
+----------------------------End of IBM Extension----------------------------+
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.