home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / i18nv102.zip / SAMPLE / SETLOC / READ.ME < prev    next >
Text File  |  1995-09-19  |  6KB  |  156 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. /************************/
  22. /***     Contents     ***/
  23. /************************/
  24.  
  25. 1.  Overview
  26. 2.  Files in this directory
  27. 3.  How to run the sample program
  28. 4.  How to compile the sample program
  29.  
  30.  
  31. 1.  Overview
  32. ============
  33.  
  34. The sample program in this directory demonstrates the use of the setlocale
  35. function call.  setlocale is used to set the locale in which an application
  36. is running.  This allows the program to use the culturally sensitive routines
  37. without having to modify the source code.
  38.  
  39. There are six general groups of functions which can be set to the same or
  40. different locales.  They are:
  41.  
  42. LC_COLLATE  - Determines how character and string collation (ordering) is
  43.                performed for sorts and searches.
  44. LC_CTYPE    - Determines how character handling is peformed for character and
  45.                string functions.
  46. LC_MONETARY - Determines how monetary formatting is performed.
  47. LC_NUMERIC  - Determines how numeric formatting is performed.
  48. LC_TIME     - Determines how date and time formatting is performed.
  49. LC_MESSAGES - Used for determining the locale for message files for different
  50.                languages.
  51.  
  52. The group LC_ALL sets the locale settings for all of the locale groups.
  53. Typically, programmers will want all functions of their program to operate
  54. in the same locale, but XPG4 does allow the groups to be set independently.
  55.  
  56. The setlocale function has the following prototype:
  57.  
  58.     char *setlocale(int, const char *);
  59.  
  60. The first argument to setlocale is the group to set.  Valid values are:
  61.  
  62.     LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME, LC_MESSAGES
  63.  
  64. The second argument is the value to set the locale group to.  Valid values are
  65. either an empty string (ex: "") or the name of a valid locale (ex: "En_US").
  66. The empty string tells setlocale to use the value(s) in the environment 
  67. variable(s) of the same name. Thus, a user can change the locale for the 
  68. program simply by changing one or more environment variables. Specifying a 
  69. specific locale name in the second argument forces the program to run in the 
  70. specified locale, and is NOT recommended.
  71.  
  72. The most common usage of setlocale is:
  73.  
  74.     setlocale(LC_ALL, "");
  75.  
  76. This call will set all locale groups to the value specified in the LC_ALL
  77. (or LANG) environment variable.  If any of the other LC_* environment variables
  78. are also set, those values will be used for their specific group.  See the
  79. sample program for an example of this.
  80.  
  81. setlocale can also be used to query the state of the locale settings.  If the
  82. second argument is NULL, the function will return a string which contains
  83. the value of the locale specified in the first argument.
  84.  
  85.     Ex: char *ret_string;
  86.         ret_string = setlocale(LC_MONETARY, NULL)
  87.  
  88. will return the value of the LC_MONETARY setting.  Specifying LC_ALL in the
  89. first argument will return a string of all six LC_* settings.  NOTE: The
  90. string returned from setlocale is a static string.  If you need to save the
  91. value of the return string, copy it before any further calls to setlocale.
  92.  
  93.  
  94. 2.  Files in this directory
  95. ===========================
  96.  
  97. File            Purpose
  98. ------------------------------------------------------------------------------
  99. setl.c          Source code for the setlocale sample program.
  100. setl.def        Definition file needed for compiling the program.
  101. setl.mak        Make file used to compile the sample.
  102. setl.exe        Compiled version of the setlocale sample.
  103.  
  104. build.cmd       A command file which will compile and link the sample program.
  105. read.me         This file.
  106.  
  107.  
  108. 3.  How to run the sample program
  109. =================================
  110.  
  111. This sample program shows the different ways you can use the setlocale API
  112. in your program.  The following steps show how the program can be run.
  113.  
  114.      1) Run the \i18n\bin\new_vars command file (or have the environment
  115.         variables already set).
  116.  
  117.      2) Set the value of either LANG to: en_us (US English).
  118.  
  119.           Ex:   set LANG=en_us
  120.  
  121.      3) Set the value of the LC_MONETARY to: fr_fr (French in France).
  122.  
  123.           Ex:   set LC_MONETARY=fr_fr
  124.  
  125.      4) Execute the setl.exe program.
  126.  
  127.           Ex:   setl
  128.  
  129.      5) The output from the program should be:
  130.  
  131.           Locale settings are: ENUS437 ENUS437 FRFR850 ENUS437 ENUS437 ENUS437
  132.           Locale settings are: ENUS437 ENUS437 FRFR850 ENUS437 ENUS437 ENUS437
  133.           Locale settings are: ENUS437 ENUS437 FRFR850 ITIT850 ENUS437 ENUS437
  134.           Changed the settings back: ENUS437 ENUS437 FRFR850 ENUS437 ENUS437 ENUS437
  135.  
  136.      6) Experiment with changing the values of LANG and LC_MONETARY environment
  137.         variable.  Also, change the values of the arguments to setlocale in
  138.         the sample program, recompile, and view the results.
  139.  
  140.  
  141. 4.  How to compile the sample program
  142. =====================================
  143.  
  144. NOTE: The sample program is already compiled for you.  If you want to see the
  145.  behavior of the program, you can just run it.  The following instructions
  146.  are needed only if you want to modify the program and recompile it.
  147.  
  148. To compile the sample application:
  149.  
  150.      1) Make sure that the CSET/2 compiler and OS/2 toolkit are installed
  151.         correctly on your system.
  152.  
  153.      2) cd to the directory which contains the setl source files.
  154.  
  155.      3) Type "build" at the command prompt.
  156.