QtqIconvOpen()--Code Conversion Allocation API

  iconv_t QtqIconvOpen (tocode, fromcode)



              QtqCode_T   *tocode;
              QtqCode_T   *fromcode;

  Service Program: QTQICONV

  Default Public Authority: *USE

  Threadsafe: Yes

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.

Authorities and Locks

None.

Parameters

tocode: INPUT
A pointer to the structure containing the CCSID to convert to. For the layout of this structure, see Format of QtqCode_T.
fromcode: INPUT
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.

Format of QtqCode_T

The QtqCode_T structure consists of the following.

Offset

Type

Field

Dec

Hex

BINARY(4)

CCSID

BINARY(4)

Conversion alternative

BINARY(4)

Substitution alternative

BINARY(4)

Shift-state alternative

BINARY(4)

Input length option

BINARY(4)

Error option for mixed data

CHAR(8)

Reserved

Field Descriptions

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:

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:

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.

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:

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

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.

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:

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 for the conversion alternative. Performance is decreased when using this alternative.

Return Value

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.

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.

Related Information

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

API introduced: V3R1

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