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.
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. 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). |
|
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 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">