The unichar, univarchar, and unitext datatypes have been added for Unicode support in the Client Option. These three datatypes are mapped to TDS_LONGBINARY with a user type of 34, 35, or 36, as shown in Table 4.
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 Client Option has the following three datatypes to support unichar, univarchar, and unitext:
CS_UNICHAR_TYPE – Internal type 21
CS_UNIVARCHAR_TYPE – Internal type 22
CS_UNITEXT_TYPE – Internal type 23
Currently, there is no special support for CS_UNITEXT_TYPE.
The following API calls have been changed in the Client Option to accommodate support for Unicode:
COBOL API names are used here to illustrate use. The
API names for C are different but behave the same as those for COBOL.
The CHARSETCNV property of the CTBCONPROPS API call is used to change the default character set sent to the server at login. The CHARSETCNV is a login property and must be specified before a connection is established for its value to be effective. If the value of the CHARSETCNV property is not specified before the CTBCONNECT API call, the connection is established with the default communication character set, iso_1.
The following properties are new for the CTBCONPROPS API call:
CS_CLIENT_CCSID – defines the CCSID to which the Client Option converts server data.
CS_SERVER_CCSID – defines the CCSID to which the Client Option converts client data.
CS_PROG_CCSID – controls the conversion of data from the client character set to the character set used by the client application program. For example, a client application program may use CCSID=500 while the client data, received from the server, is in UTF-8.
CS_DATA_CCSID – controls the conversion of metadata.
CTBCONPROPS 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.
For a connection established with the UTF-8 character
set, the default values for the CS_CLIENT_CCSID, CS_SERVER_CCSID, CS_PROG_CCSID, and CS_DATA_CCSID parameters
are 1208, 1208, 500,
and 500, respectively.
This COBOL example changes the login character set from the default iso_1 to UTF-8:
MOVE ‘utf8’ to CHARSET. MOVE 4 to BUFLEN. CALL ‘CTBCONPR’ USING CON RET-CODE CS-SET CS-CHARSETCNV CHARSET BUFLEN CS-FALSE OUTLEN.
Thereafter, the Client Option automatically converts all character datatypes to and from UTF-8, unless otherwise specified.
The next COBOL example illustrates how the value of CS_PROG_CCSID can be changed from 500 to 1208:
05 PF-CCSID PIC S9(9) COMP VALUE +0. 05 PF-CCSID-SIZE PIC S9(9) COMP VALUE +4. ………………………………………………………………………………………………………………………………… MOVE 1208 TO PF-CCSID. CALL 'CTBCONPR' USING CSL-CON-HANDLE CSL-RC CS-SET CS-PROG-CCSID PF-CCSID PF-CCSID-SIZE CS-FALSE OUTLEN.
Thereafter, all program data is presented to the application in UTF-8 as it is received by the Client Option.
The Client 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.
The CTBDESCR API call now returns CS_UNICHAR_TYPE, CS_UNIVARCHAR_TYPE, and CS_UNITEXT_TYPE instead of CS_LONGBINARY_TYPE when the user type is 34, 35, or 36, respectively.
The CTBBIND API call allows the implicit conversion between the CS_UNICHAR, CS_UNIVARCHAR, and CS_UNITEXT datatypes and the CS_CHAR, CS_VARCHAR, and CS_TEXT datatypes. The CCSIDs used in this conversion are 1200 (UTF-16) and CS_PROG_CCSID (the CCSID used by the client application).
The CTBFETCH API call automatically converts incoming CS_UNICHAR, CS_UNIVARCHAR, and CS_UNITEXT data to the datatype specified by CTBBIND.
