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