iconv_open() — Allocate code conversion descriptor

Standards

Standards / Extensions	C or C++	Dependencies
XPG4 XPG4.2 Single UNIX Specification, Version 3	both

Format

#include <iconv.h>

iconv_t iconv_open(const char *tocode, const char *fromcode);

General description

Performs all the initialization needed to convert characters from the encoded character set specified in the array pointed to by the fromcode argument to the encoded character set specified in the array pointed to by the tocode argument.

The conversion descriptor relates the two encoded character sets.

For state-dependent encodings, the conversion descriptor will be in an encoded-character-set-dependent initial shift state, ready for immediate use with iconv(). The conversion descriptor remains valid until it is closed with iconv_close().

Settings of fromcode, tocode, and their permitted combinations are implementation-dependent.

Note: The iconv() family of functions has been modified to utilize character conversion services provided by Unicode Services. The iconv_open(), iconv() and iconv_close()’s function interfaces will remain unchanged except for the addition of four new errno values and two new environment variables described in the following paragraphs.

There are differences in externals between the iconv() family of functions and Unicode Services. However, these differences will be managed by the iconv() family of functions except where noted in the z/OS XL C/C++ Compiler and Runtime Migration Guide for the Application Programmer. All conversions listed in the topic of the z/OS XL C/C++ Programming Guide entitled “Code Set Converters Supplied” will continue to work as they did prior to the integration of Unicode Services, as long as _ICONV_TECHNIQUE is left undefined. If the application does not define the _ICONV_TECHNIQUE environment variable, iconv_open() uses a default value of LMREC.

Unicode Services supports conversions between thousands of additional character sets not listed in the z/OS XL C/C++ Programming Guide. A complete list of conversions supported by Unicode Services can be found in the z/OS Unicode Services User's Guide and Reference. To set up a conversion using iconv_open() for any of the character sets listed in these tables, the user needs to use a character string representing the CCSID’s for fromcode and tocode. For example, to set up a conversion from CCSID 00256 to CCSID 00870 using conversion technique R, the user would set the _ICONV_TECHNIQUE environment variable to R and call iconv_open() as follows:

cd = iconv_open(“00870”, “00256”);

and continue to use iconv() and iconv_close() as in previous releases.

iconv() uses the following environment variables.

_ICONV_UCS2: Tells iconv_open(Y, X) what type of conversion method to setup when there is a choice between "direct" conversion from X to Y and "indirect" X to UCS-2 to Y.
_ICONV_UCS2_PREFIX: Tells iconv_open() what z/OS® dataset name prefix to use to find UCS-2 tables if they cannot be found in the HFS.
_ICONV_MODE: Selects the behavior mode for iconv_open(), iconv() and iconv_close()..
_ICONV_TECHNIQUE: This is the technique value used while using Unicode Conversion Services. For more information regarding the Unicode Conversion Services technique value, refer to topic - Creating a Unicode Environment of the z/OS Unicode Services User's Guide and Reference.

For illustration of using iconv_close(), see Example.

Special considerations for bidirectional language support: Performs all the initialization needed to activate the bidirectional layout transformation to be used by iconv. The following three conditions must be satisfied to enable the bidirectional layout transformation:

The _BIDION environment variable must be set to TRUE.
The current locale environment at iconv_open() time must be an Arabic or Hebrew locale (eg. Ar_AA or Iw_IL).
The conversion code set must be an Arabic or Hebrew code set.

Conversion code sets differ in the following three cases:

Case fromCodeSet is UCS-2 and toCodeSet is single byte code set. In this case toCodeSet must be an Arabic or Hebrew code set.
Case fromCodeSet is single byte code set and toCodeSet is UCS-2. In this case fromCodeSet must be an Arabic or Hebrew code set.
Case both fromCodeSet and toCodeSet are single byte code sets. In this case toCodeSet must be an Arabic or Hebrew code set.

iconv_open( ) checks for the existence of the environment variable _BIDIATTR to get the bidirectional layout transformation attributes. It will use default values in case _BIDIATTR is not defined, is unset, or in case of the existence of some erroneous values in the _BIDIATTR environment variable. The default values are code set dependent according to the Arabic or Hebrew code set used. For the Arabic 420 code set the default values will be: orientation RTL, type of text visual, shaping shaped, numerals national and swapping on. For the Hebrew 424 code set the default values will be: orientation RTL, type of text visual and swapping on. For the rest of the Arabic code sets the default values will be: orientation RTL, type of text implicit, shaping nominal, numerals national and swapping on.

iconv_open() uses the following environment variables.

_BIDION: Tells iconv_open() whether to activate bidirectional handling of the converted data or not. _BIDION can be assigned either the value TRUE, if you want to turn on bidirectional layout transformation, or the value FALSE, if you want to turn off the BiDi layout transformation. Bidirectional layout transformation can also be turned off if the variable_BIDION is not defined in the environment.
_BIDIATTR: Holds the bidirectional layout transformation attributes which will be used later by iconv, _BIDIATTR will be read only in iconv_open() time. The _BIDIATTR environment variable is in the form of input/output pairs separated by colon, at the beginning of the string there is an @ that identifies the beginning of the attributes list, then followed by the attributes in the form of <attribute_name1>=<input1>:<output1>, <attribute_name2>=<input2>:<output2> ..... (eg. export _BIDIATTR="@ls typeoftext=visual:implicit,orientation=ltr:ltr, numerals=nominal:national").