iconv_t QtqIconvOpen (tocode, fromcode)
QtqCode_T *tocode;
QtqCode_T *fromcode;
The QtqIconvOpen() function performs the necessary initializations to convert character encodings from the source CCSID identified by the fromcode to the CCSID identified by the tocode. It then returns a conversion descriptor of data type iconv_t. For EBCDIC mixed-byte encodings, the conversion descriptor is set to the initial single-byte shift state.
Note: This API performs the same function as the iconv_open() API except that the input type of fromcode and tocode is of data type QtqCode_T.
The conversion descriptor remains valid in a job until that job closes with iconv_close() or the job ends. Keeping unneeded conversion descriptors active results in storage being allocated for these. To reduce this storage, you should call the iconv_close() API if you no longer need this conversion descriptor. The number of active descriptors is limited to a maximum of 104 000 active descriptors per process. This number may be reduced if the job has many active threads.
None.
A pointer to the structure containing the CCSID to convert to. For the layout of this structure, see Format of QtqCode_T.
A pointer to the structure containing the CCSID to convert from, the type of conversion to perform, the substitution alternative, and the shift-state alternative. For the layout of this structure, see Format of QtqCode_T.
The QtqCode_T structure consists of the following.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | CCSID |
| 4 | 4 | BINARY(4) | Conversion alternative |
| 8 | 8 | BINARY(4) | Substitution alternative |
| 12 | C | BINARY(4) | Shift-state alternative |
| 16 | 10 | BINARY(4) | Input length option |
| 20 | 14 | BINARY(4) | Error option for mixed data |
| 24 | 18 | CHAR(8) | Reserved |
CCSID. The CCSID to convert from or to. Valid CCSID values are in the range 1 through 65533. The following special value is supported on the fromcode and tocode parameters:
| 0 | The conversion descriptor is created with the CCSID of the current job such that calls to iconv() with the conversion descriptor use the CCSID of the job at the time the conversion descriptor was opened by iconv_open(). If the CCSID of the current job is 65535 (indicating no conversion), the default CCSID from the DFTCCSID job attribute is used. |
Conversion alternative. The conversion alternative that is selected to convert graphic character data. This value is only used on the fromcode parameter; it is ignored on the tocode parameter. The following values can be used:
| 0 | The IBM-defined default conversion method and the associated conversion tables. Most of the default tables follow the round-trip conversion criterion. For the default tables that do not follow the round-trip conversion criterion, see the IBM i globalization topic collection. |
| 57 | The enforced subset match (substitution) criterion. For the CCSID conversion pairs that support this criterion, see the IBM i globalization topic collection. |
| 102 | The best-fit conversion criterion for character mismatch. |
Error option for mixed data. Whether iconv() returns an error when it converts a character string from a mixed-byte encoding scheme and the input buffer contains double-byte character (DBCS) characters.
Note: This is only valid on the fromcode parameter and only used if the target CCSID is SBCS.
Valid values are:
| 0 | An error is not returned when converting from a mixed-byte encoding scheme and the input buffer contains DBCS characters. Instead, iconv() converts the DBCS characters to the CDRA-standardized control character substitute of the target CCSID. |
| 1 | An ECONVERT error is returned in errno when iconv() encounters a DBCS character in the input buffer when converting from a mixed-byte encoding scheme. |
Input length option. Whether iconv() determines the number of bytes to the end of the input buffer being converted. This value is only used on the fromcode parameter. The possible values follow:
| 0 | The conversion descriptor is created such that the iconv() function does not determine the number of bytes; therefore, a valid value for the inbytesleft parameter must be specified. |
| 1 | The conversion descriptor is created such that the iconv() function determines the number of bytes to the end of the input buffer to be converted; therefore, the input buffer must end with a NULL character. The resulting converted output buffer is ended with a NULL character by iconv(). The inbytesleft parameter must point to a value of zero. |
Reserved. A reserved field that must be set to hexadecimal zeros.
Shift-state alternative. Whether the shift state should be restored to its initial shift state before conversion is performed by iconv(). This value is only used on the fromcode parameter; it is ignored on the tocode parameter. The following values can be used:
| 0 | The conversion descriptor is not returned to its initial shift
state.
Note: The conversion descriptor can still be returned to its initial shift state by making a separate call to iconv(). The inbuf must be equal to a null pointer or pointing to a null pointer. |
| 1 | The conversion descriptor is always returned to its initial shift state. |
Substitution alternative. Whether the number of substitution characters encountered in the converted output data is returned by iconv(). This value is only used on the fromcode parameter; it is ignored on the tocode parameter. The following values can be used:
| 0 | The number of substitution characters encountered is not returned. |
| 1 | The number of substitution characters encountered is returned.
This number may be equal to or greater than the actual number of nonidentical
conversions (substitutions) performed. The substitution character for a
particular encoding scheme is defined in the Character Data Representation
Architecture (CDRA).
Note: This value for the substitution alternative is valid only when using the enforced subset conversion criterion for the conversion alternative. Performance is decreased when using this alternative. |
If successful, QtqIconvOpen() returns a conversion descriptor of data type iconv_t. This conversion descriptor must be passed unchanged as an input parameter to the iconv() and iconv_close() functions.
If unsuccessful, QtqIconvOpen() returns -1 and in the return value of the conversion descriptor and sets errno to indicate the error.
The following errors can be returned in errno:
The system detected an address that was not valid when attempting to use an argument from the parameter list. An escape message may also be signaled as a result.
The conversion specified in the fromcode and tocode parameters is not supported.
When an errno value of EINVAL is returned, check the fromcode and tocode parameters for CCSIDs that are not valid or unsupported alternatives and options.
Insufficient storage space is available.
An undetected error occurred. Contact your service organization. An escape message may also be signaled as a result.
The following escape messages can be signaled:
| Message ID | Escape Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |