Processing XML events
Use the XML-EVENT special register to determine the event that the parser passes
to your processing procedure. XML-EVENT contains
an event name such as 'START-OF-ELEMENT'. The
parser passes the content for the event in special register XML-TEXT or XML-NTEXT, depending on the type
of the XML identifier in your XML PARSE statement.
The events are shown in basically the order that they would occur for this
sample XML document. The text shown under "Sample XML text" comes
from this sample; exact text is shown between these delimiters: <<>>:
<?xml version="1.0" encoding="ibm-1140" standalone="yes" ?>
<!--This document is just an example-->
<sandwich>
<bread type="baker's best" />
<?spread please use real mayonnaise ?>
<meat>Ham & turkey</meat>
<filling>Cheese, lettuce, tomato, etc.</filling>
<![CDATA[We should add a <relish> element in future!]]>
</sandwich>junk
- START-OF-DOCUMENT
-
- Description
- Occurs once, at the beginning of parsing the document. XML text is the
entire document, including any line-control characters, such as LF (Line Feed)
or NL (New Line).
- Sample XML text
- The text for this sample is 336 characters in length.
-
-
- VERSION-INFORMATION
-
- Description
- Occurs within the optional XML declaration for the version information.
XML text contains the version value. An XML declaration is XML text that specifies the version of XML being used and the encoding
of the document.
- Sample XML text
- <<1.0>>
-
-
- ENCODING-DECLARATION
-
- Description
- Occurs within the XML declaration for the optional encoding declaration.
XML text contains the encoding value.
- Sample XML text
- <<ibm-1140>>
-
-
- STANDALONE-DECLARATION
-
- Description
- Occurs within the XML declaration for the optional standalone declaration.
XML text contains the standalone value.
- Sample XML text
- <<yes>>
-
-
- DOCUMENT-TYPE-DECLARATION
-
- Description
- Occurs when the parser finds a document type declaration (DTD). Document
type declarations begin with the character sequence '<!DOCTYPE' and end
with a '>' character, with some fairly complicated grammar rules describing
the content in between. (See the XML specification for details.)
For this event, XML text contains the entire declaration, including the opening
and closing character sequences. This is the only event where XML text includes
the delimiters.
- Sample XML text
- The sample does not have a document type declaration.
-
-
- COMMENT
-
- Description
- Occurs for any comments in the XML document. XML text contains the data
between the opening and closing comment delimiters, '<!--' and '-->', respectively.
- Sample XML text
- <<This document is just an example>>
-
-
- START-OF-ELEMENT
-
- Description
- Occurs once for each element start tag or empty element tag. XML text
is set to the element name.
- Sample XML text
- In the order that they occur as START-OF-ELEMENT events:
- <<sandwich>>
- <<bread>>
- <<meat>>
- <<filling>>
-
-
- ATTRIBUTE-NAME
-
- Description
- Occurs for each attribute in an element start tag or empty element tag,
after recognizing a valid name. XML text contains the attribute name.
- Sample XML text
- <<type>>
-
-
- ATTRIBUTE-CHARACTERS
-
- Description
- Occurs for each fragment of an attribute value. XML text contains the
fragment. An attribute value normally consists of a single string only, even
if it is split across lines. The attribute value might consist of multiple
events, however.
- Sample XML text
- In the order that they occur as ATTRIBUTE-CHARACTERS events:
- <<baker>>
- <<s best>>
Notice that the value of the 'type' attribute in the sample consists
of three fragments: the string 'baker', the single character ''', and the
string 's best'. The single character ''' fragment is passed separately as
an ATTRIBUTE-CHARACTER event.
-
-
- ATTRIBUTE-CHARACTER
-
- Description
- Occurs in attribute values for the predefined entity references '&',
''', '>', '<', and '"'. See the XML specification for details of predefined entities.
- Sample XML text
- <<'>>
-
-
- ATTRIBUTE-NATIONAL-CHARACTER
-
- Description
- Occurs in attribute values for numeric character references (Unicode
code points or "scalar values") of the form '&#dd..;' or '&#hh..;',
where 'd' and 'h' represent decimal and hexadecimal digits, respectively.
- Sample XML text
- The sample does not contain a numeric character reference.
-
-
- PROCESSING-INSTRUCTION-TARGET
-
- Description
- Occurs when the parser recognizes the name following the processing
instruction (PI) opening character sequence, '<?'. PIs allow XML documents to contain special instructions for applications.
- Sample XML text
- <<spread>>
-
-
- PROCESSING-INSTRUCTION-DATA
-
- Description
- Occurs for the data following the PI target, up to but not including
the PI closing character sequence, '?>'. XML text
contains the PI data, which includes trailing, but not leading white space
characters.
- Sample XML text
- <<please use real mayonnaise >>
-
-
- CONTENT-CHARACTERS
-
- Description
- This event represents the principal part of an XML document: the character
data between element start and end tags. XML text contains this data, which
usually consists of a single string only, even if it is split across lines.
If the content of an element includes any references or other elements, the
complete content might consist of several events. The parser also uses the CONTENT-CHARACTERS event to pass the text of CDATA
sections to your program.
- Sample XML text
- In the order that they occur as CONTENT-CHARACTERS events:
- <<Ham >>
- << turkey>>
- <<Cheese, lettuce, tomato, etc.>>
- <<We should add a <relish> element in
future!>>
Notice that the content of the 'meat' element in the sample consists
of the string 'Ham ', the character '&' and the string ' turkey'. The
single character '&' fragment is passed separately as a CONTENT-CHARACTER event. Also notice the trailing and leading spaces,
respectively, in these two string fragments.
-
-
- CONTENT-CHARACTER
-
- Description
- Occurs in element content for the predefined entity references '&',
''', '>', '<', and '"'. See the XML specification for details of predefined entities.
- Sample XML text
- <<&>>
-
-
- CONTENT-NATIONAL-CHARACTER
-
- Description
- Occurs in element content for numeric character references (Unicode
code points or "scalar values") of the form '&#dd..;' or '&#hh..;',
where 'd' and 'h' represent decimal and hexadecimal digits, respectively.
- Sample XML text
- The sample does not contain a numeric character reference.
-
-
- END-OF-ELEMENT
-
- Description
- Occurs once for each element end tag or empty element tag when the parser
recognizes the closing angle bracket of the tag. XML text contains the element
name.
- Sample XML text
- In the order that they occur as END-OF-ELEMENT events:
- <<bread>>
- <<meat>>
- <<filling>>
- <<sandwich>>
-
-
- START-OF-CDATA-SECTION
-
- Description
- Occurs at the start of a CDATA section. CDATA sections begin with the
string '<![CDATA[' and end with the string ']]>'. Such
sections are used to "escape" blocks of text containing characters
that would otherwise be recognized as XML markup. XML text always contains
the opening character sequence '<![CDATA['. The parser passes the content
of a CDATA section between these delimiters as a single CONTENT-CHARACTERS event.
- Sample XML text
- <<<![CDATA[>>
-
-
- END-OF-CDATA-SECTION
-
- Description
- Occurs when the parser recognizes the end of a CDATA section.
- Sample XML text
- <<]]>>>
-
-
- UNKNOWN-REFERENCE-IN-ATTRIBUTE
-
- Description
- Occurs within attribute values for entity references other than the
five predefined entity references, as shown for ATTRIBUTE-CHARACTER above.
- Sample XML text
- The sample does not have any unknown entity references.
-
-
- UNKNOWN-REFERENCE-IN-CONTENT
-
- Description
- Occurs within element content for entity references other than the predefined
entity references, as shown for CONTENT-CHARACTER above.
- Sample XML text
- The sample does not have any unknown entity references.
-
-
- END-OF-DOCUMENT
-
- Description
- Occurs when document parsing has completed
- Sample XML text
- XML text is empty for the END-OF-DOCUMENT event.
-
-
- EXCEPTION
-
- Description
- Occurs when an error in processing the XML document is detected. For
encoding conflict exceptions, which are signaled before parsing begins, XML-TEXT is either zero-length or contains just the
encoding declaration value from the document.
- Sample XML text
- The part of the document that was parsed up to and including the point
where the exception (the superfluous 'junk' after the <sandwich> element
end tag) was detected.
-
-
related reference
XML-EVENT (ILE COBOL Language Reference)
4.6 Predefined entities (XML specification at www.w3.org/TR/REC-xml#sec-predefined-ent)
2.8 Prolog and document type declaration (XML specification at
www.w3.org/TR/REC-xml#sec-prolog-dtd)
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.