#include <iconv.h>
iconv_t iconv_open (tocode, fromcode)
char *tocode;
char *fromcode;
The iconv_open() function performs the necessary initializations to convert character encodings from the source CCSID identified by the fromcode parameter to the CCSID identified by the tocode parameter. 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 QtqIconvOpen() API except that the input types of fromcode and tocode are character strings.
The conversion descriptor remains valid in a job until that job closes it 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 a string containing the CCSID to convert to. See Format of fromcode and tocode for the layout of this string.
A pointer to the string containing the CCSID to convert from, the type of conversion to perform, the substitution alternative, the shift-state alternative, the input length option, and the mixed error option. See Format of fromcode and tocode for the layout of this string.
The fromcode string consists of the following.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | The word IBMCCSID |
| 8 | 8 | CHAR(5) | Character representation of CCSID number |
| 13 | D | CHAR(3) | Conversion alternative |
| 16 | 10 | CHAR(1) | Substitution alternative |
| 17 | 11 | CHAR(1) | Shift-state alternative |
| 18 | 12 | CHAR(1) | Input length option |
| 19 | 13 | CHAR(1) | Error option for mixed data |
| 20 | 14 | CHAR(12) | Reserved |
The tocode string consists of the following.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | The word IBMCCSID |
| 8 | 8 | CHAR(5) | Character representation of CCSID number |
| 13 | D | CHAR(19) | Reserved |
Character representation of CCSID number. A character representation of the CCSID number to convert from or to. Valid CCSID values are in the range 00001 through 65533. The following special value is supported on the fromcode and tocode parameters:
| 00000 | 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. The following values can be used:
| 000 | 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 i5/OS globalization topic collection. |
| 057 | The enforced subset match (substitution) criterion. For the CCSID conversion pairs that support this criterion, see i5/OS globalization. |
| 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 set (DBCS) characters.
| 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 to the end of the input buffer being converted; 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 being 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. 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(). 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. 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 (057) for the conversion alternative field. Performance is decreased when using this alternative. |
The word IBMCCSID. The 8-byte character field that contains the characters I, B, M, C, C, S, I, D. The characters must be in uppercase.
If successful, iconv_open() 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, iconv_open() returns -1 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. |
This API is threadsafe if threads that share a conversion descriptor do not attempt to preserve the shift state.