Mapping levels for the CICS assistants

A mapping is the set of rules that specifies how information is converted between language structures and XML schemas. To benefit from the most sophisticated mappings available, you must set the MAPPING-LEVEL parameter in the CICS® assistants to the latest level.

Each level of mapping inherits the function of the previous mapping, where the highest level of mapping offers the best capabilities available. The highest mapping level provides more control over data conversion at run time and removes restrictions on support for certain data types and XML elements.

You can set the MAPPING-LEVEL parameter to an earlier level if you want to redeploy applications that were previously enabled at that level.

Mapping level 4.0

Mapping level 4.0 is compatible with a CICS TS 5.2 region.

At mapping level 4.0 and higher, DFHLS2SC and DFHLS2WS support the COBOL OCCURS DEPENDING ON clause and supports mapping of COBOL character arrays into XML strings. You can set this behavior by using the CHAR-OCCURS parameter on the CICS assistants.

You must specify the parameter DATA-TRUNCATION=ENABLED.
Complex OCCURS DEPENDING ON is not supported. This limitation means that OCCURS DEPENDING ON is only supported for the last field of a structure.
CICS does not support qualified names (using the 'OF' keyword) as the target of an OCCURS DEPENDING ON clause, for example FIELD1 OF STRUCTURE1.
CICS does not support the UNBOUNDED keyword. You must specify the maximum size of the table that is expected by the application.

At mapping level 4.0 and higher, CICS web services support the conversion of application data that is encoded using UTF-16 Unicode.

When you use LS2WS or LS2SC, you can enable this behavior by using language-specific data types for UTF-16.
When you use WS2LS or SC2LS, you can enable this behavior by setting CCSID=1200.
CICS supports only a single Unicode code page, UTF-16BE with IBM® Private Use Area (CCSID 1200).
Conversion of application data that is encoded using UTF-8 is not supported.

Note: DFHLS2WS and DFHLS2SC do not the support the COBOL GROUP USAGE NATIONAL clause.

Mapping level 3.0 and higher

Mapping level 3.0 is compatible with a CICS TS 4.1 region and higher.

This mapping level provides the following support:

DFHSC2LS and DFHWS2LS map xsd:dateTime data types to CICS ASKTIME format.
DFHLS2WS can generate a WSDL document and web service binding from an application that uses many containers rather than just one container.
Tolerating truncated data that is described by a fixed-length data structure. You can set this behavior by using the DATA-TRUNCATION parameter on the CICS assistants.

Mapping level 2.2 and higher

Mapping level 2.2 is compatible with a CICS TS 3.2 region, with APAR PK69738 applied, and higher.

At mapping level 2.2 and higher, DFHSC2LS and DFHWS2LS support the following XML mappings:

Fixed values for elements
Substitution groups
Abstract data types
XML schema <sequence> elements can nest inside <choice> elements

DFHSC2LS and DFHWS2LS provide enhanced support for the following XML mappings:

Abstract elements
XML schema <choice> elements

Mapping level 2.1 and higher

Mapping level 2.1 is compatible with a CICS TS 3.2 region, with APAR PK59794 applied, and higher.

This mapping level includes greater control over the way variable content is handled with the new INLINE-MAXOCCURS-LIMIT parameter and new values on the CHAR-VARYING parameter.

At mapping level 2.1 and higher, DFHSC2LS and DFHWS2LS offer the following new and improved support for XML mappings:

The XML schema <any> element
The xsd:anyType type
Toleration of abstract elements
The INLINE-MAXOCCURS-LIMIT parameter
The minOccurs attribute

The INLINE-MAXOCCURS-LIMIT parameter specifies whether variably repeating lists are mapped inline. For more information about mapping variably repeating content inline, see Variable arrays of elements.

Support for the minOccurs attribute is enhanced for the XML schema <sequence>, <choice>, and <all> elements. If minOccurs="0", the CICS assistant treats these elements as though the minOccurs="0" attribute is also an attribute of all its child elements.

At mapping level 2.1 and higher, DFHLS2SC and DFHLS2WS support the following XML mappings:

FILLER fields in COBOL and PL/I are ignored
A value of COLLAPSE for the CHAR-VARYING parameter
A value of BINARY for the CHAR-VARYING parameter

FILLER fields in COBOL and PL/I are ignored; they do not appear in the generated XML schema and an appropriate gap is left in the data structures at run time.

COLLAPSE causes CICS to ignore trailing spaces in text fields.

BINARY provides support for binary fields. This value is useful when you are converting COBOL into an XML schema. This option is available only on SBCS character arrays and allows the array to be mapped to fixed-length xsd:base64Binary fields rather than to xsd:string fields.

Mapping level 1.2 and higher

Mapping level 1.2 is compatible with a CICS TS 3.1 region and higher.

Greater control is available over the way character and binary data are transformed at run time with these additional parameters on the batch tools:

CHAR-VARYING
CHAR-VARYING-LIMIT
CHAR-MULTIPLIER
DEFAULT-CHAR-MAXLENGTH

If you decide to use the CHAR-MULTIPLIER parameter in DFHSC2LS or DFHWS2LS, the following rules apply after the value of this parameter is used to calculate the amount of space that is required for character data.

DFHSC2LS and DFHWS2LS provide these mappings:
- Variable-length character data types that have a maximum length of more than 32 767 bytes map to a container. You can use the CHAR-VARYING-LIMIT parameter to set a lower limit. A 16-byte field is created in the language structure to store the name of the container. At run time, the character data is stored in a container and the container name is put in the language structure.
- Variable-length character data types that have a maximum length of less than 32 768 bytes map to a VARYING structure for all languages except C/C++ and Enterprise PL/I. In C/C++, these data types are mapped to null-terminated strings, and in Enterprise PL/I these data types are mapped to VARYINGZ structures. You can use the CHAR-VARYING parameter to select the way that variable-length character data is mapped.
- Variable-length binary data that has a maximum length of less than 32 768-bytes maps to a VARYING structure for all languages. If the maximum length is equal to or greater than 32 768 bytes, the data is mapped to a container. A 16-byte field is created in the language structure to store the name of the container. At run time, the binary data is stored in a container and the container name is put in the language structure.

If you have character data types in the XML schema that do not have a length that is associated with them, you can assign a default length by using the DEFAULT-CHAR-MAXLENGTH parameter in DFHWS2LS or DFHSC2LS.

DFHLS2SC and DFHLS2WS provide these mappings:

Character fields map to an xsd:string data type and can be processed as fixed-length fields or null-terminated strings at run time. You can use the CHAR-VARYING parameter to select the way that variable-length character data is handled at run time for all languages except PL/I.
Base64Binary data types map to a container if the maximum length of the data is greater than 32 767 bytes or when the length is not defined. If the length of the data is 32 767 or less, the base64Binary data type is mapped to a VARYING structure for all languages.

Mapping level 1.1 and higher

Mapping level 1.1 is compatible with a CICS TS 3.1 region and higher.

This mapping level provides improved mapping of XML character and binary data types, in particular when mapping data of variable length that has maxLength and minLength attributes that are defined with different values in the XML schema. Data is handled in the following ways:

Character and binary data types that have a fixed length that is greater than 16 MB map to a container for all languages except PL/I. In PL/I, fixed-length character and binary data types that are greater than 32 767 bytes are mapped to a container. A 16-byte field is created in the language structure to store the name of the container. At run time, the fixed-length data is stored in a container and the container name is put in the language structure.
Because containers are variable in length, fixed-length data that is mapped to a container is not padded with spaces or nulls, or truncated, to match the fixed length that is specified in the XML schema or web service description. If the length of the data is significant, you can either write your application to check it or turn on validation in the CICS region. Both SOAP and XML validation have a significant performance impact.
XML schema <list> and <union> data types map to character fields.
Schema-defined XML attributes are mapped rather than ignored. A maximum of 255 attributes is allowed for each XML element. For more information, see Support for XML attributes.
The xsi:nil attribute is supported. For more information, see Support for XML attributes.

Mapping level 1.1 only

Mapping level 1.1 is compatible with a CICS TS 3.1 region and higher.

Variable-length binary data types map to a container. A 16-byte field is created in the language structure to store the name of the container. At run time, the binary data is stored in a container and the container name is put in the language structure.
Variable-length character data types that have a maximum length greater than 32 767 bytes map to a container. A 16-byte field is created in the language structure to store the name of the container. At run time, the character data is stored in a container and the container name is put in the language structure.
Character and binary data types that have a fixed length of less than 16 MB map to fixed-length fields for all languages except PL/I. In PL/I, fixed-length character and binary data types that are 32 767 bytes or less map to fixed-length fields.
CICS encodes and decodes data in the hexBinary format but not in base64Binary format. Base64Binary data types in the XML schema map to a field in the language structure. The size of the field is calculated by using the formula: 4×(ceil(z/3)) where:
- z is the length of the data type in the XML schema.
- ceil(x) is the smallest integer greater than or equal to x.
If the length of z is greater than 24 566 bytes, the resulting language structure fails to compile. If you have base64Binary data that is greater than 24 566 bytes, you must use a mapping level of 1.2. With mapping level 1.2, you can map the base64Binary data to a container instead of using a field in the language structure.

Mapping level 1.0 only

Mapping level 1.0 is compatible with a CICS TS 3.1 region and higher.

Note the following limitations, which are modified in later mapping levels:

DFHSC2LS and DFHWS2LS map character and binary data types in the XML schema to fixed-length fields in the language structure. Look at this partial XML schema:
```
<xsd:element name="example">
  <xsd:simpleType>
    <xsd:restriction base="xsd:string">
      <xsd:maxLength value="33000"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:element>
```
That partial XML schema appears in a COBOL language structure like this example:
```
15 example     PIC X(33000)
```
CICS encodes and decodes data in the hexBinary format but not in base64Binary format. DFHSC2LS and DFHWS2LS map Base64Binary data to a fixed-length character field, the contents of which must be encoded or decoded by the application program.
DFHSC2LS and DFHWS2LS ignore XML attributes during processing.
DFHLS2SC and DFHLS2WS interpret character and binary fields in the language structure as fixed-length fields and map those fields to XML elements that have a maxLength attribute. At run time, the fields in the language structure are filled with spaces or nulls if insufficient data is available.