XML-EVENT

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 1.

XML-EVENT 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.

The content of XML-EVENT is encoded in the EBCDIC or ASCII code page in effect at run time, depending on the setting of the CHAR compiler option (EBCDIC, NATIVE, or S390).

XML-EVENT cannot be used as a receiving data item.

Table 1. 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 that corresponds with the predefined entity reference in the attribute value
ATTRIBUTE-CHARACTERS The value within quotation marks 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 the equal sign
ATTRIBUTE-NATIONAL-CHARACTER Regardless of the type of the XML document specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that corresponds 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 that corresponds with the predefined entity reference in the element content
CONTENT-CHARACTERS The character content of the element between start and end tags. This can be a substring of the character content if the content includes 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 with length zero and XML-NTEXT contains the single national character that corresponds with the numeric character reference.1
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 The string "]]>"
END-OF-DOCUMENT Empty with length zero
END-OF-ELEMENT The name of the end element tag or empty element tag
EXCEPTION The part of the document that was successfully scanned, up to and including the point at which the exception was detected.2

Special register XML-CODE contains the unique error code that identifies the exception.

PROCESSING-INSTRUCTION-DATA The rest of the processing instruction (after the target name), 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 quotation marks or apostrophes ("yes" or "no"), of the stand-alone declaration in the XML declaration
START-OF-CDATA-SECTION 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 quotation marks or apostrophes, of the version information in the XML declaration
  1. National characters with scalar values greater than 65,535 (NX"FFFF") are represented using two encoding units (a "surrogate pair"). Programmers are responsible for ensuring that operations on the content of XML-NTEXT do not split the pair of encoding units that together form a graphic character, thereby forming invalid data.
  2. Exceptions for encoding conflicts are signaled before parsing begins. For these exceptions, XML-TEXT or XML-NTEXT is either zero length or contains only the encoding declaration value from the document. See XML GENERATE Exceptions in the COBOL for Linux® on x86 Programming Guide for information about XML exception codes.