iconv_open()--Code Conversion Allocation API

Syntax

 #include <iconv.h>

 iconv_t iconv_open (tocode, fromcode)



           char       *tocode;
           char       *fromcode;

  Service Program: QTQICONV

  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

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.

Authorities and Locks

None.

Parameters

tocode: INPUT
A pointer to a string containing the CCSID to convert to. See Format of fromcode and tocode for the layout of this string.
fromcode: INPUT
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.

Format of fromcode and tocode

The fromcode string consists of the following.

Offset

Type

Field

Dec

Hex

CHAR(8)

The word IBMCCSID

CHAR(5)

Character representation of CCSID number

CHAR(3)

Conversion alternative

CHAR(1)

Substitution alternative

CHAR(1)

Shift-state alternative

CHAR(1)

Input length option

CHAR(1)

Error option for mixed data

CHAR(12)

Reserved

The tocode string consists of the following.

Offset

Type

Field

Dec

Hex

CHAR(8)

The word IBMCCSID

CHAR(5)

Character representation of CCSID number

CHAR(19)

Reserved

Field Descriptions

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.

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.

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:

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.

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:

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.

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:

The number of substitution characters encountered is not returned.

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.

Return Value

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.

Error Conditions

The following errors can be returned in errno:

[EFAULT]

Bad address

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.

[EINVAL]

Parameter not valid.

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.

[ENOMEM]

Not enough space.

Insufficient storage space is available.

[EUNKNOWN]

Undetected error

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.

Usage Notes

This API is threadsafe if threads that share a conversion descriptor do not attempt to preserve the shift state.

Related Information

iconv()--Code Conversion API
iconv_close()--Code Conversion Deallocation API

API introduced: V3R1

[ Back to top | UNIX-Type APIs | APIs by category ]