Unicode support in the Server Option for CICS

The unichar, univarchar, and unitext datatypes have been added for Unicode support in the Server Option. These three datatypes are mapped to TDS_LONGBINARY with a user type of 34, 35, or 36, as shown in Table 4.

**Table 4: Unicode datatype mappings**
SQL datatype	TDS datatype	User type	Comment
unichar	TDS_LONGBINARY	34	Fixed-length UTF-16 data
univarchar	TDS_LONGBINARY	35	Variable-length UTF-16 data
unitext	TDS_LONGBINARY	36	UTF-16 encoded data

The Server Option has the following three datatypes to support unichar, univarchar, and unitext:

TDSUNICHAR – Internal type 26
TDSUNIVARCHAR – Internal type 27
TDSUNITEXT – Internal type 28

Currently, there is no special support for TDSUNITEXT.

The following API calls have been changed in the Server Option to accommodate support for Unicode:

TDPROPS

The TDPROPS API call maintains character set conversion properties.

Syntax

COPY SYGWCOB

01  TDSPROC            PIC S9(9) COMP.
01  RETCODE            PIC S9(9) COMP.
01  OPER               PIC S9(9) COMP.
01  PROPERTY           PIC S9(9) COMP.
01  VALUE              PIC S9(9) COMP.

CALL ‘TDPROPS’ USING TDSPROC RETCODE OPER PROPERTY VALUE.

Arguments

Argument	Description
TDPROC	(I) Handle for the client/server connection.
RETCODE	(O) Variable to which the result of function execution is returned.
OPER	(I) To retrieve the property specified by PROPERTY, set the value to TDS-GET. To change the property specified by PROPERTY, set the value to TDS-SET.
PROPERTY	(I) TDPROPS supports the following properties: TDS_CLIENT_CCSID – defines the CCSID to which the Server Option converts server data. The value of this property defaults to the CCSID of the character set negotiated between the client and the server at login. TDS_SERVER_CCSID – defines the CCSID to which the Server Option converts client data. The value of this property defaults to the CCSID of the character set negotiated between the client and the server at login. A UTF-8 connection is established in the case when the client-requested character set at login is UTF-8, and Unicode support is enabled for the Server Option. TDS_PROG_CCSID – controls the conversion of data between the character sets of the server and the server application. For example, if a Server Option application sets TDS_PROG_CCSID to 1025 (Russian EBCDIC, CCSID=1025), and data received from the server is in UTF-8 (CCSID=1208), a parameter retrieved to a character variable in a TDRCVPRM call will be implicitly converted from CCSID=1208 to CCSID=1025. TDS_DATA_CCSID – controls the conversion of metadata. For example, if an OSC application program sets TDS_DATA_CCSID property value to 1025 (Russian EBCDIC, CCSID=1025) and data received from the server is in UTF-8 (CCSID=1208), then the column names will be retrieved for the application program after being implicitly converted from CCSID=1208 to CCSID=1025.
VALUE	(I) The value of the property specified in PROPERTY.

For a connection established with the UTF-8 character set, the default values for the TDS_CLIENT_CCSID, TDS_SERVER_CCSID, TDS_PROG_CCSID, and TDS_DATA_CCSID parameters are 1208, 1208, 500, and 500, respectively.

TDPROPS may specify values for these properties any time after a connection has been established. The default values for these properties depend on the character set established for the connection at login.

The Server Option does not reset any CCSID property values set by an application program. Once an application changes a CCSID property value, the setting remains for all API calls until it is reset by the application.

Example 1

TDS_PROG_CCSID is set to 1208 (UTF-8), and both TDS_SERVER_CCSID and TDS_CLIENT_CCSID default to 1208. The server application program calls TDRCVPRM.

When the server reads data from the client, the data is in UTF-8.
When a Server Option application requests data from the server, the data is retrieved in UTF-8.

Example 2

TDS_PROG_CCSID is set to 1025 (Russian EBCDIC, CCSID=1025), and both TDS_SERVER_CCSID and TDS_CLIENT_CCSID default to 1208. The application calls TDRCVPRM:

When data is read by the server from the client, the data is in UTF-8.
When data is requested by the Server Option application from the server, the data is retrieved in EBCDIC CCSID=1025.

Example 3

TDS_PROG_CCSID is set to 939 (Japanese EBCDIC, CCSID=939), and both TDS_SERVER_CCSID and TDS_CLIENT_CCSID default to sjis (CCSID=943). The application calls TDRCVPRM:

When data is read by the server from the client, the data is in sjis.
When data is requested by the Server Option application from the server, the data is retrieved in EBCDIC CCSID=939.

TDESCRIB

The TDESCRIB API call now allows use of the TDSUNICHAR, TDSUNIVARCHAR, and TDSUNITEXT datatypes.

Table 5 lists new datatype conversions supported.

**Table 5: New datatype mappings**
Datatype	Datatype
TDSCHAR	TDSUNICHAR
TDSCHAR	TDSUNIVARCHAR
TDSCHAR	TDSUNITEXT
TDSVARCHAR	TDSUNICHAR
TDSVARCHAR	TDSUNIVARCHAR
TDSTEXT	TDSUNITEXT