ILE COBOL Programmer's Guide

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&apos;s best" />
  <?spread please use real mayonnaise ?>
  <meat>Ham &amp; 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:
  1. <<sandwich>>
  2. <<bread>>
  3. <<meat>>
  4. <<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:
  1. <<baker>>
  2. <<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 '&amp;', '&apos;', '&gt;', '&lt;', and '&quot;'. 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:
  1. <<Ham >>
  2. << turkey>>
  3. <<Cheese, lettuce, tomato, etc.>>
  4. <<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 '&amp;', '&apos;', '&gt;', '&lt;', and '&quot;'. 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:
  1. <<bread>>
  2. <<meat>>
  3. <<filling>>
  4. <<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 ]