isCOBOL Evolve : Language Reference : Procedure Division Statements : XML PARSE
XML PARSE
The XML PARSE statement parses an XML document into its individual pieces and passes each piece, one at a time, to a user-written processing procedure.
General Format
XML PARSE Xml-Stream PROCESSING PROCEDURE IS Procedure-Name-1
                               [ { THROUGH } Procedure-Name-2 ]
                                 { THRU }
 
  [ ON EXCEPTION Imperative-Statement-1 ]
 
  [ NOT ON EXCEPTION Imperative-Statement-2 ]
[END-XML]
Syntax Rules
1. Xml-Stream must reference an elementary data item of category alphanumeric, an alphanumeric group item or an elementary data item of category national. If it references an alphanumeric group item, then it is treated as though it were an elementary data item of category alphanumeric.
2. Procedure-Name-1 is the first or only section or paragraph in the processing procedure.
3. Procedure-Name-2 is the last section or paragraph in the processing procedure.
General Rules
1. The processing procedure consists of the statements at which XML events are handled. The range of the processing procedure also includes all statements executed by CALL, EXIT, GO TO, GOBACK, and PERFORM statements in the range of the processing procedure.
2. The processing procedure must not directly execute an XML PARSE statement. However, if the processing procedure passes control to another program by using a CALL statement, the target program can execute the same or a different XML PARSE statement. A program executing on multiple threads can execute the same XML statement or different XML statements simultaneously.
3. An exception condition occurs when the XML parser detects an error in processing the XML document. The parser first signals an exception XML event by passing control to the processing procedure with special register XML-EVENT set to contain 'EXCEPTION'. If the XML processing procedure handles the exception XML event and sets XML-CODE to zero before returning control to the parser, the exception condition no longer exists. If no other unhandled exceptions occur prior to the termination of the parser, control is transferred to Imperative-Statement-2 of the NOT ON EXCEPTION phrase, if specified.
4. If an exception condition does not exist at termination of XML PARSE processing, control is transferred to Imperative-Statement-2 if the NOT ON EXCEPTION clause is specified. Otherwise control is transferred to the end of the XML PARSE statement.
Note: Unlike the IBM implementation of XML PARSE, isCOBOL doesn’t return VERSION-INFORMATION and STANDALONE-DECLARATION events.
Examples
Parse a simple XML, display it and use some key data from it
 working-storage section.
 01 xml-document.
    02 pic x(36) value '<?xml version="1.0" encoding="utf-8"'.
    02 pic x(19) value ' standalone="yes"?>'.
    02 pic x(39) value '<!--This document is just an example-->'.
    02 pic x(10) value '<sandwich>'.
    02 pic x(35) value '  <bread type="baker&apos;s best"/>'.
    02 pic x(41) value '  <?spread please use real mayonnaise  ?>'.
    02 pic x(31) value '  <meat>Ham &amp; turkey</meat>'.
    02 pic x(40) value '  <filling>Cheese, lettuce, tomato, etc.'.
    02 pic x(10) value '</filling>'.
    02 pic x(35) value '  <![CDATA[We should add a <relish>'.
    02 pic x(22) value ' element in future!]]>'.
    02 pic x(31) value '  <listprice>$4.99 </listprice>'.
    02 pic x(27) value '  <discount>0.10</discount>'.
    02 pic x(15) value '</sandwich>'.
 
 01 xml-document-length computational pic 999.
 
 01 my-msg                    pic x(30).
 01 current-element           pic x(30).
 01 xfr-ed                    pic x(9) justified.
 01 xfr-ed-1 redefines xfr-ed pic 999999.99.
 01 list-price computational  pic 9v99 value 0.
 01 discount computational    pic 9v99 value 0.
 01 display-price             pic $$9.99.
 01 prom-price                pic $$9.99.
 
procedure division.
 main.
   display  xml-document
   xml parse xml-document processing procedure xml-handler
       on exception     display 'XML document error ' xml-code x'0d0a' xml-errmsg
       not on exception display 'XML document successfully parsed'
   end-xml  
   move list-price to display-price
   compute prom-price = list-price * (1 - discount)
   display 'Information from XML ' x'0d0a'
           '  Sandwich list price: ' display-price x'0d0a'
           '  Promotional price:   ' prom-price
   end-display
   goback.
xml-handler.
   evaluate xml-event
     when 'DOCUMENT-TYPE-DECLARATION ' display 'Doc type decl: ' XML-TEXT
     when 'START-OF-ELEMENT'
       display 'Start element tag: <' XML-TEXT '>'
       move XML-TEXT to current-element
     when 'CONTENT-CHARACTERS'
       display 'Content characters: <' XML-TEXT '>'
       evaluate current-element
         when 'listprice' compute list-price = function numval-c(XML-TEXT)
         when 'discount'
           move XML-TEXT to xfr-ed
           move xfr-ed-1 to discount
       end-evaluate
     when 'END-OF-ELEMENT'
       display 'End element tag: <' XML-TEXT '>'
       move spaces to current-element
     when 'START-OF-DOCUMENT'
       compute xml-document-length = function length(XML-TEXT)
       display 'Start of document: length=' xml-document-length
           ' characters.'
     when 'END-OF-DOCUMENT' display 'End of document.'
     when 'VERSION-INFORMATION' display 'Version: <' XML-TEXT '>'
     when 'ENCODING-DECLARATION' display 'Encoding: <' XML-TEXT '>'
     when 'STANDALONE-DECLARATION' display 'Standalone: <' XML-TEXT '>'
     when 'ATTRIBUTE-NAME' display 'Attribute name: <' XML-TEXT '>'
     when 'ATTRIBUTE-CHARACTERS' display 'Attribute value characters: <' XML-TEXT '>'
     when 'ATTRIBUTE-CHARACTER' display 'Attribute value character: <' XML-TEXT '>'
     when 'START-OF-CDATA-SECTION' display 'Start of CData: <' XML-TEXT '>'
     when 'END-OF-CDATA-SECTION' display 'End of CData: <' XML-TEXT '>'
     when 'CONTENT-CHARACTER' display 'Content character: <' XML-TEXT '>'
     when 'PROCESSING-INSTRUCTION-TARGET' display 'PI target: <' XML-TEXT '>'
     when 'PROCESSING-INSTRUCTION-DATA' display 'PI data: <' XML-TEXT '>'
     when 'COMMENT' display 'Comment: <' XML-TEXT '>'
     when 'EXCEPTION'
       compute xml-document-length = 
                 function length (XML-TEXT)
      move  XML-TEXT (xml-document-length - 5:10) to  my-msg
      display 'Exception ' XML-CODE ' at offset '
          xml-document-length ':' xml-errmsg ':' my-msg
     when other display 'Unexpected XML event: ' XML-EVENT '.'
   end-evaluate.