Start of changeStart of change

Data conversion

Start of change

Why is data conversion needed?

Here are some cases in which data conversion is necessary:

End of changeStart of change

Preparing for code page conversion with channels

About this task

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.

Note:
  1. The conversion between 037 and 500, as used, for example, with the MQ transport is an EBCDIC to EBCDIC conversion brought about by small differences in the character encodings used by CICS and MQ.
  2. You need to be aware that not all points in each codepage have direct counterparts in other codepages. The EBCDIC character NL is one such example. Java and z/OS conversion services may differ in the conversions that they perform. "Technotes", and other Internet discussions may offer guidance on particular points. It is also worth observing that programming communities are themselves divided on the question of what is the more appropriate conversion in particular circumstances.

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.

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
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.

End of changeStart of change

Data conversion with channels

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:

For data conversion purposes, CICS recognizes two types of data:

CHAR
Character data--that is, a text string. The data in the container is converted (if necessary) to the code page of the application that retrieves it. If the application that retrieves the data is a client on an ASCII-based system, this will be an ASCII code page. If it is a CICS Transaction Server for z/OS application, it will be an EBCDIC code page.

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.

BIT
All non-character data--that is, everything that is not designated as being of type CHAR. The data in the container cannot be converted. This is the default value.

The API commands used for data conversion are:

Start of change

How to cause CICS to convert character data automatically

About this task

Procedure

  1. In the client program, use the DATATYPE(DFHVALUE(CHAR)) option of the PUT CONTAINER command to specify that a container holds character data and that the data is eligible for conversion. For example:
    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.
  2. In the server program, issue a GET CONTAINER command to retrieve the data from the program's current channel:
    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.
  3. In the server program, issue a PUT CONTAINER command to return a value to the client:
    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.
  4. In the client program, issue a GET CONTAINER command to retrieve the status returned by the server program:
    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.

Results

End of changeStart of change

Using containers to do code page conversion

About this task

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:

End of changeStart of change

A SOAP example

A CICS TS SOAP application:

  1. Retrieves a UTF8 or UTF16 message from a socket or MQ message queue.
  2. Puts the message into a container, in UTF8 format.
  3. Puts EBCDIC data structures into other containers on the same channel.
  4. Makes a distributed program link (DPL) call to a handler program on a back-end AOR, passing the channel.

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.

End of changeEnd of changeEnd of changeEnd of change [[ Contents Previous Page | Next Page Index ]]