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.

The tocode string consists of the following.



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:

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:

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.

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:

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:

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 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:



Usage Notes

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


Related Information



API introduced: V3R1

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