
===============================================================================
                  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


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

The sample program in this directory demonstrates the use of the setlocale
function call.  setlocale is used to set the locale in which an application
is running.  This allows the program to use the culturally sensitive routines
without having to modify the source code.

There are six general groups of functions which can be set to the same or
different locales.  They are:

LC_COLLATE  - Determines how character and string collation (ordering) is
               performed for sorts and searches.
LC_CTYPE    - Determines how character handling is peformed for character and
               string functions.
LC_MONETARY - Determines how monetary formatting is performed.
LC_NUMERIC  - Determines how numeric formatting is performed.
LC_TIME     - Determines how date and time formatting is performed.
LC_MESSAGES - Used for determining the locale for message files for different
               languages.

The group LC_ALL sets the locale settings for all of the locale groups.
Typically, programmers will want all functions of their program to operate
in the same locale, but XPG4 does allow the groups to be set independently.

The setlocale function has the following prototype:

    char *setlocale(int, const char *);

The first argument to setlocale is the group to set.  Valid values are:

    LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME, LC_MESSAGES

The second argument is the value to set the locale group to.  Valid values are
either an empty string (ex: "") or the name of a valid locale (ex: "En_US").
The empty string tells setlocale to use the value(s) in the environment 
variable(s) of the same name. Thus, a user can change the locale for the 
program simply by changing one or more environment variables. Specifying a 
specific locale name in the second argument forces the program to run in the 
specified locale, and is NOT recommended.

The most common usage of setlocale is:

    setlocale(LC_ALL, "");

This call will set all locale groups to the value specified in the LC_ALL
(or LANG) environment variable.  If any of the other LC_* environment variables
are also set, those values will be used for their specific group.  See the
sample program for an example of this.

setlocale can also be used to query the state of the locale settings.  If the
second argument is NULL, the function will return a string which contains
the value of the locale specified in the first argument.

    Ex: char *ret_string;
        ret_string = setlocale(LC_MONETARY, NULL)

will return the value of the LC_MONETARY setting.  Specifying LC_ALL in the
first argument will return a string of all six LC_* settings.  NOTE: The
string returned from setlocale is a static string.  If you need to save the
value of the return string, copy it before any further calls to setlocale.


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

File            Purpose
------------------------------------------------------------------------------
setl.c          Source code for the setlocale sample program.
setl.def        Definition file needed for compiling the program.
setl.mak        Make file used to compile the sample.
setl.exe        Compiled version of the setlocale sample.

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 setlocale API
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 either LANG to: En_US (US English).

          Ex:   set LANG=En_US

     3) Set the value of the LC_MONETARY to: Fr_FR.IBM-850 (French in France).

          Ex:   set LC_MONETARY=Fr_FR.IBM-850

     4) Execute the setl.exe program.

          Ex:   setl

     5) The output from the program should be:

          Locale settings are: ENUS437 ENUS437 FRFR850 ENUS437 ENUS437 ENUS437
          Locale settings are: ENUS437 ENUS437 FRFR850 ENUS437 ENUS437 ENUS437
          Locale settings are: ENUS437 ENUS437 FRFR850 ITIT850 ENUS437 ENUS437
          Changed the settings back: ENUS437 ENUS437 FRFR850 ENUS437 ENUS437 ENUS437

     6) Experiment with changing the values of LANG and LC_MONETARY environment
        variable.  Also, change the values of the arguments to setlocale in
        the sample program, recompile, and view the results.


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 setl source files.

     3) Type "build" at the command prompt.
