ILE COBOL Programmer's Guide
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.
-
-
- 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.
- Sample XML text
- <<bread>>
-
-
- 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)
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.