
===============================================================================
                  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.  Files in this directory
3.  How to run the sample program
4.  How to compile the sample program
5.  Notes


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

This sample program demonstrates the use of the I18N messaging subsystem.  The
message system is very simple.  It is comprised of two parts:

     1. A message catalog source file, which is built into a message catalog
         (and include file of message tags).

     2. The message APIs which an application program uses to read the messages
        from the catalog.

Messages need to reside in catalogs so that different locales can read the
messages which are translated into the language of that locale.  This allows
a single version of the executable program to be understood in many different
locales.

Separating message catalogs by locale is achieved by use of the NLSPATH
variable.  This environment variable lists the directories in which the
message files can be found.  There are two very important variables which are
used in the NLSPATH:

     %L         When a catopen call checks the NLSPATH, it substitutes the
                value of LANG for the %L identifier.
     %N         This is the name of the message catalog, which is supplied
                by the catopen call.

Using these variables, an NLSPATH might look like:

     NLSPATH = \I18N\MESSAGES\%L\%N;.\%N

This would mean that catopen calls would first look for the message catalog in
the \I18N\MESSAGES\<locale> directory, where <locale> is the current locale,
and then in the current directory.  In this manner, different locale versions
of the message file can be stored in different subdirectories and used at
the proper time.

Other variables which may be included in the NLSPATH are:

     %l         Place holder for the language of the current locale (could be
                 used for a message directory for all locales which share
                 the same language.
     %t         Place holder for the territory of the current locale (such as
                 "US" from the locale "En_US").
     %c         The codeset of the current locale (for example, "IBM-437" for
                 "En_US.IBM-437" would be a message directory for all codeset
                 437 locales).

2.  Files in this directory
===========================

File            Purpose
------------------------------------------------------------------------------
mycat.c         Source code for reading messages from catalogs.
mycat.def       Definition file needed for compiling the program.
mycat.mak       Make file used to compile the sample.
mycat.exe       Compiled version of the mycat sample.

test.msg        Source file for the message catalog.
test.cat        Compiled message catalog.
test_msg.h      Include file of lables to reference the catalog.

build.cmd       A command file which will compile and link the sample program.
read.me         This file.


3.  How to run the sample program
=================================

This sample program shows the different ways you can use the Messaging APIs
in your program.  The following steps show how the program can be run.

     1) Run the \i18n\bin\new_vars command file (or have the environment
        variables already set).

     2) Set the value of LC_MESSAGES to: En_US (US English).

          Ex:   set LC_MESSAGES=En_US

     3) Change the NLSPATH variable to the current directory:

          Ex:   set NLSPATH=.\%N

     4) Execute the mycat.exe program.

          Ex:   mycat

     5) The output from the program should be:

          Name of messaging locale is: ENUS437

          String: This is a message from the message catalog

          String: No message read.

          String: On: 3/29/94 at: 5:04PM the file: myfile.sys was printed on
                  printer: PS.

          String: No catalog open.

     6) Move the catalog to \I18N\MESSAGES

          Ex:   move *.cat \i18n\messages

     7) Run mycat again.  The program should fail to open the message catalog.

     8) Change the NLSPATH to: \I18N\MESSAGES\%N

     9) Run the program, and see that it works.

    10) Move the catalog to the engligh in USA subdirectory.

          Ex:   cd \i18n\messages
                move *.cat enus437
                cd \i18n\samples\cat

    11) Change the NLSPATH to use the %L:

          Ex:   set NLSPATH=\i18n\messages\%L\%N

    12) Run mycat, and see that it works.

    13) Move the message catalog to the frfr850 directory:

          Ex:   move \i18n\messages\enus437\test.cat \i18n\messages\frfr850

    14) Run mycat, and notice that it does not find the catalog.

    15) Experiment with different NLSPATH variables and moving the catalog
         to different directories.


4.  How to compile the sample program
=====================================

NOTE: The sample program is already compiled for you.  If you want to see the
 behavior of the program, you can just run it.  The following instructions
 are needed only if you want to modify the program and recompile it.

To compile the sample application:

     1) Make sure that the CSET/2 compiler and OS/2 toolkit are installed
        correctly on your system.

     2) cd to the directory which contains the mycat source files.

     3) Type "build" at the command prompt.

If you wish to rebuild the message catalog:

     1) Make sure that the \I18N\BIN directory is on your path.

     2) cd to the directory which contains the mycat source files.

     3) Type "runcat" at the command prompt.

     4) Recompile your program (since the .h file will have changed).


5.  Notes
=========

1. The second argument to the "catopen" call determines if the LANG variable
    or the LC_MESSAGES variable is used to replace the "%L" in the NLSPATH.
    In this program we use the value "NL_CAT_LOCALE" which forces the
    LC_MESSAGES to be used.  If we used the value "0", LANG would be used.
    But remember, from how LANG works, that if you define LANG, and no other
    variables that that value will be used for LC_MESSAGES.
