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:
The parser uses the following special registers when XMLPARSE(COMPAT) is in effect:
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 XMLPARSE 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.
| 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. | 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 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 | n/a5
(A numeric character reference that has no corresponding code point in the target coded character set is replaced with hyphen-minus.) |
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 reference2. |
| COMMENT | XML-TEXT or XML-NTEXT contains the text of the comment between the opening character sequence "<!--" and the closing character sequence "-->". | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS). |
| 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. | 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 an entity reference or another element. |
| CONTENT-NATIONAL-CHARACTER | n/a5
(A numeric character reference that has no corresponding code point in the target coded character set is replaced with hyphen-minus.) |
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. |
| 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 error 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. | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS). |
| PROCESSING-INSTRUCTION-TARGET | XML-TEXT or XML-NTEXT contains the processing instruction target name, which occurs immediately after the processing instruction opening sequence, "<?". | XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS). |
| 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 | 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 might signal event UNRESOLVED-REFERENCE instead. |
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). |
|
||
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).
If the XML document does not contain a document type declaration (<!DOCTYPE ...>), an unresolved entity reference in character content results in an EXCEPTION XML event. To cause the parser to signal an UNRESOLVED-REFERENCE event for an unresolved reference in character data, instead of an EXCEPTION event, include at least a minimal document type declaration in the XML document; for example:
<!DOCTYPE rootName>The parser always signals an EXCEPTION XML event for unresolved references in attribute values, even when the document includes a document type declaration.