XML schema to COBOL mapping

The DFHSC2LS and DFHWS2LS utility programs support mappings between XML schema definitions and COBOL data structures.

How XML schema element names are mapped to COBOL

The CICS® assistants generate unique and valid names for COBOL variables from the schema element names using the following rules:
  1. COBOL reserved words are prefixed with ' X '.

    For example, DISPLAY becomes XDISPLAY.

  2. Characters other than A-Z, a-z, 0-9, or hyphen are replaced with ' X '.

    For example, monthly_total becomes monthlyXtotal . You can use the MAPPING-OVERRIDES parameter to change the way other characters are handled. For example, if you set the value UNDERSCORES-AS-HYPHENS , any underscore in the XML is converted to a hyphen instead of an X. So monthly_total becomes monthly-total.

  3. If the last character is a hyphen, it is replaced with ' X '.

    For example, ca-request- becomes ca-requestX.

  4. If the schema specifies that the variable has varying cardinality (that is, minOccurs and maxOccurs are specified on an xsd:element with different values), and the schema element name is longer than 23 characters, it is truncated to that length.

    If the schema specifies that the variable has fixed cardinality and the schema element name is longer than 28 characters, it is truncated to that length.

  5. Duplicate names in the same scope are made unique by the addition of one or two numeric digits to the second and subsequent instances of the name.

    For example, three instances of year become year , year1 , and year2.

    Should the above behavior be undesirable the user can specify MAPPING-OVERRIDES=NO-ARRAY-NAME-INDEXING as input to the utility which disables the addition of one or two numeric digits to the second and subsequent instances of the name.

  6. Five characters are reserved for the strings -cont or -num , which are used when the schema specifies that the variable has varying cardinality; that is, when minOccurs and maxOccurs are specified with different values.

    For more information, see Variable arrays of elements.

  7. For attributes, the previous rules are applied to the element name. The prefix attr- is added to the element name, and is followed by -value or -exist . If the total length is longer than 28 characters, the element name is truncated. For more information, see Support for XML attributes.

    The nillable attribute has special rules. The prefix attr- is added, but nil- is also added to the beginning of the element name. The element name is followed by -value . If the total length is longer than 28 characters, the element name is truncated.

The total length of the resulting name is 30 characters or less.

How XML schema types are mapped to COBOL

DFHSC2LS and DFHWS2LS map schema types to COBOL data description elements by using the specified mapping level according to Table 1. Note the following points:
  • If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to NULL, variable-length character data is mapped to null-terminated strings and an extra character is allocated for the null-terminator.
  • If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to YES, variable-length character data is mapped to two related elements: a length field and a data field. For example: 
    <xsd:simpleType name="VariableStringType">
  <xsd:restriction base="xsd:string">
    <xsd:minLength value="1"/>
    <xsd:maxLength value="10000"/>
  </xsd:restriction>
</xsd:simpleType>
<xsd:element name="textString" type="tns:VariableStringType"/>
    maps to: 
    15 textString-length PIC S9999 COMP-5 SYNC
15 textString PIC X(10000)
Table 1. Mapping reference for XML schema types
Schema simple type COBOL data description 
<xsd:simpleType>
  <xsd:restriction base="xsd:anyType">
  </xsd:restriction>
</xsd:simpleType>

Mapping level 2.0 and below: Not supported

Mapping level 2.1: Supported

 
<xsd:simpleType>
  <xsd:restriction base="xsd:anySimpletype">
  </xsd:restriction>
</xsd:simpleType>

Mapping level 1.0: Not supported

Mapping level 1.1 and higher: 
PIC X(255)
 
<xsd:simpleType>
  <xsd:restriction base="xsd:type">
    <xsd:length value="z"/>
  </xsd:restriction>
</xsd:simpleType>
where type is one of:
  • string
  • normalizedString
  • token
  • Name
  • NMTOKEN
  • language
  • NCName
  • ID
  • IDREF
  • ENTITY
  • hexBinary
All mapping levels:
PIC X(z)
 
<xsd:simpleType>
  <xsd:restriction base="xsd:type">
    <xsd:length value="z"/>
  </xsd:restriction>
</xsd:simpleType>
where type is one of:
  • string
  • normalizedString
  • token
  • Name
  • NMTOKEN
  • language
  • NCName
  • ID
  • IDREF
  • ENTITY
When CCSID=1200 at mapping level 4.0 and higher: 
PIC N(z) USAGE NATIONAL
 
<xsd:simpleType>
  <xsd:restriction base="xsd:type">
  </xsd:restriction>
</xsd:simpleType>
where type is one of:
  • duration
  • date
  • time
  • gDay
  • gMonth
  • gYear
  • gMonthDay
  • gYearMonth
All mapping levels: 
PIC X(32)
 
<xsd:simpleType>
  <xsd:restriction base="xsd:dateTime">
  </xsd:restriction>
</xsd:simpleType>
Mapping level 1.2 and below: 
PIC X(32)
Mapping level 2.0 and higher: 
PIC X(40)
Mapping level 3.0 and higher:
PIC S9(15) COMP-3

The format is CICS ABSTIME. 

<xsd:simpleType>
  <xsd:restriction base="xsd:type">
  </xsd:restriction>
</xsd:simpleType>
where type is one of:
  • byte
  • unsignedByte
All mapping levels:
PIC X DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:short">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC S9999 COMP-5 SYNC
or
PIC S9999 DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:unsignedShort">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels:
PIC 9999 COMP-5 SYNC
or
PIC 9999 DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:integer">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC S9(18) COMP-3
 
<xsd:simpleType>
  <xsd:restriction base="xsd:int">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC S9(9) COMP-5 SYNC
or
PIC S9(9) DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:unsignedInt">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC 9(9) COMP-5 SYNC
or
PIC 9(9) DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:long">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC S9(18) COMP-5 SYNC
or
PIC S9(18) DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:unsignedLong">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC 9(18) COMP-5 SYNC
or
PIC 9(18) DISPLAY
 
<xsd:simpleType>
  <xsd:restriction base="xsd:decimal">
    <xsd:totalDigits value="m">
    <xsd:fractionDigits value="n">
  </xsd:restriction>
</xsd:simpleType>
 All mapping levels:
If WIDE-COMP3=FULL: 
PIC 9(m)V9(n) COMP-3
Otherwise: 
PIC 9(p)V9(n) COMP-3

where p = m - n. 

<xsd:simpleType>
  <xsd:restriction base="xsd:boolean">
  </xsd:restriction>
</xsd:simpleType>
All mapping levels: 
PIC X DISPLAY

The value x'00' implies false, x'01' implies true. 

<xsd:simpleType>
  <xsd:list>
    <xsd:simpleType>
      <xsd:restriction base="xsd:int"/>
    </xsd:simpleType>
  </xsd:list>
</xsd:simpleType>

Mapping level 1.0: Not supported

Mapping level 1.1 and higher: 
PIC X(255)
 
<xsd:simpleType>
  <xsd:union memberTypes="xsd:int xsd:string"/>
</xsd:simpleType>

Mapping level 1.0: Not supported

Mapping level 1.1 and higher: 
PIC X(255)
 
<xsd:simpleType>
  <xsd:restriction base="xsd:base64Binary">
    <xsd:length value="z"/>
  </xsd:restriction>
</xsd:simpleType>
<xsd:simpleType>
  <xsd:restriction base="xsd:base64Binary">
  </xsd:restriction>
</xsd:simpleType>
where the length is not defined.

Mapping level 1.0: Not supported

Mapping level 1.1: 
PIC X(y)

where y =4×(ceil( z /3)). ceil( x ) is the smallest integer greater than or equal to x.

Mapping level 1.2 and higher: 
PIC X(z)

where the length is fixed.

PIC X(16)

where the length is not defined. The field holds the 16-byte name of the container that stores the binary data.

 
<xsd:simpleType>
  <xsd:restriction base="xsd:float">
  </xsd:restriction>
</xsd:simpletype>
Mapping level 1.1 and below: 
PIC X(32)
Mapping level 1.2 and higher: 
COMP-1
Note: The IBM® Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation that is used for XML. Some values might not convert exactly from one representation to the other. Some extremely large or small values might not be valid for xsd:float data types. Some values might lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of COMP-1 data types with fixed precision alternatives. 
<xsd:simpleType>
  <xsd:restriction base="xsd:double">
  </xsd:restriction>
</xsd:simpletype>
Mapping level 1.1 and below: 
PIC X(32)
Mapping level 1.2 and higher: 
COMP-2
Note: The IBM Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation that is used for XML. Some values might not convert exactly from one representation to the other. Some extremely large or small values might not be valid for xsd:double data types. Some values might lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of COMP-2 data types with fixed precision alternatives.

Some of the schema types shown in the table map to a COBOL format of COMP-5 SYNC or of DISPLAY, depending on the values (if any) that are specified in the minInclusive and maxInclusive facets:

  • For signed types ( short , int , and long ), DISPLAY is used when the following are specified: 
    <xsd:minInclusive value="-a"/>
<xsd:maxInclusive value="a"/>
    where a is a string of '9's.
  • For unsigned types ( unsignedShort , unsignedInt , and unsignedLong ), DISPLAY is used when the following are specified: 
    <xsd:minInclusive value="0"/>
<xsd:maxInclusive value="a"/>
    where a is a string of '9's.

When any other value is specified, or no value is specified, COMP-5 SYNC is used.