XML-EVENT

The XML-EVENT special register communicates event information from the XML parser to the processing procedure identified in the XML PARSE statement.

Before passing control to the processing procedure, the XML parser sets the XML-EVENT special register to the name of the XML event. The specific events and the associated special registers that are set depend on the setting of the XMLPARSE compiler option, XMLPARSE(XMLSS) or XMLPARSE(COMPAT).

The parser uses the following special registers when XMLPARSE(XMLSS) is in effect:

  • XML-CODE
  • XML-EVENT
  • XML-TEXT or XML-NTEXT
  • XML-NAMESPACE or XML-NNAMESPACE
  • XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX

The parser uses the following special registers when XMLPARSE(COMPAT) is in effect:

  • XML-CODE
  • XML-EVENT
  • XML-TEXT or XML-NTEXT

The parser sets XML-NTEXT to associated XML text when the XML document is in a national data item, and sets XML-TEXT when the XML document is in an alphanumeric data item. When the XMLPARSE(COMPAT) compiler option is in effect, the parser sets XML-NTEXT to the text of any numeric character reference (for events ATTRIBUTE-NATIONAL-CHARACTER and CONTENT-NATIONAL-CHARACTER) regardless of the type of the XML document data item.

When the XMLPARSE(XMLSS) compiler option is in effect, the parser sets XML-NNAMESPACE and XML-NNAMESPACE-PREFIX when the XML document is in a national data item and when the RETURNING NATIONAL phrase is specified in the XML PARSE statement; otherwise, the parser sets XML-NAMESPACE and XML-NAMESPACE-PREFIX.

Table 1 shows XML events and special register contents for parsing with the XMLPARSE(XMLSS) and XMLPARSE(COMPAT) options.

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.

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

Table 1. XML events and associated special register contents
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1
ATTRIBUTE-CHARACTER n/a5 XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the attribute value.
ATTRIBUTE-CHARACTERS XML-TEXT or XML-NTEXT contains the value within quotation marks or apostrophes. This can be a substring of the attribute value. XML-TEXT or XML-NTEXT contains the value within quotation marks or apostrophes. This can be a substring of the attribute value if the value includes a character reference or an entity reference.
ATTRIBUTE-NAME For attribute names that are not in a namespace, XML-TEXT or XML-NTEXT contains the attribute name.

For attributes with names in a nondefault namespace, attribute names are always prefixed and have the form: prefix:local-part = "AttValue".

XML-TEXT or XML-NTEXT contains the local-part, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier, and XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix.

XML-TEXT or XML-TEXT contains the attribute name (the string to the left of the equal sign).
ATTRIBUTE-NATIONAL-CHARACTER Regardless of the type of the XML document, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that correponds with the numeric character reference. 2 XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
COMMENT XML-TEXT or XML-NTEXT contains the text of the comment between the opening character sequence "<!--" and the closing character sequence "-->". This can be a substring of the text. XML-TEXT or XML-NTEXT always contains the complete text of the comment.
CONTENT-CHARACTER n/a5 XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the element content.
CONTENT-CHARACTERS XML-TEXT or XML-NTEXT contains the character content of the element between start and end tags. This can be a substring of the content. XML-TEXT or XML-NTEXT contains the character content of the element between start and end tags. This can be a substring of the character content if the content includes a character reference or an entity reference.
CONTENT-NATIONAL-CHARACTER Regardless of the type of the XML document, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that corresponds with the numeric character reference.2 XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
DOCUMENT-TYPE-DECLARATION XML-TEXT or XML-NTEXT contains the name of the root element, as specified in the document type delcaration. XML-TEXT or XML-NTEXT contains the entire document type declaration, including the opening and closing character sequences "<!DOCTYPE" and ">".
ENCODING-DECLARATION XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes, of the encoding declaration in the XML declaration. XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
END-OF-CDATA-SECTION All XML special registers except XML-CODE and XML-EVENT are empty with length zero. XML-TEXT or XML-NTEXT contains the string "]]>".
END-OF-DOCUMENT All XML special registers except XML-CODE and XML-EVENT are empty with length zero. XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
END-OF-ELEMENT XML-TEXT or XML-NTEXT contains the local part of the end element tag or empty element tag name.

If the element name is in a nondefault namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier.

If the element name is in a namespace and is prefixed (of the form prefix:local-part), XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix.

XML-TEXT or XML-NTEXT contains the name of the end element tag or empty element tag.
END-OF-INPUT All XML special registers except XML-CODE and XML-EVENT are empty with length zero.

To parse an additional segment of an XML document, move the next segment to identifier-1 and set XML-CODE to 1.

n/a6
EXCEPTION XML-CODE contains the unique return code and reason code that identifies the exception.

XML-TEXT or XML-NTEXT contains the document fragment up to the point of the error or anomaly that caused the exception.4

All other XML special registers are empty with length zero.

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

XML-TEXT or XML-NTEXT contains the part of the document that was successfully scanned, up to and including the point at which the exception was detected.

NAMESPACE-DECLARATION XML-TEXT and XML-NTEXT are both empty with length zero.

XML-NAMESPACE or XML-NNAMESPACE contains the declared namespace identifier. If the namespace is "undeclared" by specifying the empty string, XML-NAMESPACE and XML-NNAMESPACE are empty with length zero.

XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix if the namespace declaration is of the form xmlns:prefix = "namespace-identifier"; otherwise, if the declaration is for the default namespace and thus the attribute name is xmlns, XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX are both empty with length zero.

n/a6

(ATTRIBUTE-NAME and ATTRIBUTE-CHARACTERS events are signaled instead.)

PROCESSING-INSTRUCTION-DATA XML-TEXT or XML-NTEXT contains the rest of the processing instruction (after the target name), not including the closing sequence "?>", but including trailing, and not leading, white space characters. This can be a substring of the processing instruction data. XML-TEXT or XML-NTEXT always contains the complete processing instruction data.
PROCESSING-INSTRUCTION-TARGET XML-TEXT or XML-NTEXT contains the processing instruction target name, which occurs immediately after the processing instruction opening sequence, "<?". This event can occur multiple times for a given processing instruction: one occurrence preceding each substring of the data. XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS). This event occurs only once for a given processing instruction.
STANDALONE-DECLARATION XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes ("yes" or "no"), of the stand-alone declaration in the XML declaration. XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
START-OF-CDATA-SECTION All XML special registers except XML-CODE and XML-EVENT are empty with length zero. XML-TEXT or XML-NTEXT contains the string "<![CDATA[".
START-OF-DOCUMENT All XML special registers except XML-CODE and XML-EVENT are empty with length zero. XML-TEXT or XML-NTEXT contains the entire document.
START-OF-ELEMENT XML-TEXT or XML-NTEXT contains the local part of the start element tag name or the local part of the empty element tag name.

If the element name is in a namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier.

If the element name is in a namespace and is prefixed (of the form prefix:local-part, XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix.

XML-TEXT or XML-NTEXT contains the name of the start element tag or empty element tag, also known as the element type.
UNKNOWN-REFERENCE-IN-ATTRIBUTE n/a5

For XMLPARSE(XMLSS), the parser always signals EXCEPTION.

XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
UNKNOWN-REFERENCE-IN-CONTENT n/a5

For XMLPARSE(XMLSS), the parser signals UNRESOLVED-REFERENCE or EXCEPTION instead.

See "Unresolved references" below for additional details.

XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
UNRESOLVED-REFERENCE XML-TEXT or XML-NTEXT contains the entity name from XML content, not including the "&" and ";" delimiters.

See "Unresolved references" below for additional details.

n/a6

(The parser signals UNKNOWN-REFERENCE-IN-CONTENT instead.)

VERSION-INFORMATION XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes, of the version information in the XML declaration. XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
  1. For all events except EXCEPTION, XML-CODE contains zero. Unless stated otherwise, the namespace XML registers (XML-NAMESPACE, XML-NNAMESPACE, XML-NAMESPACE-PREFIX, and XML-NNAMESPACE-PREFIX) are empty and have length zero.
  2. 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.
  3. For XMLPARSE(COMPAT), 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 PARSE exceptions with XMLPARSE(COMPAT) in effect in the Enterprise COBOL Programming Guide for information about XML exception codes.
  4. If an END-OF-INPUT XML event previously occurred and the processing procedure provided a new document segment, XML-TEXT or XML-NTEXT contains only the new segment.

    If the anomaly occurs before parsing begins (for example, the encoding specification is invalid), XML-TEXT or XML-NTEXT are empty with length zero.

    The fragment might or might not include the anomaly. For a duplicate attribute name, for example, the fragment includes the incorrect attribute. For an invalid character, the fragment includes document text up to, but not including, the invalid character.

  5. n/a. Not applicable; occurs only with XMLPARSE(COMPAT).
  6. n/a. Not applicable; occurs only wtih XMLPARSE(XMLSS).

Unresolved References:

An unresolved entity reference is a reference to the name of an entity that has no declaration in the document type definition (DTD).

The parser signals an UNRESOLVED-REFERENCE event only if all of the following conditions are true:
  • The unresolved reference is within element content, not an attribute value.
  • The XML document starts with an XML declaration that specifies standalone="no".
  • The XML document contains a document type declaration, for example,
    <!DOCTYPE rootElementName> 
    
  • If the VALIDATING phrase is specified on the XML PARSE statement, the document type declaration must also specify an external DTD subset, for example:
    <!DOCTYPE rootElementName SYSTEM "someOther.dtd"> 
    
Otherwise the parser signals an EXCEPTION event instead of UNRESOLVED-REFERENCE.