home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / i18nv104.zip / SAMPLE / CAT / READ.ME < prev    next >
Text File  |  1996-02-13  |  7KB  |  197 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. 5.  Notes
  27.  
  28.  
  29. 1.  Overview
  30. ============
  31.  
  32. This sample program demonstrates the use of the I18N messaging subsystem.  The
  33. message system is very simple.  It is comprised of two parts:
  34.  
  35.      1. A message catalog source file, which is built into a message catalog
  36.          (and include file of message tags).
  37.  
  38.      2. The message APIs which an application program uses to read the messages
  39.         from the catalog.
  40.  
  41. Messages need to reside in catalogs so that different locales can read the
  42. messages which are translated into the language of that locale.  This allows
  43. a single version of the executable program to be understood in many different
  44. locales.
  45.  
  46. Separating message catalogs by locale is achieved by use of the NLSPATH
  47. variable.  This environment variable lists the directories in which the
  48. message files can be found.  There are two very important variables which are
  49. used in the NLSPATH:
  50.  
  51.      %L         When a catopen call checks the NLSPATH, it substitutes the
  52.                 value of LANG for the %L identifier.
  53.      %N         This is the name of the message catalog, which is supplied
  54.                 by the catopen call.
  55.  
  56. Using these variables, an NLSPATH might look like:
  57.  
  58.      NLSPATH = \I18N\MESSAGES\%L\%N;.\%N
  59.  
  60. This would mean that catopen calls would first look for the message catalog in
  61. the \I18N\MESSAGES\<locale> directory, where <locale> is the current locale,
  62. and then in the current directory.  In this manner, different locale versions
  63. of the message file can be stored in different subdirectories and used at
  64. the proper time.
  65.  
  66. Other variables which may be included in the NLSPATH are:
  67.  
  68.      %l         Place holder for the language of the current locale (could be
  69.                  used for a message directory for all locales which share
  70.                  the same language.
  71.      %t         Place holder for the territory of the current locale (such as
  72.                  "US" from the locale "En_US").
  73.      %c         The codeset of the current locale (for example, "IBM-437" for
  74.                  "En_US.IBM-437" would be a message directory for all codeset
  75.                  437 locales).
  76.  
  77. 2.  Files in this directory
  78. ===========================
  79.  
  80. File            Purpose
  81. ------------------------------------------------------------------------------
  82. mycat.c         Source code for reading messages from catalogs.
  83. mycat.def       Definition file needed for compiling the program.
  84. mycat.mak       Make file used to compile the sample.
  85. mycat.exe       Compiled version of the mycat sample.
  86.  
  87. test.msg        Source file for the message catalog.
  88. test.cat        Compiled message catalog.
  89. test_msg.h      Include file of lables to reference the catalog.
  90.  
  91. build.cmd       A command file which will compile and link the sample program.
  92. read.me         This file.
  93.  
  94.  
  95. 3.  How to run the sample program
  96. =================================
  97.  
  98. This sample program shows the different ways you can use the Messaging APIs
  99. in your program.  The following steps show how the program can be run.
  100.  
  101.      1) Run the \i18n\bin\new_vars command file (or have the environment
  102.         variables already set).
  103.  
  104.      2) Set the value of LC_MESSAGES to: En_US (US English).
  105.  
  106.           Ex:   set LC_MESSAGES=En_US
  107.  
  108.      3) Change the NLSPATH variable to the current directory:
  109.  
  110.           Ex:   set NLSPATH=.\%N
  111.  
  112.      4) Execute the mycat.exe program.
  113.  
  114.           Ex:   mycat
  115.  
  116.      5) The output from the program should be:
  117.  
  118.           Name of messaging locale is: ENUS437
  119.  
  120.           String: This is a message from the message catalog
  121.  
  122.           String: No message read.
  123.  
  124.           String: On: 3/29/94 at: 5:04PM the file: myfile.sys was printed on
  125.                   printer: PS.
  126.  
  127.           String: No catalog open.
  128.  
  129.      6) Move the catalog to \I18N\MESSAGES
  130.  
  131.           Ex:   move *.cat \i18n\messages
  132.  
  133.      7) Run mycat again.  The program should fail to open the message catalog.
  134.  
  135.      8) Change the NLSPATH to: \I18N\MESSAGES\%N
  136.  
  137.      9) Run the program, and see that it works.
  138.  
  139.     10) Move the catalog to the engligh in USA subdirectory.
  140.  
  141.           Ex:   cd \i18n\messages
  142.                 move *.cat enus437
  143.                 cd \i18n\samples\cat
  144.  
  145.     11) Change the NLSPATH to use the %L:
  146.  
  147.           Ex:   set NLSPATH=\i18n\messages\%L\%N
  148.  
  149.     12) Run mycat, and see that it works.
  150.  
  151.     13) Move the message catalog to the frfr850 directory:
  152.  
  153.           Ex:   move \i18n\messages\enus437\test.cat \i18n\messages\frfr850
  154.  
  155.     14) Run mycat, and notice that it does not find the catalog.
  156.  
  157.     15) Experiment with different NLSPATH variables and moving the catalog
  158.          to different directories.
  159.  
  160.  
  161. 4.  How to compile the sample program
  162. =====================================
  163.  
  164. NOTE: The sample program is already compiled for you.  If you want to see the
  165.  behavior of the program, you can just run it.  The following instructions
  166.  are needed only if you want to modify the program and recompile it.
  167.  
  168. To compile the sample application:
  169.  
  170.      1) Make sure that the CSET/2 compiler and OS/2 toolkit are installed
  171.         correctly on your system.
  172.  
  173.      2) cd to the directory which contains the mycat source files.
  174.  
  175.      3) Type "build" at the command prompt.
  176.  
  177. If you wish to rebuild the message catalog:
  178.  
  179.      1) Make sure that the \I18N\BIN directory is on your path.
  180.  
  181.      2) cd to the directory which contains the mycat source files.
  182.  
  183.      3) Type "runcat" at the command prompt.
  184.  
  185.      4) Recompile your program (since the .h file will have changed).
  186.  
  187.  
  188. 5.  Notes
  189. =========
  190.  
  191. 1. The second argument to the "catopen" call determines if the LANG variable
  192.     or the LC_MESSAGES variable is used to replace the "%L" in the NLSPATH.
  193.     In this program we use the value "NL_CAT_LOCALE" which forces the
  194.     LC_MESSAGES to be used.  If we used the value "0", LANG would be used.
  195.     But remember, from how LANG works, that if you define LANG, and no other
  196.     variables that that value will be used for LC_MESSAGES.
  197.