Rational Developer for System z
Enterprise COBOL for z/OS, Version 4.1, Programming Guide


Parsing XML documents

To parse XML documents, use the XML PARSE statement, specifying the XML document that is to be parsed and the procedure for handling XML events that occur during parsing. You can optionally specify the action to be taken after parsing finishes by coding the ON EXCEPTION phrases, as shown in the following code fragment:

XML PARSE xml-document
    PROCESSING PROCEDURE xml-event-handler
  ON EXCEPTION
     DISPLAY 'XML document error ' XML-CODE
     STOP RUN
  NOT ON EXCEPTION
     DISPLAY 'XML document was successfully parsed.'
END-XML

In the XML PARSE statement, you first identify the parse data item (xml-document in the example above) that contains the XML document character stream. In the DATA DIVISION, define the data item as an elementary data item of category national or as a national group item if the encoding of the document is Unicode UTF-16; otherwise, define the data item as an alphanumeric group item or an elementary alphanumeric data item. If the parse data item is national, the XML document must be encoded in Unicode UTF-16BE, CCSID 1200. If the parse data item is alphanumeric, its content must be encoded with one of the supported code pages listed in the related reference below regarding Coded characters sets for XML documents. See the related reference below about Understanding the encoding of XML documents for more information about code pages.

Next you specify the name of the procedure that is to handle the XML events from the document (xml-event-handler in the example above).

When the XMLPARSE(XMLSS) compiler option is in effect, you can use the ENCODING phrase of the XMLPARSE statement to specify the CCSID of the document. You can also use the RETURNING NATIONAL phrase to cause the parser to automatically convert UTF-8 or single-byte characters to national characters for return to your processing procedure.

In addition, you can specify either or both of the following phrases to receive control after parsing finishes:

You can end the XML PARSE statement with the explicit scope terminator END-XML. Use END-XML to nest an XML PARSE statement that uses the ON EXCEPTION or NOT ON EXCEPTION phrase in a conditional statement.

The parser passes control to the processing procedure for each XML event. Control returns to the parser at the end of the processing procedure. This exchange of control between the XML parser and the processing procedure continues until one of the following events occurs:

Special registers: Use the XML-EVENT special register to determine which event the parser passed 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. When the XMLPARSE(XMLSS) option is in effect, the parser also sets special register XML-NAMESPACE or XML-NNAMESPACE to the namespace identifier, if any, associated with the XML event. The parser sets the XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX special register to any associated prefix.

related concepts  
XML-CODE  

related references        
Coded character sets for XML documents    
XML-EVENT
    
XMLPARSE
    
XML PARSE statement (Enterprise COBOL Language Reference)    


Terms of use | Feedback

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