home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / i18nv102.zip / READ.ME
Text File  |  1995-09-18  |  33KB  |  830 lines
  1.  
  2. ===============================================================================
  3.                   Internationalization (I18N) For OS/2                 
  4. ===============================================================================
  5.  
  6.                 Copyright IBM Corporation -- 1993, 1994, 1995
  7.  
  8. DISCLAIMER: This I18N package has been made available solely to gauge OS/2
  9. developer interest in the industry standard XPG4 internationalization 
  10. programming model. This does not mean that IBM will introduce a product based
  11. on the contents of this package. This package is not a full implementation of 
  12. the X/Open* XPG4 specification and does not make any claims of XPG4 branding. 
  13. It implements only the portions of the XPG4 specification which deal with 
  14. internationalization.
  15.  
  16. *X/Open is a trademark of the X/Open Company Limited.
  17.  
  18. ===============================================================================
  19.  
  20. /************************/
  21. /***     Contents     ***/
  22. /************************/
  23.  
  24. 1.  Overview
  25. 2.  Locale model
  26. 3.  About this package
  27. 4.  Common abbreviations
  28. 5.  Files in this directory
  29. 6.  Installing the package
  30. 7.  Environment variables
  31. 8.  Setting the LOCALE
  32. 9.  Linking with the I18N package
  33. 10. About wide characters
  34. 11. Using the char datatype
  35. 12. Command-line programs provided
  36. 13. I18N API prototype summary
  37. 14. What is new in this version of the package
  38. 15. What is not included in this package
  39. 16. Recommended reading
  40.  
  41.  
  42. 1.  Overview
  43. ============
  44.  
  45. This package provides an internationalization toolkit for the development of
  46. world-wide applications based on the X/Open Portability Guidelines, Issue 4 
  47. (XPG/4). This industry standard was developed to ensure portability, 
  48. interoperability, and consistency of user environments across all compliant 
  49. systems. The XPG/4 internationalization programming model has the following
  50. features:
  51.  
  52. o Applications can be written in a language-independent way, so that a single
  53.   version of the application can support users throughout the world. This
  54.   eliminates the need for multiple language-specific versions and can
  55.   dramatically reduce development, manufacturing and distribution costs.
  56.  
  57. o Applications can "automatically" interact with international users in their 
  58.   own language, correct cultural conventions, and national data encoding.
  59.  
  60. o The selection of localization features is user-definable through language
  61.   environment variables. This announcement mechanism permits the dynamic
  62.   loading of localization objects (locales), which give applications the
  63.   correct cultural flavor.
  64.  
  65. o The language is determined by the user, not the system or application. The
  66.   same application can be launched in different languages on the same
  67.   workstation, by simply changing the language environment settings.
  68.  
  69. o New languages, countries and code pages can easily be supported by simply
  70.   providing new locale objects, without requiring any change to applications.
  71.  
  72. o Locale objects contain information to support the following types of
  73.   culturally correct processing:
  74.   - date and time formatting
  75.   - numerical formatting
  76.   - monetary formatting
  77.   - text sorting
  78.   - character classification
  79.   - character case conversion
  80.   - processing of single or multi-byte character text
  81.   - text processing using wide characters
  82.  
  83. o Utilities are provided to permit the packaging of application-specific 
  84.   translatable text in external message files. Messaging interfaces are
  85.   provided to access the correct message language at run-time, as specified 
  86.   by the locale environment variables.
  87.  
  88.  
  89. 2.  Locale model
  90. ================
  91.  
  92. The I18N library is based on a locale model, in which the world is divided up
  93. into a collection of locales. A given country may have one or more locales
  94. depending on its cultural diversity. For example, Switzerland has German, 
  95. Italian, and French locales. Locales are also not based only on language. 
  96. For example, French is used in both France and Canada. However, the numeric 
  97. formats in these two countries are different. In addition, locales also 
  98. contain a code page character map. For example, English in the US is actually 
  99. available in three different locales, which support code pages 437 (default), 
  100. 850 and 819 (ISO8859-1).
  101.  
  102. In general, a locale name has the following format:
  103.  
  104.      xx_YY.ZZZZ
  105.  
  106. where xx is usually a language abbreviation, YY is a country abbreviation,
  107. and .ZZZZ is an optional 3 or 4 digit codepage number.  So, to set the locale
  108. to US English, one could type:
  109.  
  110.      set LANG=en_US.437
  111.  
  112. There are several other ways in which users can name locales (for environment
  113. variables). The codepage number is optional. If it is left off, the currently
  114. active codepage number will be appended to the locale name.  So, for example, 
  115. one could type:
  116.  
  117.      set LANG=en_US
  118.  
  119. and ".437" would be appened to the locale name on a typical US installation of 
  120. OS/2. The underscore is also optional.  So another way of specifying the same 
  121. locale is:
  122.  
  123.      set LANG=enus
  124.  
  125. In addition, case is ignored in locale names.  So "EN_US" is yet another way 
  126. of specifying the same locale.
  127.  
  128. The I18N package also provides the ability to define locale aliases.
  129. These are just simple names a user can assign to locale names to make them 
  130. easier to remember. The locale alias table is stored in "\i18n\locale\ALIASES". 
  131. The table consists of rows of aliases.  Each row contains the alias and the
  132. true locale name, separated by a space.  The alias file is an ASCII text file,
  133. and can be edited.  In addition, a program (LOCALIAS) has been provided to
  134. make adding, deleting, and modifying aliases easier.
  135.  
  136. Several locale aliases have been provided with this package.  So, one could
  137. enter:
  138.  
  139.      set LANG=english
  140.  
  141. and this would set the locale to: "en_US.437".  Locale aliases can be up to
  142. 25 characters long, with no spaces included.
  143.  
  144. The actual locales are stored in dynamic link libraries (in \i18n\locale).  The
  145. names of the .DLL files are similar to the full names shown above, but with
  146. the underscore and the period removed.  So the default US English locale file
  147. is actually stored as: ENUS437.DLL
  148.  
  149. The reason for this remapping of names is that OS/2 supports the FAT file
  150. system, which enforces file name lengths of 8.3  Thus, the locale names are
  151. composed of XXYYZZZZ.DLL, which conforms to the rules.  The mapping of locale
  152. names (or aliases) to the locale file names is automatic - you do not need to
  153. worry about it.
  154.  
  155. The following is a list of locales provided in this release:
  156.  
  157.      Locale    Locale description
  158.      Name
  159.      -----------------------------------------------------------------------
  160.      C         This is the default locale if no environment variables are set.
  161.  
  162.      ARAA864   Arabic in Arabic Area (Primary)
  163.      ARAA1046  Arabic in Arabic Area (Alternate)
  164.      BGBG915   Bulgarian in Bulgaria
  165.      CSCZ852   Czech in Czech Republic
  166.      DADK850   Danish in Denmark
  167.      DECH850   German in Switzerland
  168.      DEDE850   German in Germany (and Austria)
  169.      ELGR869   Greek in Greece
  170.      ENGB850   English in the U.K.
  171.      ENUS437   English in the U.S. (Primary)
  172.      ENUS850   English in the U.S. (Alternate)
  173.      ENUS819   English in the U.S. (ISO8859-1)
  174.      ESES850   Spanish in Spain
  175.      FIFI850   Finnish in Finland
  176.      FRBE850   French in Belgium
  177.      FRCA850   French in Canada
  178.      FRCH850   French in Switzerland
  179.      FRFR850   French in France
  180.      HRHR852   Croatian in Croatia
  181.      HUHU852   Hungarian in Hungary
  182.      ISIS850   Icelandic in Iceland
  183.      ITIT850   Italian in Italy
  184.      IWIL862   Hebrew in Israel (Primary)
  185.      IWIL856   Hebrew in Israel (Alternate)
  186.      JAJP932   Japanese in Japan
  187.      KOKR949   Korean in Korea
  188.      MKMK915   Macedonian in Macedonia
  189.      NLBE850   Flemish in Belgium
  190.      NLNL850   Dutch in Netherlands
  191.      NONO850   Norwegian in Norway
  192.      PLPL852   Polish in Poland
  193.      PTBR850   Portuguese in Brazil
  194.      PTPT850   Portuguese in Portugal
  195.      RORO852   Romanian in Romania
  196.      RURU866   Russian in Russia
  197.      SHSP852   Latin Serbian in Serbia
  198.      SLSI852   Slovenian in Slovenia
  199.      SKSK852   Slovak in Slovakia
  200.      SRSP915   Cyrillic Serbian in Serbia
  201.      SVSE850   Swedish in Sweden
  202.      THTH874   Thai in Thailand
  203.      TRTR857   Turkish in Turkey
  204.      ZHCN1381  Simplified Chinese in China
  205.      ZHTW950   Traditional Chinese in Taiwan (Primary)
  206.      ZHTW948   Traditional Chinese in Taiwan (Alternate)
  207.  
  208. Additional locales are being added. If you are using this package, and would 
  209. like information about a specific locale, contact us for further information.
  210.  
  211. In addition to using the 8.3 names (without the underscore or period) for
  212. locale files, I18N also uses those names for message catalog directories.
  213. So, suppose you had the following NLSPATH variable, and LANG variable:
  214.  
  215.      set NLSPATH=E:\I18N\MESSAGES\%L\%N
  216.      set LANG=en_US
  217.  
  218. Further suppose you execute the following catalog open command in your program:
  219.  
  220.      cat_handle = catopen("my.cat", 0);
  221.  
  222. I18N would then attempt to find the following file:
  223.  
  224.      E:\I18N\MESSAGES\ENUS437\MY.CAT
  225.  
  226. That is because the locale (english) is remapped to: ENUS437 (without the .DLL).
  227. Look at the \I18N\MESSAGES directory in this package to see some of the locale
  228. message directories provided.
  229.  
  230. 3.  About this package
  231. ======================
  232.  
  233. This package is an OS/2 Developers Toolkit for writing programs using the
  234. XPG4 internationalization programming model. It has been made available to
  235. gauge OS/2 developer interest in this model.
  236.  
  237. Included are the include files, libraries, .dll files, and programs necessary
  238. for developing internationalized programs using the XPG4 model.  We have also 
  239. included a large number of sample programs to demonstrate the proper use of 
  240. the I18N APIs.  Also, there is an on-line technical reference (in OS/2 VIEW
  241. format) to describe the APIs provided.
  242.  
  243. NOTE:  In this release of the I18N package, the technical reference is not
  244.        completely up to date.  If any discrepancies are found between the
  245.        descriptions found in this file and the technical reference, this
  246.        file should be considered definitive.
  247.  
  248.  
  249. 4.  Common abbreviations
  250. ========================
  251.  
  252. The following are common abbreviations in the NLS programming world:
  253.  
  254.      Abbreviation       Meaning
  255.      -------------------------------------------------------------------------
  256.      NLS                National Language Support
  257.      ICONV              Input Conversion
  258.      I18N               Internationalization
  259.      I14Y               Interoperability
  260.      L10N               Localization
  261.      Wide character     A character with a fixed, multiple byte representation.
  262.                         In our implementation, wide characters are all 2 bytes
  263.                         long.
  264.      wchar_t            A new data type for wide characters.
  265.  
  266.  
  267. 5.  Files in this directory
  268. ===========================
  269.  
  270. The following files can be found in this directory:
  271.  
  272. File          Purpose
  273. ------------------------------------------------------------------------------
  274. read.me       This file.
  275. bin           .EXE and .CMD files for building message catalogs and setting
  276.                environment variables.
  277. dll           Required .DLL files.
  278. include       Required header files.
  279. locale        .DLL files which implement the locales.
  280. lib           Required .LIB files.
  281. ref           Contains technical reference (in OS/2 VIEW format).
  282. doc           Documentation for commands in the bin directory.
  283. sample        Sample programs to demonstrate the I18N APIs.
  284.  
  285.  
  286. 6.  Installing the package
  287. ==========================
  288.  
  289.      1. The package should already be unzipped in a directory \I18N off of
  290.         the root of an HPFS formatted drive.
  291.  
  292.         NOTE: In the instructions below, no drive letters are specified for
  293.               environment variables.  You should substitute the proper letter
  294.               for your installation.
  295.  
  296.      2. Add the \I18N\DLL path to your existing LIBPATH statement in your
  297.         CONFIG.SYS file.  Before you use I18N make sure to reboot your system
  298.         so the change in LIBPATH takes effect.
  299.  
  300.      3. Make sure that the IBM C SET/2 Compiler and OS/2 Toolkit are installed
  301.         on your system, as they are prerequisites to compiling and linking the
  302.         many examples in the \I18N\SAMPLES directory.
  303.  
  304.      4. Add the following to your CONFIG.SYS file:
  305.  
  306.           SET LANG=<locale>
  307.  
  308.         where <locale> is a locale you prefer, such as en_US.
  309.  
  310.      NOTE: Steps 5-8 below are OPTIONAL.  A command file:
  311.            \I18N\BIN\NEW_VARS.CMD is provided which sets the variables
  312.            described below.  If you do not wish to permanently affect your
  313.            environment, you may run the command file as needed.
  314.  
  315.      5. Add the \I18N\BIN path to your existing PATH statement in your
  316.         CONFIG.SYS file.
  317.  
  318.      6. Add the \I18N\INCLUDE path to your existing INCLUDE statement in your
  319.         CONFIG.SYS file.
  320.  
  321.      7. Add the \I18N\LIB path to your existing LIB statement in your
  322.         CONFIG.SYS file.
  323.  
  324.      8. Add the following to your CONFIG.SYS file:
  325.  
  326.           SET LOCPATH=\I18N\LOCALE
  327.           SET NLSPATH=\I18N\MESSAGES\%L\%N
  328.  
  329.  
  330. 7.  Environment variables
  331. =========================
  332.  
  333. The following environment variables are used for internationalization to
  334. determine the behavior of the system.  The variables are inherited as defaults
  335. by the application at boot time from CONFIG.SYS or set directly via the SET
  336. command.
  337.  
  338.      LOCPATH     specifies the search path(s) for the localized .dll's.
  339.                  different paths are separated by semicolons.
  340.  
  341.      LANG="xxx"  where "xxx" is the file name of the locale .dll, e.g. the
  342.                  value en_US is American English. Values are provided in
  343.                  the "Locale model" section above.
  344.  
  345.      NLSPATH     specifies the search path for locating the message catalog
  346.                  files.  The environment variable is used by the Message
  347.                  facility component of the NLS subsystem.
  348.  
  349. Locale values (for the setlocale call - see next section) can also be set by
  350. the LC_* environment variables:
  351.  
  352.      LC_ALL      overrides the value of other LC_* environment variables.
  353.  
  354.      LC_COLLATE  determines the character-collation or string-collation
  355.                  rules governing the behavior of ranges, equivalence
  356.                  classes and multicharacter collating elements.
  357.  
  358.      LC_CTYPE    determines character handling rules governing the
  359.                  interpretation of sequences of bytes of text data
  360.                  characters (single-byte or multi-byte characters),
  361.                  the classification of characters (for example, alpha,
  362.                  digit and so on) and the behavior of character classes.
  363.  
  364.      LC_MESSAGES determines the locale (language) for messages and menus.
  365.                  It also determines the rules for affirmative and negative
  366.                  responses according to locale, although such responses are
  367.                  not recommended by NLS Guidelines or CUA.
  368.  
  369.      LC_MONETARY determines the rules governing monetary formatting.
  370.  
  371.      LC_NUMERIC  determines the rules governing numeric formatting
  372.                  other than monetary.
  373.  
  374.      LC_TIME     determines the rules governing date and time formatting.
  375.  
  376.      LANG        default setting of Locale overidable by the preceding
  377.                  environment variables.  Similar to LC_ALL above, only LC_ALL
  378.                  cannot be overriden by the LC_* variables, whereas LANG
  379.                  can.
  380.  
  381. The application should use only the LANG, LOCPATH and NLSPATH variables.
  382. A user can override them with the locale environment variables.  When a call to
  383. setlocale is made, the settings are queried for priority level as follows:
  384.  
  385.      If the LC_ALL environment variable is set, the value of the LC_ALL
  386.      variable is used for all categories.
  387.  
  388.      If the LC_ALL environment variable is not set, the values specified
  389.      for medium-priority environment variables (LC_COLLATE, LC_CTYPE,
  390.      LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) are used.
  391.  
  392.      If individual LC_* environment variables are not set, the value of
  393.      the LANG environment variable specifies the locale for all remaining
  394.      categories.
  395.  
  396.      If the LANG environment variable is not set, the locale for all
  397.      remaining categories defaults to the C locale.
  398.  
  399.  
  400. 8.  Setting the LOCALE
  401. ======================
  402.  
  403. By design, an application program initially starts up in the default C locale.
  404. Most internationalized programs, however, must then change the locale for the
  405. program to the locale set by the user.  This is done with a call to setlocale.
  406. Upon calling the setlocale routine, the program's locale is determined by
  407. either the LANG, and LC_* environment variables, or directly by the 2nd
  408. argument to setlocale.
  409.  
  410. Usually, the user will set one or more of the LC_* environment variables to
  411. determine the locale of the program.  If all facets of a program (date/time/
  412. monetary etc) are to be set to the same locale (which is common), the
  413. LANG or LC_ALL environment variable should be set to that locale.  If one
  414. or more features are to be set to a different locale, their environment
  415. variable must also be set.
  416.  
  417. The following is the typical usage of the setlocale call:
  418.  
  419.      #include <wchar.h>
  420.      #include <locale.h>
  421.  
  422.      main() {
  423.  
  424.      /* The LC_ALL and LANG environment variables set the program's locale */
  425.  
  426.        setlocale(LC_ALL, "");
  427.      }
  428.  
  429. If, in the example above, the LC_ALL variable was set to en_US, and the
  430. LC_MONETARY variable was set to fr_FR, all facets of the program would be
  431. set to en_US, except the monetary formatting, which would be set to fr_FR.
  432.  
  433. Application programmers can also hardcode a locale for a program by setting
  434. the second argument of setlocale to a locale value:
  435.  
  436.     setlocale(LC_NUMERIC, "it_IT");
  437.  
  438. This is generally *NOT* recommended.
  439.  
  440. Setlocale can also be used to query what locale is currently active for a given LC_* value, by
  441. providing a NULL 2nd argument.  For example:
  442.  
  443.      ret_string = setlocale(LC_MESSAGES, NULL);
  444.  
  445. will return the setting of the messages locale for the program.
  446.  
  447.  
  448. 9.  Linking with the I18N package
  449. =================================
  450.  
  451. The I18N library comes packaged in two parts:
  452.  
  453.   1) An import library (setloci.lib), which is linked with your applications.
  454.   2) A dynamic link library (setloc.dll), which is placed in the runtime
  455.       machine's LIBPATH.
  456.  
  457. This implementation requires that case-sensitivity (the /NOI switch in
  458. both CSet/2 and CSet++) be turned on whenever the setloci import library is
  459. linked with an application.  This allows the lower-case APIs in the library
  460. to be properly found at application load-time.
  461.  
  462. All of the sample programs illustrate how to use this switch when linking your
  463. program.  See the ".mak" file in any of the sample directories for more
  464. information.
  465.  
  466. *NOTE* The /NOI switch is *required*.  If it is not used, your application
  467. will not function correctly.
  468.  
  469.  
  470. 10. About wide characters
  471. =========================
  472.  
  473. The XPG4 programming model defines a new character datatype wchar_t for 16-bit
  474. character code elements.  The wchar_t datatype extends the range of the
  475. standard char datatype to 16-bit characters. In general programmers only need
  476. to use this datatype when direct character manipulation is needed on multi-byte
  477. character data.
  478.  
  479. Special functions are provided to convert between multi-byte and wchar strings
  480. (see mbstowcs, wcstombs, mbtowc, and wctomb functions below), and to copy,
  481. compare, or search wchar strings (see wcs* functions below).
  482.  
  483. The XPG4 programming model doesn't dictate the code page of the wchar_t
  484. variables.  Wide characters can be used in any code page.
  485.  
  486. As a programmer writing internationalized programs, you can not assume 
  487. anything about what value a wchar_t variable may contain, because it can vary 
  488. from locale to locale, and from vendor to vendor.
  489.  
  490. Instead, you must use the I18N functions to manipulate and test wchar_t
  491. variables to insure proper operation of your program in an international
  492. environment.  These functions are described, in detail, below.  Typically,
  493. wide character functions either start with the prefix "wcs" (as in wcscpy -
  494. wide character copy), or have the letter "w" inserted in the function
  495. name (as in "iswalpha" - is the wide character an alphabetic character).
  496.  
  497. IMPORTANT:  Wide characters and strings *can* be represented in your program
  498.             as literal values.  Place the capital letter 'L' in front of your
  499.             literal characters and strings.
  500.  
  501.      Ex: wcscpy(a_wide_var, L"A wide char string!");
  502.          if (a_wide_char_var == L'\0') ...
  503.  
  504.  
  505. 11. Using the char datatype
  506. ===========================
  507.  
  508. The char datatype is still used in most cases but now it may contain multi-byte
  509. characters as defined in the specific locale. A multi-byte character is
  510. composed of one or more bytes, with no imbedded null bytes. The standard C str*
  511. functions are still used to manipulate these kinds of strings, with the
  512. exception of:
  513.  
  514.      strcmp        doesn't handle < or > comparisons culturally. However,
  515.                    strcmp still works for equal/not equal tests.  To determine
  516.                    greater than/less than on strings, use the strcoll and
  517.                    strxfrm functions.
  518.  
  519.      strchr        for character searching its not multi-byte aware
  520.      strrchr       and so may find a single byte character amid a
  521.                    multi-byte sequence.
  522.  
  523.      strncpy       is not multi-byte aware and may only copy only part
  524.                    of a multi-byte character.
  525.  
  526.      strstr        is not multi-byte aware for single character strings but
  527.                    will work with strings >1 character as the search key.
  528.  
  529.  
  530. 12. Command-line programs provided
  531. ==================================
  532.  
  533.      Program      Purpose
  534.      -------------------------------------------------------------------------
  535.      gencat       Constructs message catalog files.
  536.      mkcatdef     Constructs message #define .h files to be used in an
  537.                   application program to reference catalog file entries.
  538.      runcat       A command file which builds both message catalogs, and
  539.                   the include files for those catalogs (via mkcatdef and
  540.                   gencat).
  541.      cvtmsg       Converts an OS/2 mkmsgf input file into an XPG4 gencat
  542.                   input file.
  543.      locale       Displays the currently active locale categories.
  544.  
  545. See the "cat" sample directory for details.
  546.  
  547.      localias     Allows user to add, delete, and modify entries in the locale
  548.                    alias table.
  549.  
  550. 13. I18N API prototype summary
  551. ==============================
  552.  
  553.       ***************************************************
  554.       ** For more technical details on these functions **
  555.       ** use VIEW on the \I18N\REF\I18N.INF file.      **
  556.       ***************************************************
  557.  
  558. 1. Runtime Locale load and data access functions:
  559.  
  560.      char *setlocale(int, const char *);
  561.  
  562. 2. Character Attribute testing (Uses locale-based methods):
  563.  
  564.      int isalnum(int c);
  565.      int isalpha(int c);
  566.      int iscntrl(int c);
  567.      int isdigit(int c);
  568.      int isgraph(int c);
  569.      int islower(int c);
  570.      int isprint(int c);
  571.      int ispunct(int c);
  572.      int isspace(int c);
  573.      int isupper(int c);
  574.      int isxdigit(int c);
  575.  
  576.      int toupper(int c);
  577.      int tolower(int c);
  578.  
  579.      int iswalnum(wint_t wc);
  580.      int iswalpha(wint_t wc);
  581.      int iswcntrl(wint_t wc);
  582.      int iswdigit(wint_t wc);
  583.      int iswgraph(wint_t wc);
  584.      int iswlower(wint_t wc);
  585.      int iswprint(wint_t wc);
  586.      int iswpunct(wint_t wc);
  587.      int iswspace(wint_t wc);
  588.      int iswupper(wint_t wc);
  589.      int iswxdigit(wint_t wc);
  590.  
  591.      int iswctype(wint_t wc, wctype_t mask);
  592.  
  593.      wint_t towupper(wint_t wc);
  594.      wint_t towlower(wint_t wc);
  595.  
  596.      wctype_t wctype(const char *charclass);
  597.  
  598. 3. Date and Time Formatting:
  599.  
  600.      size_t strftime(char *s, size_t maxsize, const char *format,
  601.                       const struct tm *tm);
  602.  
  603.      size_t strfmon(char *s, size_t maxsize, const char *format, ...);
  604.  
  605.      char  *strptime(const char *buf, const char *fmt, struct tm *tm);
  606.  
  607.      size_t wcsftime(wchar_t *wcs, size_t maxsize, const char *format,
  608.                      const struct tm *tm);
  609.  
  610.      char *nl_langinfo(nl_item item);
  611.      struct lconv *localeconv(void);
  612.  
  613. 4. File IO functions which use mbtowc transformations:
  614.  
  615.      wint_t   fgetwc(FILE *stream);
  616.      wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);
  617.  
  618.      wint_t   fputwc(wint_t wc, FILE *stream);
  619.      int      fputws(const wchar_t *ws, FILE *stream);
  620.  
  621.      wint_t   getwc (FILE *stream);
  622.      wint_t   putwc(wint_t wc, FILE *stream);
  623.      wint_t   ungetwc(wint_t wc, FILE *stream);
  624.  
  625.      wint_t   getwchar(void);
  626.      wint_t   putwchar(wint_t wc);
  627.  
  628. 5. The basic conversion methods between multibyte <--> wchar_t:
  629.  
  630.      int    mblen(const char *s, size_t n);
  631.      size_t mbstowcs(wchar_t *ws, const char *s, size_t n);
  632.      int    mbtowc(wchar_t *wc, const char *s, size_t n);
  633.      size_t wcstombs(char *s, const wchar_t *ws, size_t n);
  634.      int    wcswidth(const wchar_t *ws, size_t n);
  635.      int    wctomb(char *s, wchar_t wchar);
  636.      int    wcwidth(wint_t wc);
  637.  
  638. 6. Basic String manipulation API for wchar_t data type:
  639.  
  640.      size_t   wcscspn (const wchar_t *ws1, const wchar_t *ws2);
  641.      size_t   wcslen  (const wchar_t *ws);
  642.      wchar_t *wcscat  (wchar_t       *ws1, const wchar_t *ws2);
  643.      wchar_t *wcscpy  (wchar_t       *ws1, const wchar_t *ws2);
  644.      int      wcscmp  (const wchar_t *ws1, const wchar_t *ws2);
  645.      int      wcsncmp (const wchar_t *ws1, const wchar_t *ws2, size_t n);
  646.      wchar_t *wcspbrk (const wchar_t *ws1, const wchar_t *ws2);
  647.      wchar_t *wcsncpy (wchar_t       *ws1, const wchar_t *ws2, size_t n);
  648.      size_t   wcsspn  (const wchar_t *ws1, const wchar_t *ws2);
  649.      wchar_t *wcschr  (wchar_t       *ws1, wint_t         wc);
  650.      wchar_t *wcsncat (wchar_t       *ws1, const wchar_t *ws2, size_t n);
  651.      wchar_t *wcsrchr (wchar_t       *ws1, wint_t         wc);
  652.      wchar_t *wcstok  (wchar_t       *ws1, const wchar_t *ws2);
  653.      wchar_t *wcswcs  (const wchar_t *ws1, const wchar_t *ws2);
  654.  
  655. 7. Wide character print/scan formatting:
  656.  
  657.      fscanf/scanf/sscanf with %S, %C decoding, and parameter
  658.                             reordering via the (%n$x) format
  659.  
  660.      fprintf/printf/sprintf with %S, %C encoding, and parameter
  661.                             reordering via the (%n$x) format
  662.  
  663.      vfprintf/vprintf/vsprintf with %S, %C encoding, and parameter
  664.                             reordering via the (%n$x) format
  665.  
  666. 8. Collations:
  667.  
  668.      int strcoll(const char *s1, const char *s2);
  669.      size_t strxfrm(char *s1, const char *s2, size_t n);
  670.  
  671.      int wcscoll(const wchar_t *ws1, const wchar_t *ws2);
  672.      size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);
  673.  
  674. 9. Conversions:
  675.  
  676.      long wcstol(const wchar_t *nptr,
  677.                        wchar_t **endptr, int base);
  678.      unsigned long wcstoul(const wchar_t *nptr,
  679.                                  wchar_t **endptr, int base);
  680.  
  681.      double wcstod(const wchar_t *nptr, wchar_t **endptr);
  682.      double strtod(const char *nptr, char **endptr);
  683.  
  684.  
  685. 10. Messages:
  686.  
  687.      nl_catd   catopen(const char *name, int oflag);
  688.      char     *catgets(nl_catd catd, int setid, int msgid, const char *s);
  689.      int       catclose(nl_catd catd);
  690.  
  691. 11. Regular expression functions:
  692.  
  693.      int regcomp(regex_t *preg, const char *pattern, int cflags);
  694.      int regexec(const regex_t *preg, const char *string, 
  695.         size_t nmatch, regmatch_t pmatch[], int eflags);
  696.      size_t regerror(int errcode, const regex_t *preg, 
  697.         char *errbuf, size_t errbuf_size);
  698.      void regfree(regex_t *preg);
  699.  
  700. 12. Non-XPG4 case insenstive compare and case conversion functions:
  701.  
  702.      char *strlwr(char *s);
  703.      char *strupr(char *s);
  704.      int strcmpi(const char *s1, const char *s2);
  705.      int stricmp(const char *s1, const char *s2);
  706.      int strnicmp(const char *s1, const char *s2, size_t n);
  707.      int memicmp(void *s1, void *s2, unsigned int n);
  708.  
  709. 13. Helper functions:
  710.  
  711.      double get_i18n_version(void);
  712.      int find_locale_alias(char *in_str, char *out_str);
  713.      int add_locale_alias(char *the_alias, char *the_name);
  714.      int remove_locale_alias(char *in_str);
  715.      int map_string_to_locale(char *in_str, char *out_str);
  716.      int get_alias_table_path(char *out_str);
  717.  
  718.  
  719. 14. What is new in this version of the package
  720. ==============================================
  721.  
  722.  
  723. Version 1.02 (8/29/95)
  724. ----------------------
  725.  
  726. - iconv conversion support based on ISO10646 UCS-2:
  727.     i18n\lib\iconv.lib - static link library for iconv APIs
  728.     i18n\include\iconv.h - iconv include file
  729.     i18n\locale\iconv\ucstbl.dll - DLL for all table-driven conversions
  730.     i18n\locale\iconv\utf-8.dll - DLL for UTF-8 conversions
  731.     i18n\locale\iconv\iconv.lst - alias file for UCS-2 conversions
  732.     i18n\locale\uconvtab\* - binary form of mapping tables
  733.     i18n\locale\uconvtab\uconv.lst - alias file for UCS-2 mapping tables
  734.  
  735.   *Unicode is a trademark of Unicode, Inc.
  736.  
  737. - Minor bug fixes in:
  738.   strfmon()
  739.   regcomp()
  740.   regexec()
  741.   printf() family of APIs
  742.   scanf() family of APIs
  743.  
  744. - Cleaned up version of wchar.h
  745.  
  746.  
  747. Version 1.00 (4/18/95)
  748. ----------------------
  749.  
  750. - The setlocale() function will now work with the older locale formats.
  751. - Bug fixes in fscanf().
  752. - Install utility bug fixes.
  753.  
  754. - Appending a major version number ( only major bug fixes will cause this
  755.   to increment ) to setloc.dll.
  756.  
  757.            was setloc.dll   -->  now setloc1.dll
  758.  
  759.  
  760. - Added defines to version.h header file for version number and 
  761.   module name identification to be used by install programs.
  762.  
  763.            #define I18N_VERSION_NUM    1.00
  764.            #define MODULE_NAME      "SETLOC1"
  765.  
  766.  
  767. Version 0.40 (3/15/95)
  768. ----------------------
  769.  
  770. - Default locale loaded during setloc.dll initialization. This is determined
  771.   by mapping the current country code and code page to the set of installed
  772.   locales. If no match is found, the "C" locale is still used. 
  773. - After the default locale is established a setlocale(LC_ALL, "") call is made
  774.   during setloc.dll initialization. This call uses the XPG4 I18N environment
  775.   variables to override the default locale setting.
  776. - If setlocale is called with the null string ("") argument, but the 
  777.   XPG4 I18N environment variables are not set, the locale is left unchanged.
  778.  
  779. Version 0.35 (3/7/95)
  780. ----------------------
  781. Changes:
  782. - Regular expression functions, header and sample program added.
  783. - Case insensitive compare functions enabled for MBCS strings.
  784. - strupr and strlwr functions enabled for MBCS strings.
  785. - Bug fix in wcsxfrm.
  786. - Enhanced version of cvtmsg utility
  787.  
  788. Version 0.30 (1/30/95)
  789. -----------------------
  790.  
  791. Changes:
  792. - Fully functional utility for installing and customizing 
  793.   the I18N run-time environment. This is intended for 
  794.   products which include the I18N support and must install 
  795.   it. The program with source code and documentation is in
  796.   the sample\install directory.
  797. - cvtmsg utility for converting OS/2 message files to XPG4 message files.
  798. - Completely recompiled with IBM C/C++ Tools Version 2.0
  799. - Miscellaneous bug fixes
  800. - vprintf, vsprintf and vfprintf supported
  801. - New printf and vprintf sample programs
  802.  
  803.  
  804. 15. What is not included in this package
  805. ========================================
  806.  
  807. XPG4 specifies several commands such as localedef and iconv which 
  808. are not a part of this package. In addition, we have not provided any
  809. code page converters for the iconv api calls.
  810.  
  811. This means that while you can't create custom locales or create custom code
  812. page converters, you can use the I18N API calls to try out the XPG4 
  813. programming model.  We hope to include these missing functions in a future 
  814. release.
  815.  
  816.  
  817. 16. Recommended reading
  818. =======================
  819.  
  820. The Library of NLS recommends the following books:
  821.  
  822.      GG24-3850   Intl Tech Supt Center AIX 3.2 Natl Lang Support (IBM publ)
  823.      SC23-2431   Internationalization of AIX Software: A Programmer's Guide
  824.      XOPEN       X/Open CAE Specification, Issue 4 (X/Open Company Ltd)
  825.  
  826.  
  827.   ============================================================================
  828.       End of Read.Me File                         
  829.   ============================================================================
  830.