Mapping levels for the CICS JSON assistant

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

Each level of mapping inherits the function of the previous mapping, with the highest level of mapping offering 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 JSON properties

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

Limitations at all mapping levels

  • Data types used in the JSON schema must be explicitly declared.
  • JSON object references to external documents using "$ref" are not supported within the JSON schema

Mapping level 4.1

Mapping level 4.1 is compatible with a CICS TS 5.3 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.

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

This mapping level provides the following support:

At mapping level 4.0 and higher, DFHLS2JS supports the COBOL OCCURS DEPENDING ON clause and supports mapping of COBOL character arrays into JSON schemas. You can set this behavior by using the CHAR-OCCURS parameter on the CICS JSON assistant.
  • 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 an integer bound for the maximum size of the table expected by the application.
At mapping level 4.0 and higher, JSON web services support the conversion of application data that is encoded using UTF-16 Unicode.
  • When you use LS2JS, you can enable this behavior by using language-specific data types for UTF-16.
  • When you use JS2LS, 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: DFHLS2JS does not the support the COBOL GROUP USAGE NATIONAL clause.

Mapping level 3.0 and higher

This mapping level provides the following support:

  • DFHJS2LS maps date-time data types to CICS ASKTIME format.
  • DFHLS2JS can generate a JSON schema 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 assistant.

Mapping level 2.2 and higher

This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

Mapping level 2.1 and higher

This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

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, DFHJS2LS offers the following new and improved support for arrays:
  • The INLINE-MAXOCCURS-LIMIT parameter
  • The minItems property

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

At mapping level 2.1 and higher, DFHLS2JS support the following JSON 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 JSON 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 converting COBOL into a JSON schema. This option is available only on SBCS character arrays and allows the array to be mapped to a fixed-length JSON string containing base64 encoded data rather than to a normal string.

Mapping level 1.2 and higher

This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

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 DFHJS2LS, note that the following rules apply after the value of this parameter is used to calculate the amount of space required for character data.
  • DFHJS2LS provides 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 JSON schema that do not have a length associated with them, you can assign a default length using the DEFAULT-CHAR-MAXLENGTH parameter in DFHJS2LS.

DFHLS2JS provides these mappings:
  • Character fields map to a 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

This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

This mapping level provides improved mapping of JSON character and binary data types, in particular when mapping data of variable length that has maxLength and minLength properties defined with different values in the JSON schema. Data is handled as follows:
  • 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 specified in the JSON schema. If the length of the data is significant, you can either write your application to check it or turn validation on in the CICS region. Validation has a significant performance impact.

Mapping level 1.1 only

This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

This mapping level provides improved mapping of JSON character and binary data types, in particular when mapping data of variable length that has maxLength and minLength properties defined with different values in the JSON 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 JSON schema map to a field in the language structure. The size of the field is calculated using the formula: 4×(ceil(z/3)) where:
    • z is the length of the data type in the JSON 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 are recommended to 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

This option is retained for compatibility with SOAP web services. It is not recommended for use with JSON.

Note the following limitations, which have been modified in later mapping levels:
  • DFHJS2LS map character and binary data types in the JSON schema to fixed-length fields in the language structure. Look at this partial JSON schema:
            "example":{
          "type":"string",
          "maxLength":33000
    That partial JSON schema appears in a COBOL language structure as:
    15 example     PIC X(33000)
  • CICS encodes and decodes data in the hexBinary format but not in base64Binary format. DFHJS2LS map Base64Binary data to a fixed-length character field, the contents of which must be encoded or decoded by the application program.
  • DFHLS2JS interpret character and binary fields in the language structure as fixed-length fields and map those fields to JSON strings that have a maxLength property. At run time, the fields in the language structure are filled with spaces or nulls if insufficient data is available.