Chapter 1: Using XML and COBOL Together

This chapter describes support for XML including an explanation of XML, XML schemas, and how XML fits in with COBOL.


Your COBOL development system makes it easy to harness the power of XML data exchange with existing and new COBOL applications.

XML syntax extensions augment the COBOL syntax already supported. The extensions support a full range of syntax for manipulating XML documents, and are processed using the XML preprocessor. See the chapter XML Syntax Extensions for more information.

The cbl2xml command-line utility and the CBL2XML Wizard enable you to:

For detailed information on cbl2xml, see the chapter Generating COBOL Structures with XML Syntax.

Whether you do the process manually or with the aid of cbl2xml, the process of XML-enabling a COBOL application consists of:

If you would like to read a brief overview of XML technology, see the section XML in Brief later in this chapter.

XML Implementation

XML data encoding is record based and the vast majority of possible encodings can easily be represented as COBOL data records. For example:

Example 1-1: XML Data Received in a COBOL Record

This XML stream:

<?xml version="1.0"?>
<group elementNumber=1235 >
   <elementAlpha>Alpha value</elementAlpha>

Can be received directly by COBOL code using syntax extensions as follows:

01  xmls-group                    identified by "group".
    05  xmls-Number     pic 9(18) identified by 
        "elementNumber" is attribute.
    05  xmls-Alpha      pic x(80) identified by 

This is a simple example. However, we support a number of more complex syntax scenarios, including variable tag specifications, non-regular and nested occurrences, mixed data, and optional elements.

Once you are able to encode XML records in your application, you can originate or receive these records in your COBOL application. Do this using standard file input/output verbs including OPEN, READ, WRITE, and CLOSE. The run-time support automatically converts, encodes, and performs all of the necessary I/O. For example, the following code is all that is necessary to generate the XML stream depicted in Example 1-1 into the file out-xml:

     select xml-stream assign "out.xml"
           organization  is xml   
           document-type is "group"
           file status is xml-bookdb-status.
     xd xml-stream.
     01  xmls-group                identified by "group".
         05  xmls-Number pic 9(18) 
             identified by "elementNumber" is attribute.
         05  xmls-Alpha  pic x(80) 
             identified by "elementAlpha".
     working-storage section.
     01  xml-bookdb-status         pic s9(9) comp.
     move 1235                     to xmls-Number
     move "Alpha value"            to xmls-Alpha
     open output xml-stream
     write xmls-group
     close xml-stream
     stop run.


We fully support the IBM syntax for XML handling, known as XML PARSE.

The XML PARSE statement provides a mechanism for processing XML. The statement causes XML document data to be split into component fragments by the system's XML parser, and to be made available to a user-defined routine. Each fragment is labeled with a tag or "event" to indicate the nature of the fragment.

Special Registers

Communication between the parser and the user routine is handled through four special registers:

For more information on these special registers see the Special Registers section of the Concepts of the COBOL Language chapter of your Language Reference.

User Routine

You need to include a user routine in your program. This routine typically contains an EVALUATE statement that handles the XML-EVENT values. The parser continually provides fragment information to the user routine until the entire document has been processed or until a fatal error is encountered. If malformed XML is encountered by the parser, an error code is placed into the special register XML-CODE, and control is transferred to an imperative statement. For non-fatal errors however, the user routine has the option of resetting XML-CODE to zero and and thus continuing execution. It also has the option of setting XML-CODE to -1 for a normal event. This causes the parser to terminate, but without generating an exception event.

See the Help topic The XML PARSE statement for more information.

XML in Brief

XML (eXtensible Markup Language) is fast emerging as the language of choice for exchanging data over the World Wide Web. The language is governed by a set of rules set forth in an XML schema or a Document Type Definition (DTD). These rules dictate the structure of an XML document. The XML schema is a more modern, powerful and prevalent technology for dictating XML document structure than the older DTD technology. We provide comprehensive support for XML schemas that enable input from and output to XML documents from a COBOL application.

XML is documented extensively on the W3C Web site. In this document, we concentrate only on the parts of XML that we use to enable data exchange with XML. See the World Wide Web consortium Web site for more information.

XML Schemas

An XML schema (usually an .xsd file) is made up in part of element definitions. These definitions dictate the structure and content of an XML instance document that references the schema. XML elements can have attributes associated with them. These attributes further describe the data contained in the element.

The following is an example of a simple XML schema:

Example 1-1: Sample XML Schema

<?xml version="1.0" encoding="utf-8"?>
<schema xmlns="" 
   <element name="employee">
            <element name="emp-name">
                  <restriction base="string">
                     <length value="12"/>
            <element name="emp-number">
                  <restriction base="string">
                     <length value="8"/>

This schema defines a parent element, employee, with two child elements, emp-name and emp-number. Each of the child elements contains two child elements of its own - restriction and length. In this implementation of XML support, the base and value attributes for those elements are translated into COBOL record PIC clauses.

XML Instance Documents

XML instance documents (.xml files) are built using the elements declared in a schema, and also contain data. You use XML syntax extensions to read from and write to XML instance documents.

Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.