Changes to application programming

The following information is added to the CICS Application Programming Guide.

Data conversions within CICS® using z/OS® Unicode conversion services adds to the data conversion support that is provided for any of the range of EBCDIC and ASCII codepage combinations listed in the "CICS-supported conversions" topic in the CICS Family: Communicating from CICS on System/390® manual.

Conversions involving Unicode typically take place as part of the processing of HTTP requests or the use of the CONTAINER API commands introduced in CICS TS 3.1. The conversion of data to or from either UTF-8 or UTF-16 and EBCDIC and ASCII codepages, depends on the selection of suitable conversion images. Conversion between the UTF-8 and UTF-16 forms of Unicode is also supported.

To use the data conversion methods described here, as opposed to those offered by earlier releases of CICS, you must be communicating your data using channels or containers, as described in the CICS Application Programming Guide.

CICS documents and document templates cannot be converted to or from the UTF-8 and UTF-16 character encodings. This restriction applies whether they are used as a static response in CICS Web support, retrieved by CICS in response to EXEC CICS WEB API commands, or retrieved by an application program using an EXEC CICS DOCUMENT RETRIEVE command.

Appendix F of the z/OS Support for Unicode: Using Conversion Services manual -SA22 -7649 records those conversions which are supported though these services. CICS now supports any of these character conversions by making use of the z/OS conversion services.

Ensuring that required conversion images are available
Those CCSIDs used as part of CICS applications must be made known to the System Programmers responsible for maintaining the z/OS Conversion Image, so that specific conversions are available to the CICS regions where these applications execute.
Handling CCSID 1200

CICS supports conversions involving UTF-16 data using any of the following CCSID's: 1200, 1201, and 1202. The z/OS conversion services permit CCSID 1200, in its big-endian form, to be used, but does not contain support for the little-endian form or for CCSIDs 1201 or 1202. CICS transforms any source data that is identified in any of these unsupported forms to the big-endian form of 1200 before passing the data to z/OS for conversion. If the target data is one of the unsupported forms then CICS receives the data as the big-endian form of 1200 and transforms it to the required CCSID. If the target CCSID is 1200 then CICS assumes the encoding to be in big-endian form. If the conversion is between any of these CCSIDs then CICS will carry out the transformation without calling the z/OS conversion services.

When setting up the z/OS conversion image for conversions involving any of these forms of UTF-16 then CCSID 1200 must be specified. CCSIDs 1201 and 1202 will not be recognised by z/OS when attempting to create a conversion image.

CICS respects the byte order marker for inbound conversions, but is not able to retain that information when handling a related outbound conversion. All outbound data for CCSID 1200 is UTF16-BE. Application programmers need to know about this and perform their own BE to LE conversions if they so require.
Sharing a conversion image
  • Unless the PTF for APAR OA05744 is applied, do not specify a search order for those conversions, installed into the z/OS image which are intended for use by CICS.
  • If the same conversions are needed for COBOL you must define the conversion image with two separate statements:
    • one with no search order, and
    • the other explicitly specifying a search order of 'RECLM'.
    for example:.

    CONVERSION 850,037;
    CONVERSION 850,037,RECLM;

With the APAR installed, CICS and COBOL can make use of those supported conversions which specify the default search order implicitly or explicitly, removing the need to provide two control statements in the image generation file.
JAVA programs
Codepage conversion facilities exist within JAVA, So it is not neccessary to duplicate these in CICS. The conversion facilities described here do not extend to JAVA programs. For an example, see the putting data into a container topic in the Java™ applications in CICS manual.