Convert Data (QDCXLATE) API

The Convert Data (QDCXLATE) API converts data through the use of a table object. (If you need to convert the case of your data, it is recommended that you use the Convert Case (QLGCNVCS, QlgConvertCase API.) You also can use the equivalent API QTBXLATE to achieve the same function. The call interface to QTBXLATE is identical to Convert Data (QDCXLATE).

You can create the conversion table that QDCXLATE uses for the conversion, or you can use an IBM-supplied table. The IBM-supplied tables can be found in the QUSRSYS library. For a list of both the conversion tables and the casing tables, see the Globalization topic in the iSeries Information Center. These tables are not the same as those used by the intersystem communications function (ICF) for conversion support. For information on this, see Sockets Programming.

You can create your own conversion tables using the Create Table (CRTTBL) command.

When the QDCXLATE API is called with parameters 1, 2, 3, and 4, it converts single-byte data. When all parameters are specified, DBCS conversion is taking place.

The QDCXLATE API can distinguish double-byte from single-byte characters when converting from EBCDIC to ASCII and from ASCII to EBCDIC if the proper parameters have been supplied. The QDCXLATE API converts data byte for byte and returns the converted data to your program.

When only single-byte data is converted, the input (unconverted) data is replaced with the converted data. When double-byte data is converted, the converted data is placed in the output data parameter.

The QDCXLATE API is thread safe only when converting single-byte data or T.61 data.

Authorities and Locks

Table Authority

*USE

Table Library Authority

*USE

Required Parameter Group

Length of data being converted

INPUT; PACKED(5,0)

The length of the data being converted. This value cannot exceed 32 767.

Conversion data

I/O; CHAR(*)

The data to be converted. This buffer also contains the output data after conversion when the API is called with only the required parameter group.

SBCS conversion table name

INPUT; CHAR(10)

The name of the single-byte character set (SBCS) conversion table to be used. The table may be a system-supplied or user-supplied conversion table. The table name must be left-justified.

Note: This parameter is ignored when the DBCS language parameter is set to *BG5, *KSC, *SCGS *J90X5026, *J90X5035, or *SCGBK.

Optional Parameter Group

SBCS conversion table library name

INPUT; CHAR(10)

The name of the library that contains the SBCS conversion table. The library name must be left-justified. If this parameter is not specified, the library list is used to locate the conversion table. This parameter is ignored when the DBCS language parameter is set to *BG5, *KSC, *SCGS, *J90X5026, *J90X5035 or *SCGBK.

Output data

OUTPUT; CHAR(*)

The output buffer that contains the double-byte character set (DBCS) data that was converted.

Because of the insertion of shift-out and shift-in characters, it is possible that the converted data is longer than the source data. If this is the case, it is not possible to do the conversion in place, as is done when you use only a required-parameter-group call. The converted data is then placed in the area pointed to by this parameter.

Length of output buffer

INPUT; PACKED(5,0)

The size of the output data buffer. The maximum length should match the actual size of the output data parameter. If the converted output is longer than the length of output buffer parameter, an exception is signaled.

Length of converted data

OUTPUT; PACKED(5,0)

The actual length of the converted output in the output data parameter.

DBCS language

INPUT; CHAR(10)

The DBCS language that is being converted. All values must be padded on the right with blanks. The possible values follow:

*JPN	IBM Japanese graphic character set
*KOR	IBM Korean graphic character set
*CHS	IBM Simplified Chinese graphic character set
*CHT	IBM Traditional Chinese graphic character set
*BG5	Taiwan industry standard graphic character set (BIG-5)
*KSC	Korean industry standard graphic character set (KS)
*SCGS	The People's Republic of China National standard graphic character set (GB)
*J90X5026	The Japanese JIS X 0208 1990 standard mapped using CCSID 5026.
*J90X5035	The Japanese JIS X 0208 1990 standard mapped using CCSID 5035.
*SCGBK	The People's Republic of China National standard graphic character set extended (GBK)

Shift-out and shift-in characters

INPUT; CHAR(1)

Whether shift-out and shift-in characters should be inserted during the conversion. This parameter is ignored when the DBCS language parameter is set to *BG5, *KSC, *SCGS, *J90X5026, *J90X5035 or *SCGBK. The possible values follow:

Y	Insert shift-out and shift-in characters
N	Do not insert shift-out and shift-in characters

Type of conversion

INPUT; CHAR(10)

The type of DBCS conversion being done. The possible values follow:

*AE	Convert ASCII to EBCDIC
*EA	Convert EBCDIC to ASCII

Note: You are responsible for specifying the correct SBCS table name for the type of conversion being done by this DBCS request except when the DBCS language parameter is set to *BG5, *KSC, *SCGS, *J90X5026, *J90X5035 or *SCGBK.

Error Messages