Convert Data (QDCXLATE) API
Required Parameter Group:
| 1 | Length of data being converted | Input | Packed(5,0) |
| 2 | Conversion data | I/O | Char(*) |
| 3 | SBCS conversion table name | Input | Char(10) |
Optional Parameter Group:
| 4 | SBCS conversion table library name | Input | Char(10) |
| 5 | Output data | Output | Char(*) |
| 6 | Length of output buffer | Input | Packed(5,0) |
| 7 | Length of converted data | Output | Packed(5,0) |
| 8 | DBCS language | Input | Char(10) |
| 9 | Shift-out and shift-in characters | Input | Char(1) |
| 10 | Type of conversion | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: Yes
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).
This API is available for compatibility purposes or user-defined mappings only. Do not use this API in new development; instead, use the iconv()--Code Conversion API or the Convert a Graphic Character String (CDRCVRT) API.
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 i5/OS globalization topic collection. These tables are not the same as those used by the intersystem communications function (ICF) for conversion support. For more information, see Socket 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
| Message ID | Error Message Text |
|---|---|
| CPF2143 E | Cannot allocate object &1 in &2 type *&3. |
| CPF2144 E | Not authorized to &1 in &2 type *&3. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2619 E | Table &1 not found. |
| CPF264D E | Double-byte character set language not valid. |
| CPF264E E | Shift-in and shift-out value of double-byte character set not valid. |
| CPF264F E | Translation type of double-byte character set not valid. |
| CPF2647 E | Buffer length not valid. |
| CPF265E E | Number of parameters specified not valid. |
| CPF265F E | Translation length exceeded maximum length. |
| CPF2651 E | Table &1 not found. |
| CPF2669 E | Double-byte character set source not valid. |
| CPF269A E | Library parameter is not set to "QSYS " on call. |
| CPF269B E | T.61 conversion table not found. |
| CPF269C E | Error in input data. |
| CPF269D E | A nonspacing underline character was found in the input data. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF6309 E | Not authorized to library &1. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API existed prior to V1R3