Here are some cases in which data conversion is necessary:
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.
Appendix F of the z/OS Support for Unicode: Using Conversion Services manual -SA22 -7649 records those conversions which are supported though these services. These are not limited to Unicode, but include the ability to convert between a broad range of character encodings, including EBCDIC, ASCII and Unicode.
CICS® now supports any of these character conversions by making use of the z/OS® conversion services. However, those conversions that earlier releases of CICS carried out using a set of tables, continue to be supported in that manner. It is only if CICS TS 3.1 is asked to carry out a conversion between a pair of CCSIDs that are unsupported via these tables, that it attempts the conversion using the z/OS services.
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.
Applications that use channels to exchange data use a simple data conversion model. Frequently, no conversion is required and, when it is, a single programming instruction can be used to tell CICS to handle it automatically.
Note the following:
In contrast, the data in channel containers is converted under the control of the application programmer, using API commands.
For data conversion purposes, CICS recognizes two types of data:
All the data in a container is converted as if it were a single character string. For single-byte character set (SBCS) code pages, a structure consisting of several character fields is equivalent to a single-byte character string. However, for double-byte character set (DBCS) code pages this is not the case. If you use DBCS code pages, to ensure that data conversion works correctly you must put each character string into a separate container.
The API commands used for data conversion are:
EXEC CICS PUT CONTAINER [CHANNEL] [DATATYPE] [FROMCCSID]
EXEC CICS GET CONTAINER [CHANNEL] [INTOCCSID]
EXEC CICS PUT CONTAINER(cont_name) CHANNEL('payroll')
FROM(data1) DATATYPE(DFHVALUE(CHAR))
There is no need to specify the FROMCCSID option unless the data is
not in the default CCSID of the client platform. (For CICS TS regions, the
default CCSID is specified on the LOCALCCSID system initialization parameter.)
The default CCSID is implied.EXEC CICS GET CONTAINER(cont_name) INTO(data_area1)
The data is returned in the default CCSID of the server platform.
There is no need to specify the INTOCCSID option unless you want the data
to be converted to a CCSID other than the default. If the client and server
platforms are different, data conversion takes place automatically.EXEC CICS PUT CONTAINER(status) FROM(data_area2)
DATATYPE(DFHVALUE(CHAR))
The DATATYPE(DFHVALUE(CHAR))
option specifies that the container holds character data and that the data
is eligible for conversion. There is no need to specify the FROMCCSID option
unless the data is not in the default CCSID of the server platform.EXEC CICS GET CONTAINER(status) CHANNEL('payroll')
INTO(status_area)
The status
is returned in the default CCSID of the client platform. There is no need
to specify the INTOCCSID option unless you want the data to be converted to
a CCSID other than the default. If the client and server platforms are different,
data conversion takes place automatically.
Your applications can use the container API as a simple means of converting character data from one code page to another. The following example converts data from codepage1 to codepage2:
EXEC CICS PUT CONTAINER(temp) DATATYPE(DFHVALUE(CHAR))
FROMCCSID(codepage1) FROM(input-data)
EXEC CICS GET CONTAINER(temp) INTOCCSID(codepage2)
SET(data-ptr) FLENGTH(data-len)
The following example converts data from the region's default EBCDIC code page to a specified UTF8 code page:
EXEC CICS PUT CONTAINER(temp) DATATYPE(DFHVALUE(CHAR))
FROM(ebcdic-data)
EXEC CICS GET CONTAINER(temp) INTOCCSID(utf8_ccsid)
SET(utf8-data-ptr) FLENGTH(utf8-data-len)
When using the container API in this way, bear the following in mind:
A CICS TS SOAP application:
The back-end handler program, also running on CICS TS, can use EXEC CICS GET CONTAINER commands to retrieve the EBCDIC data structures or the messages. It can get the messages in UTF8 or UTF16, or in its own or the region's EBCDIC code page. Similarly, it can use EXEC CICS PUT CONTAINER commands to place data into the containers, in UTF8, UTF16, or EBCDIC.
To retrieve one of the messages in the region's EBCDIC code page, the handler can issue the command:
EXEC CICS GET CONTAINER(input_msg) INTO(msg)
Because the INTOCCSID option is not specified, the message data is automatically converted to the region's EBCDIC code page. (This assumes that the PUT CONTAINER command used to store the message data in the channel specified a DATATYPE of CHAR; if it specified a DATATYPE of BIT, the default, no conversion is possible.)
To return some output in the region's EBCDIC code page, the handler can issue the command:
EXEC CICS PUT CONTAINER(output) FROM(output_msg)
Because CHAR is not specified, no data conversion will be permitted. Because the FROMCCSID option is not specified, the message data is taken to be in the region's EBCDIC code page.
To retrieve one of the messages in UTF8, the handler can issue the command:
EXEC CICS GET CONTAINER(input_msg) INTO(msg) INTOCCSID(utf8)
The INTOCCSID option is necessary to prevent automatic conversion of the data to the region's EBCDIC code page.
To return some output in UTF8, the server program can issue the command:
EXEC CICS PUT CONTAINER(output) FROM(output_msg) FROMCCSID(utf8)
The FROMCCSID option specifies that the message data is currently in UTF8 format. Because CHAR is not specified, no data conversion will be permitted.