Rational Developer for System z
Enterprise COBOL for z/OS, Version 4.1, Language Reference


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:

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.

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

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.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)