
===============================================================================
                  Internationalization (I18N) For OS/2
===============================================================================

                Copyright IBM Corporation -- 1993, 1994, 1995

DISCLAIMER: This package is not a full implementation of the X/Open* XPG4
specification and does not make any claims of XPG4 branding.  It implements
only the portions of the XPG4 specification which deal with
internationalization.

*X/Open is a trademark of the X/Open Company Limited.

===============================================================================

/************************/
/***     Contents     ***/
/************************/

1.  Overview
2.  Locale model
3.  Common abbreviations
4.  Files in this directory
5.  Installing the package
6.  Environment variables
7.  Setting the LOCALE
8.  Linking with the I18N package
9.  About wide characters
10. Using the char datatype
11. Command-line programs provided
12. Installation Program
13. I18N API prototype summary
14. What's new in this version of the package
15. Recommended reading


1.  Overview
============

This package provides an internationalization toolkit for the development of
world-wide applications based on the X/Open Portability Guidelines, Issue 4
(XPG/4). This industry standard was developed to ensure portability,
interoperability, and consistency of user environments across all compliant
systems. The XPG/4 internationalization programming model has the following
features:

o Applications can be written in a language-independent way, so that a single
  version of the application can support users throughout the world. This
  eliminates the need for multiple language-specific versions and can
  dramatically reduce development, manufacturing and distribution costs.

o Applications can "automatically" interact with international users in their
  own language, correct cultural conventions, and national data encoding.

o The selection of localization features is user-definable through language
  environment variables. This announcement mechanism permits the dynamic
  loading of localization objects (locales), which give applications the
  correct cultural flavor.

o The language is determined by the user, not the system or application. The
  same application can be launched in different languages on the same
  workstation, by simply changing the language environment settings.

o New languages, countries and code pages can easily be supported by simply
  providing new locale objects, without requiring any change to applications.

o Locale objects contain information to support the following types of
  culturally correct processing:
  - date and time formatting
  - numerical formatting
  - monetary formatting
  - text sorting
  - character classification
  - character case conversion
  - processing of single or multi-byte character text
  - text processing using wide characters

o Utilities are provided to permit the packaging of application-specific
  translatable text in external message files. Messaging interfaces are
  provided to access the correct message language at run-time, as specified
  by the locale environment variables.


2.  Locale model
================

The I18N library is based on the concept of locale objects, which can be
loaded at run-time and provide all information which is specific to a
particular language/territory/code-page combination.

A territory is usually a country, but could be any geographical area.
A particular territory could have several different locales which correspond
to different languages. For example, Switzerland has locales for both the
German and French locales. Also, a particular language may be spoken in
several different territories and there may be several locales associated
with these combinations. For example, French is spoken in France, Canada,
Switzerland and Belgium, so that there are four locales corresponding to
these combinations. Finally, a particular language/territory combination
can be use with several different code pages. For example, English in the
US is available in three different locales, which support code pages
IBM-437, IBM-850 and IBM-819 (ISO8859-1).

In general, a locale name has the following format:

     Xx_YY.ZZZZZZZZ

where Xx is a language abbreviation, YY is a territory abbreviation, and
.ZZZZZZZZ is an code page name (generally "IBM-NNNN" where NNNN is a 3 or 4
digit codepage number).  So, to set the locale to US English, one could type:

     set LANG=En_US

The US English locale corresponding to the current process code page would
be then be loaded.

To force the locale for the IBM-437 code page, one could type:

     set LANG=En_US.IBM-437

The actual locales are stored in dynamic link libraries (in \i18n\locale). The
names of the .DLL files are similar to the full names shown above, but with
the underscore, period and "IBM-" removed.  So the default US English locale
DLL file is ENUS437.DLL. This is done to support FAT file systems, which
enforce file name lengths of 8.3.

The I18N package also provides the ability to define locale aliases.
These are stored in "\i18n\locale\ALIASES". The table consists of rows of
aliases. Each row contains the alias DLL name and the true DLL name,
separated by a space. The alias file is an ASCII text file, and can be edited.

Locale aliasing using the ALIASES file always takes place before any attempt
to load a locale.

The following is a list of locales provided in this release:

  DLL       Locale Name     Locale Description
  -----------------------------------------------------------------------
  (setloc1) C               Default locale if no locale DLL can be loaded.
  ARAA864   Ar_AA.IBM-864   Arabic in Arabic Area (Primary)
  ARAA1046  Ar_AA.IBM-1046  Arabic in Arabic Area (Alternate)
  BGBG915   Bg_BG.IBM-915   Bulgarian in Bulgaria
  CSCZ852   Cs_CZ.IBM-852   Czech in Czech Republic (Primary)
  CSCZ912   Cs_CZ.IBM-912   Czech in Czech Republic (ISO8859-2)
  DADK850   Da_DK.IBM-850   Danish in Denmark
  DECH850   De_CH.IBM-850   German in Switzerland
  DEDE850   De_DE.IBM-850   German in Germany (and Austria)
  ELGR869   El_GR.IBM-869   Greek in Greece
  ENGB850   En_GB.IBM-850   English in the U.K.
  ENUS437   En_US.IBM-437   English in the U.S. (Primary)
  ENUS850   En_US.IBM-850   English in the U.S. (Alternate)
  ENUS819   En_US.IBM-819   English in the U.S. (ISO8859-1)
  ESES850   Es_ES.IBM-850   Spanish in Spain
  FIFI850   Fi_FI.IBM-850   Finnish in Finland
  FRBE850   Fr_BE.IBM-850   French in Belgium
  FRCA850   Fr_CA.IBM-850   French in Canada
  FRCH850   Fr_CH.IBM-850   French in Switzerland
  FRFR850   Hr_FR.IBM-850   French in France
  HRHR852   Hr_HR.IBM-852   Croatian in Croatia (Primary)
  HRHR912   Hr_HR.IBM-912   Croatian in Croatia (ISO8859-2)
  HUHU852   Hu_HU.IBM-852   Hungarian in Hungary (Primary)
  HUHU912   Hu_HU.IBM-912   Hungarian in Hungary (ISO8859-2)
  ISIS850   Is_IS.IBM-850   Icelandic in Iceland
  ITIT850   It_IT.IBM-850   Italian in Italy
  IWIL862   Iw_IL.IBM-862   Hebrew in Israel (Primary)
  IWIL856   Iw_IL.IBM-856   Hebrew in Israel (Alternate)
  JAJP932   Ja_JP.IBM-932   Japanese in Japan (Primary)
  (alias)   Ja_JP.IBM-942   Japanese in Japan (Alternate)
  KOKR949   Ko_KR.IBM-949   Korean in Korea
  MKMK915   Mk_MK.IBM-915   Macedonian in Macedonia
  NLBE850   Nl_BE.IBM-850   Flemish in Belgium
  NLNL850   Nl_NL.IBM-850   Dutch in Netherlands
  NONO850   No_NO.IBM-850   Norwegian in Norway
  PLPL852   Pl_PL.IBM-852   Polish in Poland (Primary)
  PLPL912   Pl_PL.IBM-912   Polish in Poland (ISO8859-2)
  PTBR850   Pt_BR.IBM-850   Portuguese in Brazil
  PTPT850   Pt_PT.IBM-850   Portuguese in Portugal
  RORO852   Ro_RO.IBM-852   Romanian in Romania
  RURU866   Ru_RU.IBM-866   Russian in Russia (Primary)
  RURU915   Ru_RU.IBM-915   Russian in Russia (ISO8859-5)
  SHSP852   Sh_SP.IBM-852   Latin Serbian in Serbia (Primary)
  SHSP912   Sh_SP.IBM-912   Latin Serbian in Serbia (ISO8859-2)
  SLSI852   Sl_SI.IBM-852   Slovenian in Slovenia (Primary)
  SLSI912   Sl_SI.IBM-912   Slovenian in Slovenia (ISO8859-2)
  SKSK852   Sk_SK.IBM-852   Slovak in Slovakia (Primary)
  SKSK912   Sk_SK.IBM-912   Slovak in Slovakia (ISO8859-2)
  SRSP915   Sr_SP.IBM-915   Cyrillic Serbian in Serbia
  SVSE850   Sv_SE.IBM-850   Swedish in Sweden
  THTH874   Th_TH.IBM-874   Thai in Thailand
  TRTR857   Tr_TR.IBM-857   Turkish in Turkey
  ZHCN1381  Zh_CN.IBM-1381  Simplified Chinese in China
  ZHTW950   Zh_TW.IBM-950   Traditional Chinese in Taiwan (Primary)
  ZHTW948   Zh_TW.IBM-948   Traditional Chinese in Taiwan (Alternate)

In addition to using the 8.3 names (without the underscore or period) for
locale DLLs, the I18N package also uses those names for message catalog
directories.  So, suppose you had the following NLSPATH variable, and LANG
variable, with a process code page of 437:

     set NLSPATH=E:\I18N\MESSAGES\%L\%N
     set LANG=En_US

Further suppose you execute the following catalog open command in your program:

     cat_handle = catopen("my.cat", 0);

catopen would then attempt to find the following file:

     E:\I18N\MESSAGES\ENUS437\MY.CAT

That is because the locale (En_US) is remapped to ENUS437 (without the .DLL).
Look at the \I18N\MESSAGES directory in this package to see some of the locale
message directories provided.


3.  Common abbreviations
========================

The following are common abbreviations in the NLS programming world:

     Abbreviation       Meaning
     -------------------------------------------------------------------------
     NLS                National Language Support
     I18N               Internationalization
     I14Y               Interoperability
     L10N               Localization


4.  Files in this directory
===========================

The following files can be found in this directory:

File          Purpose
------------------------------------------------------------------------------
read.me       This file.
bin           .EXE and .CMD files for building message catalogs and setting
               environment variables.
dll           Required .DLL files.
include       Required header files.
locale        Files which implement the locales and converters.
lib           Required .LIB files.
ref           Contains technical reference (in OS/2 VIEW format).
doc           Documentation for commands in the bin directory.
sample        Sample programs to demonstrate the I18N APIs.


5.  Installing the package
==========================

     1. The package should already be unzipped in a directory \I18N.

        NOTE: In the instructions below, no drive letters are specified for
              environment variables.  You should substitute the proper letter
              for your installation.

     2. Add the \I18N\DLL path to your existing LIBPATH statement in your
        CONFIG.SYS file.  Before you use I18N make sure to reboot your system
        so the change in LIBPATH takes effect.

     3. Make sure that the IBM C SET/2 Compiler and OS/2 Toolkit are installed
        on your system, as they are prerequisites to compiling and linking the
        many examples in the \I18N\SAMPLES directory.

     4. Add the following to your CONFIG.SYS file
        (unless it is already there):

          SET LANG=<locale>

        where <locale> is a locale you prefer, such as en_US.

     NOTE: Steps 5-8 below are OPTIONAL.  A command file:
           \I18N\BIN\NEW_VARS.CMD is provided which sets the variables
           described below.  If you do not wish to permanently affect your
           environment, you may run the command file as needed.

     5. Add the \I18N\BIN path to your existing PATH statement in your
        CONFIG.SYS file.

     6. Add the \I18N\INCLUDE path to your existing INCLUDE statement in your
        CONFIG.SYS file.

     7. Add the \I18N\LIB path to your existing LIB statement in your
        CONFIG.SYS file.

     8. Add the following to your CONFIG.SYS file:

          SET LOCPATH=\I18N\LOCALE
          SET NLSPATH=\I18N\MESSAGES\%L\%N

        If these environment variables already exist in your CONFIG.SYS file,
        add the paths to the existing statements. For example:

          SET LOCPATH=\I18N\LOCALE;\PRODUCTX\LOCALE
          SET NLSPATH=\I18N\MESSAGES\%L\%N;\PRODUCTX\MESSAGES\%L\%N


6.  Environment variables
=========================

The following environment variables are used for internationalization to
determine the behavior of the system.  The variables are inherited as defaults
by the application at boot time from CONFIG.SYS or set directly via the SET
command.

     LOCPATH     specifies the search path(s) for the locale DLLs
                 Different paths are separated by semicolons.

     NLSPATH     specifies the search path(s) for locating the message catalog
                 files.  Different paths are separated by semicolons.

     LC_ALL      specifies the locale for all categories. Overrides LANG and
                 other LC_* environment variables.

     LC_COLLATE  specifies the locale for the LC_COLLATE (collation) category.

     LC_CTYPE    specifies the locale for the LC_CTYPE category. This category
                 determines character classification, case mappings and
                 multibyte/widechar character processing.

     LC_MESSAGES specifies the locale for the LC_MESSAGES (message catatlog)
                 category.

     LC_MONETARY specifies the locale for the LC_MONETARY (monetary formatting)
                 category.

     LC_NUMERIC  specifies the locale for the LC_NUMERIC (numeric formatting)
                 category.

     LC_TIME     specifies the locale for the LC_TIME (date/time formatting)
                 category.

     LANG        default setting of locale overridable by the preceding
                 environment variables.

When a call to setlocale is made, the settings are queried for priority level
as follows:

     If the LC_ALL environment variable is set, the value of the LC_ALL
     variable is used for all categories.

     If the LC_ALL environment variable is not set, the values specified
     for medium-priority environment variables (LC_COLLATE, LC_CTYPE,
     LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) are used.

     If individual LC_* environment variables are not set, the value of
     the LANG environment variable specifies the locale for all remaining
     categories.

     If the LANG environment variable is not set, the default locale (see
     below) is used for all remaining categories.



7.  Setting the LOCALE
======================

By design, an application program initially starts up with a default locale.
This default locale is determined during the setloc1.dll initialization by
first mapping the current country code and code page to the set of installed
locales.  Then the LANG and LC_* environment variables are examined and if
present, override this first default.

If a locale which uses code page 437 is not found, the US English
437 locale, enus437, is used instead.  If a locale which uses code page 850
is not found, the US English 850 locale, enus850, is used instead.

If no suitable default locale can be found, the "C" locale is used.

Most internationalized programs, however, must then change the locale for the
program to the locale set by the user.  This is done with a call to setlocale.
Upon calling the setlocale routine, the program's locale is again determined by
either the LANG, and LC_* environment variables, or directly by the 2nd
argument to setlocale.

Usually, the user will set one or more of the LC_* environment variables to
determine the locale of the program.  If all facets of a program (date/time/
monetary etc) are to be set to the same locale (which is common), the
LANG or LC_ALL environment variable should be set to that locale.  If one
or more features are to be set to a different locale, their environment
variable must also be set.

The following is the typical usage of the setlocale call:

     #include <wchar.h>
     #include <locale.h>

     main() {

     /* The LC_ALL and LANG environment variables set the program's locale */

       setlocale(LC_ALL, "");
     }

If, in the example above, the LC_ALL variable was set to en_US, and the
LC_MONETARY variable was set to fr_FR, all facets of the program would be
set to en_US, except the monetary formatting, which would be set to fr_FR.

Application programmers can also hardcode a locale for a program by setting
the second argument of setlocale to a locale value:

    setlocale(LC_NUMERIC, "it_IT");

This is generally *NOT* recommended.

Setlocale can also be used to query what locale is currently active for a given LC_* value, by
providing a NULL 2nd argument.  For example:

     ret_string = setlocale(LC_MESSAGES, NULL);

will return the setting of the messages locale for the program.


8.  Linking with the I18N package
=================================

The I18N library comes packaged in two parts:

  1) An import library (setloci.lib), which is linked with your applications.
  2) A dynamic link library (setloc1.dll), which is placed in the runtime
      machine's LIBPATH.

This implementation requires that case-sensitivity (the /NOI switch in
both CSet/2 and CSet++) be turned on whenever the setloci import library is
linked with an application.  This allows the lower-case APIs in the library
to be properly found at application load-time.

All of the sample programs illustrate how to use this switch when linking your
program.  See the ".mak" file in any of the sample directories for more
information.

*NOTE* The /NOI switch is *required*.  If it is not used, your application
will not function correctly.


9. About wide characters
=========================

The XPG4 programming model defines a new character datatype wchar_t for 16-bit
character code elements.  The wchar_t datatype extends the range of the
standard char datatype to 16-bit characters. In general programmers only need
to use this datatype when direct character manipulation is needed on multi-byte
character data.

Special functions are provided to convert between multi-byte and wchar strings
(see mbstowcs, wcstombs, mbtowc, and wctomb functions below), and to copy,
compare, or search wchar strings (see wcs* functions below).

As a programmer writing internationalized programs, you can not assume
anything about what value a wchar_t variable may contain, because it can vary
from locale to locale, and from vendor to vendor.

Instead, you must use the I18N functions to manipulate and test wchar_t
variables to insure proper operation of your program in an international
environment.  These functions are described, in detail, below.  Typically,
wide character functions either start with the prefix "wcs" (as in wcscpy -
wide character copy), or have the letter "w" inserted in the function
name (as in "iswalpha" - is the wide character an alphabetic character).

IMPORTANT:  Wide characters and strings *can* be represented in your program
            as literal values.  Place the capital letter 'L' in front of your
            literal characters and strings.

     Ex: wcscpy(a_wide_var, L"A wide char string!");
         if (a_wide_char_var == L'\0') ...


10. Using the char datatype
===========================

The char datatype is still used in most cases but now it may contain multi-byte
characters as defined in the specific locale. A multi-byte character is
composed of one or more bytes, with no imbedded null bytes. The standard C str*
functions are still used to manipulate these kinds of strings, with the
exception of:

     strcmp        doesn't handle < or > comparisons culturally. However,
                   strcmp still works for equal/not equal tests.  To determine
                   greater than/less than on strings, use the strcoll and
                   strxfrm functions.

     strchr        for character searching its not multi-byte aware
     strrchr       and so may find a single byte character amid a
                   multi-byte sequence.

     strncpy       is not multi-byte aware and may only copy only part
                   of a multi-byte character.

     strstr        is not multi-byte aware for single character strings but
                   will work with strings >1 character as the search key.


11. Command-line programs provided
==================================

     Program      Purpose
     -------------------------------------------------------------------------
     gencat       Constructs message catalog files.
     mkcatdef     Constructs message #define .h files to be used in an
                  application program to reference catalog file entries.
     runcat       A command file which builds both message catalogs, and
                  the include files for those catalogs (via mkcatdef and
                  gencat).
     cvtmsg       Converts an OS/2 mkmsgf input file into an XPG4 gencat
                  input file.
     locale       Displays the currently active locale categories.


12. Installation Program
========================

Included in this toolkit is a program that installs the I18N files required
for the runtime environment and configures the CONFIG.SYS information.
A SYSLEVEL file is also provided which the installation program uses for
version control.

It is a command line program (.EXE) which provides no user interface
other than the command line parameters.

This installation program can be used by any product wishing to install
the I18N toolkit runtime.

For more details VIEW the \I18N\REF\I18N.INF file or read the
\I18N\INSTALL\i18ninst.doc file.


13. I18N API prototype summary
==============================

      ***************************************************
      ** For more technical details on these functions **
      ** use VIEW on the \I18N\REF\I18N.INF file.      **
      ***************************************************

1. Runtime Locale load and data access functions:

     char *setlocale(int category, const char *locale);
     char *nl_langinfo(nl_item item);
     struct lconv *localeconv(void);

2. Character Attribute testing (Uses locale-based methods):

     int isalnum(int c);
     int isalpha(int c);
     int iscntrl(int c);
     int isdigit(int c);
     int isgraph(int c);
     int islower(int c);
     int isprint(int c);
     int ispunct(int c);
     int isspace(int c);
     int isupper(int c);
     int isxdigit(int c);

     int toupper(int c);
     int tolower(int c);

     int iswalnum(wint_t wc);
     int iswalpha(wint_t wc);
     int iswcntrl(wint_t wc);
     int iswdigit(wint_t wc);
     int iswgraph(wint_t wc);
     int iswlower(wint_t wc);
     int iswprint(wint_t wc);
     int iswpunct(wint_t wc);
     int iswspace(wint_t wc);
     int iswupper(wint_t wc);
     int iswxdigit(wint_t wc);

     int iswctype(wint_t wc, wctype_t mask);

     wint_t towupper(wint_t wc);
     wint_t towlower(wint_t wc);


3. Date and Time Formatting:

     size_t strftime(char *s, size_t maxsize, const char *format,
                      const struct tm *tm);

     size_t strfmon(char *s, size_t maxsize, const char *format, ...);

     char  *strptime(const char *buf, const char *fmt, struct tm *tm);

     size_t wcsftime(wchar_t *wcs, size_t maxsize, const char *format,
                     const struct tm *tm);


4. File IO functions which use mbtowc transformations:

     wint_t   fgetwc(FILE *stream);
     wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);

     wint_t   fputwc(wint_t wc, FILE *stream);
     int      fputws(const wchar_t *ws, FILE *stream);

     wint_t   getwc (FILE *stream);
     wint_t   putwc(wint_t wc, FILE *stream);
     wint_t   ungetwc(wint_t wc, FILE *stream);

     wint_t   getwchar(void);
     wint_t   putwchar(wint_t wc);

     int      getw(register FILE *stream);
     int      putw(int w, register FILE *stream);

5. The basic conversion methods between multibyte <--> wchar_t:

     int    mblen(const char *s, size_t n);
     size_t mbstowcs(wchar_t *ws, const char *s, size_t n);
     int    mbtowc(wchar_t *wc, const char *s, size_t n);
     size_t wcstombs(char *s, const wchar_t *ws, size_t n);
     int    wctomb(char *s, wchar_t wchar);

6. Basic String manipulation API for wchar_t data type:

     wchar_t *wcscat  (wchar_t       *ws1, const wchar_t *ws2);
     wchar_t *wcschr  (wchar_t       *ws1, wint_t         wc);
     int      wcscmp  (const wchar_t *ws1, const wchar_t *ws2);
     wchar_t *wcscpy  (wchar_t       *ws1, const wchar_t *ws2);
     size_t   wcscspn (const wchar_t *ws1, const wchar_t *ws2);
     size_t   wcslen  (const wchar_t *ws);
     wchar_t *wcsncat (wchar_t       *ws1, const wchar_t *ws2, size_t n);
     int      wcsncmp (const wchar_t *ws1, const wchar_t *ws2, size_t n);
     wchar_t *wcsncpy (wchar_t       *ws1, const wchar_t *ws2, size_t n);
     wchar_t *wcspbrk (const wchar_t *ws1, const wchar_t *ws2);
     wchar_t *wcsrchr (wchar_t       *ws1, wint_t         wc);
     size_t   wcsspn  (const wchar_t *ws1, const wchar_t *ws2);
     wchar_t *wcstok  (wchar_t       *ws1, const wchar_t *ws2);
     wchar_t *wcswcs  (const wchar_t *ws1, const wchar_t *ws2);
     int      wcswidth(const wchar_t *ws, size_t n);
     wctype_t wctype(const char *charclass);
     int      wcwidth(wchar_t wc);

7. Wide character print/scan formatting:

     fscanf/scanf/sscanf with %S, %C decoding, and parameter
                            reordering via the (%n$x) format

     fprintf/printf/sprintf with %S, %C encoding, and parameter
                            reordering via the (%n$x) format

     vfprintf/vprintf/vsprintf with %S, %C encoding, and parameter
                            reordering via the (%n$x) format

8. Collations:

     int    strcoll(const char *s1, const char *s2);
     size_t strxfrm(char *s1, const char *s2, size_t n);

     int    wcscoll(const wchar_t *ws1, const wchar_t *ws2);
     size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);

9. Conversions:

     long wcstol(const wchar_t *nptr,
                       wchar_t **endptr, int base);
     unsigned long wcstoul(const wchar_t *nptr,
                                 wchar_t **endptr, int base);

     double wcstod(const wchar_t *nptr, wchar_t **endptr);
     double strtod(const char *nptr, char **endptr);

10. Messages:

     nl_catd   catopen(const char *name, int oflag);
     char     *catgets(nl_catd catd, int setid, int msgid, const char *s);
     int       catclose(nl_catd catd);

11. Regular expression functions:

     int regcomp(regex_t *preg, const char *pattern, int cflags);
     int regexec(const regex_t *preg, const char *string,
                 size_t nmatch, regmatch_t pmatch[], int eflags);
     size_t regerror(int errcode, const regex_t *preg,
                     char *errbuf, size_t errbuf_size);
     void regfree(regex_t *preg);

12. Non-XPG4 case insensitive compare and case conversion functions:

     char *strlwr(char *s);
     char *strupr(char *s);
     int strcmpi(const char *s1, const char *s2);
     int stricmp(const char *s1, const char *s2);
     int strnicmp(const char *s1, const char *s2, size_t n);
     int memicmp(void *s1, void *s2, unsigned int n);

13. Helper functions:

     double get_i18n_version(void);

14. Code Set Conversion Functions:

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

    size_t  iconv(iconv_t cd, const char **inbuf, size_t *inbytesleft,
                                    char **outbuf, size_t *outbytesleft);

    int     iconv_close(iconv_t cd);


14. What's new in this version of the package
=============================================

Version 1.04 (02/01/96)
-----------------------

- Installation program has been modified.  Will now default a value for
  the LANG environment variable if it is not specified on the call to
  install and it doesn't exist in the config.sys file.

- Updated conversion tables used by iconv.

- The mkcatdef utility no longer appends "_msg" to the name of the include
  file it generates.

- Fixed miscellaneous problems with the gencat and mkcatdef utilities.


Version 1.03 (12/08/95)
-----------------------

- Installation program for installing necessary runtime files,
  updating config.sys and a syslevel file for version checking.

- Added updates and corrections to the I18N.INF file.

- Deleted sample installation program.

- Improved compatibility with older locales.


Version 1.02 (10/20/95)
-----------------------

- iconv conversion support based on ISO10646 UCS-2:
    i18n\lib\iconv.lib - static link library for iconv APIs
    i18n\include\iconv.h - iconv include file
    i18n\locale\iconv\ucstbl.dll - DLL for all table-driven conversions
    i18n\locale\iconv\utf-8.dll - DLL for UTF-8 conversions
    i18n\locale\iconv\iconv.lst - alias file for UCS-2 conversions
    i18n\locale\uconvtab\* - binary form of mapping tables
    i18n\locale\uconvtab\uconv.lst - alias file for UCS-2 mapping tables
    i18n\sample\iconv\* - sample conversion program

- new locales:
    Cs_CZ.IBM-912
    Hr_HR.IBM-912
    Hu_HU.IBM-912
    Pl_pl.IBM-912
    Ro_ro.IBM-912
    Ru_ru.IBM-915
    Sh_sp.IBM-912
    Sk_sk.IBM-912
    Sl_si.IBM-912

- improved locale aliasing:
    Ja_JP.IBM-942 supported as alias of Ja_JP.IBM-932
    any missing 850 locales aliased to En_US.IBM-850 unless specified
       in alias table
    any missing 437 locales aliased to En_US.IBM-437 unless specified
       in alias table

- Minor bug fixes in:
  wunget()
  strfmon()
  regcomp()
  regexec()
  printf() family of APIs
  scanf() family of APIs

- Cleaned up version of wchar.h


Version 1.00 (4/18/95)
----------------------

- The setlocale() function will now work with the older locale formats.
- Bug fixes in fscanf().
- Install utility bug fixes.

- Appending a major version number (only major bug fixes will cause this
  to increment) to setloc.dll.

           was setloc.dll   -->  now setloc1.dll


- Added defines to version.h header file for version number and
  module name identification to be used by install programs.

           #define I18N_VERSION_NUM    1.00
           #define MODULE_NAME      "SETLOC1"



15. Recommended reading
=======================

The Library of NLS recommends the following books:

     GG24-3850   Intl Tech Supt Center AIX 3.2 Natl Lang Support (IBM publ)
     SC23-2431   Internationalization of AIX Software: A Programmer's Guide
     XOPEN       X/Open CAE Specification, Issue 4 (X/Open Company Ltd)


============================================================================
End of Read.Me File
============================================================================
