Mapping COBOL Data to XML Elements

The example shown in the topic Generating XML-enhanced COBOL from an XML Schema generates COBOL data records based on the element names found in the schema. However, you might have an existing COBOL record you want to use specifically to communicate with a third-party schema. To do this, you must create a direct relationship between a COBOL record and the elements of the schema by means of a map file.

Use this format to generate a map file that you can customize.

cbl2xml filename -m mapFile

The process of XML-enabling an application to exchange information with XML documents based on an existing COBOL record and an existing schema is as follows:

  1. Generate a map file using cbl2xml. To produce a new map file, specify a map filename that does not exist. When cbl2xml does not find an existing map file with the name you specify, it generates a new file.
  2. Edit the map file, changing the names of generated elements to element names that exist in the schema you want to use for data exchange.
  3. Rerun cbl2xml using the same format you used in step 1 of this process. However, this time specify the existing, edited map file. When cbl2xml does find a map file of the name you specified, it applies the mappings in the file to the COBOL record.

The remainder of this section explains the details of this process.

If the mapfile you specify does not exist, cbl2xml takes data structures from the COBOL file, translates them into XML, and writes that information into the map file.

For example:

COBOL record and XML schema communication

Product_info.cpy contains the following record:

       01  PRODUCT-INFO.
           05 PROD-ID     PIC 9(6).
           05 COMPANY-ID  PIC 9(4).
           05 CATALOG-NUM PIC 9(8).
           05 SKU-REF     PIC X(10).

The following is the element definition from widget.xsd with which you want to communicate:

	<xsd:element name="Widgets">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element ref="Product_Id" minOccurs="0"/>
				<xsd:element ref="Company_Id"/>
				<xsd:element ref="Catalogue_Id"/>
				<xsd:element ref="SKU"/>
				<xsd:element ref="Product_Series" minOccurs="0"/>
				<xsd:element ref="Availability"/>
				<xsd:element ref="Sale"/>
				<xsd:element ref="Base_Price_And_Unit"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Cbl2xml generates the following map file from product_info.cpy:

Generated map file

<?xml version="1.0" encoding="utf-8"?>
<xml-cobol-mapping-file 
   xmlns="http://xml.microfocus.com/schema/xml/v1.0/mfxmlmap.xsd" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation=
    "http://xml.microfocus.com/schema/xml/v1.0/mfxmlmap.xsd
    mfxmlmap.xsd">
   <xml-cobol-mapping>
      <cobol-name>product-info</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>product-info</xml-name>
      <xml-type>group</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.prod-id</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>prod-id</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.company-id</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>company-id</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.catalog-num</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>catalog-num</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
   <xml-cobol-mapping>
      <cobol-name>product-info.sku-ref</cobol-name>
      <cobol-count-in>true</cobol-count-in>
      <xml-name>sku-ref</xml-name>
      <xml-type>string</xml-type>
      <xml-attribute>false</xml-attribute>
      <xml-namespace></xml-namespace>
   </xml-cobol-mapping>
</xml-cobol-mapping-file>

The map file is an XML document. The tags generated by cbl2xml contain specific information about the COBOL record as follows:

Map file tag name Meaning
<xml-cobol-mapping-file> Indicates that this is a mapping file to be used to create XML structure in a COBOL program. It is the root element of the map file.
<xml-cobol-mapping> Contains information for one COBOL data item. It is the parent element to <cobol-name>, <xml-name>, <xml-type>, <xml-attribute>, and <xml-namespace>.
<cobol-name> Contains the name of a data item from a COBOL record, including the parent name of the data item. The parent name comes first, followed by the data item name, separated by a period (.). For example: a-file-record.a-file-item.
<cobol-count-in> Specifies whether or not the COBOL XML COUNT IN clause is generated for the COBOL item in <cobol-name>. Acceptable values are “true” and “false”. The default value is “true.” This value is ignored when the –nocountin command-line option is used.
<xml-name> Specifies an equivalent XML element name to be used to correspond to the record named in <cobol-name>.
<xml-type> The XML simple type that the COBOL item is being mapped to. This parameter is applicable only when a COBOL data item has a PIC clause.
<xml-attribute> Specifies whether or not the element specified in <xml-name> is to be treated as an attribute in the XML schema. Values are “true” or “false.”
<xml-namespace> An optional element that specifies the XML namespace for the element specified in <xml-name>. A namespace specified at a group level is inherited automatically by child elements.

You can then create user-defined mappings by editing the map file and matching the XML element names found in the schema to the COBOL names found in your COBOL record. To do this, change the <xml-name>s in the map file to match the element names in the schema. In this example, you would edit the <xml-name>s in the map file shown in example Generated Map File as follows:

Change... To...
<xml-name>product-info</xml-name> <xml-name>Widgets</xml-name>
<xml-name>prod-id</xml-name> <xml-name>Product_Id</xml-name>
<xml-name>company-id</xml-name> <xml-name>Company_Id</xml-name>
<xml-name>catalog-num</xml-name> <xml-name>Catalogue_Id</xml-name>
<xml-name>sku-ref</xml-name> <xml-name>SKU</xml-name>

At this point, run cbl2xml again, specifying the edited map file, and cbl2xml produces a schema and a copybook. The schema will be similar to your existing schema, depending on how much of that existing schema you edited into your map file. You do not need to use this schema; it is created by default and is not critical. The copybook contains your original COBOL record with the appropriate XML syntax extensions appended to it, based on the information found in the map file. In this example, cbl2xml generates the following copybook:

        01 product-info identified by "Widgets" 
           count in widgets-count.
         02 prod-id pic 9(6) identified by "Product_Id" 
            count in Product_Id-count.
         02 company-id pic 9(4) identified by "Company_Id" 
            count in Company_Id-count.
         02 catalog-num pic 9(8) identified by "Catalogue_Id" 
            count in Catalogue_Id-count.
         02 sku-ref pic X(10) identified by "SKU" 
            count in SKU-count.

Paste this new record into your COBOL program, replacing the original record. Your COBOL record is now XML-enabled to communicate with XML documents that conform to the widgets.xsd schema.