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.3
Mapping level 4.3 is compatible with CICS TS V5.4 with APAR PI88519, and higher.
Mapping level 4.3 is primarily for use with DFHJS2LS, but is also included in the CICS web services assistants, XML assistants, and JSON assistants. This mapping level implements support for multidimensional arrays in JSON.
Mapping level 4.2
Mapping level 4.2 is compatible with CICS TS V5.4 with APAR PI86039, and higher.
Mapping level 4.2 is primarily for use with DFHJS2LS, but is also included in the CICS web services assistants, XML assistants, and JSON assistants. This mapping level implements support for Additional Properties in JSON, and introduces the following three parameters to DFHJS2LS: ADDITIONAL-PROPERTIES-DEFAULT, ADDITIONAL-PROPERTIES-MAX, and ADDITIONAL-PROPERTIES-SIZE.
Mapping level 4.1
Mapping level 4.1 is compatible with a CICS TS 5.3 region or CICS TS 5.2 region with APAR PI67641 applied, and higher.
Mapping level 4.1 is added to the Web Services Assistants, XML Assistants, and JSON Assistants. This mapping level implements improved mappings for simple arrays generated bottom-up from existing copybooks; it also adds the ability for CICS to auto-detect uninitialized trailing storage in arrays, and to omit those records from the generated XML/JSON form. For more information, see COBOL to JSON schema mapping.
DFHLS2WS, DFHWS2LS, DFHLS2SC, DFHSC2LS, DFHJS2LS, and DFHLS2JS support the TRUNCATE-NULL-ARRAYS and TRUNCATE-NULL-ARRAY-VALUES parameters.
If you specify any value for TRUNCATE-NULL-ARRAY-VALUESS , you must also specify TRUNCATE-NULL-ARRAYS=ENABLED.
Mapping level 4.0
Mapping level 4.0 is compatible with a CICS TS 5.2 region.
- 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.
- 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.
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.
- Fixed values for elements
- Substitution groups
- Abstract data types
- XML schema <sequence> elements can nest inside <choice> elements
- 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.
- 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.
- 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.
- CHAR-VARYING
- CHAR-VARYING-LIMIT
- CHAR-MULTIPLIER
- DEFAULT-CHAR-MAXLENGTH
-
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.
-
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.
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.
maxLength
and
minLength
attributes
that are defined with different values in the XML schema. Data is
handled in the following ways:
- 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.
Mapping level 1.0 only
Mapping level 1.0 is compatible with a CICS TS 3.1 region and higher.
-
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:
That partial XML schema appears in a COBOL language structure like this example:<xsd:element name="example"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:maxLength value="33000"/> </xsd:restriction> </xsd:simpleType> </xsd:element>
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.