The  Language Message  File  tool is  designed  for systems  where  end
users  want  to see  messages  in their  native  language and  multiple
languages  exist.   A programming convention  is used where  a one byte
character  code  determines  the   language  the  messages  should   be
displayed in.

The  major intent  of the  tool  is to  allow the  writing of  programs
where  the  messages can  be displayed  in  the user's  native language
without changing the code of the program or the code page.

The tool supports two commands:

   CRTLNGMSGF    This  creates  the  LNGMSGF   data  area  which   will
                 contain one byte  for the language and  an alternating
                 entry  of a 20  byte qualified  message file name.   A
                 typical command to create the data area would be:

                     CRTLNGMSGF   LIB(xxxx)

                 The LNGMSGF data  area would be  created in the  named
                 library.   The  EDTCONARR TAA  command  would then  be
                 used to enter the data.  See the later discussion.

                 You  may create  as  many language  message  file data
                 areas as needed, but only one per library.

   RTVLNGMSGF    This  allows  a  retrieval of  the  LNGMSGF  data area
                 information.  A typical command would be:

                     RTVLNGMSGF   LANG(&LANG) RTNMSGF(&MSGF) +
                                    RTNMSGFL(&MSGFL)

If the  language does  not exist,  TAA9896 will  be sent  as an  escape
message.

A typical  use of  the tool would  be to access  some data from  a user
file  that contains the one  byte character language ID.   For example,
you could  use the  USRATTR  field in  a user  profile and  access  the
information using  RTVOBJD (see the  TAA Tool CHGOBJD2  for how  to set
USRATTR).   Or you could use  the last byte of the  TEXT field from the
user profile and access the information using RTVUSRPRF.

Typical coding would be:

             DCL         &MSGF *CHAR LEN(10)
             DCL         &MSGFL *CHAR LEN(10)
             DCL         &LANG *CHAR LEN(1)
                         /*                                    */
                         /*   Get &LANG info for the user      */
                         /*                                    */
             RTVLNGMSGF  LANG(&LANG) RTNMSGF(&MSGF) RTNMSGFL(&MSGFL)
             OVRMSGF     MSGF(USRMSGS) TOMSGF(&MSGFL/&MSGF)
                         /*                                    */
                         /*   Send a message                   */
                         /*                                    */
             SNDPGMMSG   MSGID(uuunnnn) MSGF(USRMSGS) MSGTYPE(*DIAG)

When the  program sends  a message  from USRMSGS,  the OVRMSGF  command
causes  the system  to attempt  to  access the  message  from the  file
specified for  TOMSGF.  If the  message ID does not  exist, the message
is then retrieved from the USRMSGS file.

The same technique may be used for the QCPFMSG file.

CRTLNGMSGF command parameters                         *CMD
-----------------------------

   LIB           The  library  where  the  LNGMSGF  data  area  will be
                 created.

RTVLNGMSGF command parameters                         *CMD
-----------------------------

   LANG          The one character language identifier.

   RTNMSGF       The return  message file.   This must  be declared  as
                 *CHAR LEN(10).

   RTNMSGFL      The  return  message  file  library.    This  must  be
                 declared as *CHAR LEN(10).

   LNGMSGFLIB    The  library containing the LNGMSGF  data area.  *LIBL
                 is the default.  *CURLIB may also be specified.

Entering data into the LNGMSGF data area
----------------------------------------

The EDTCONARR TAA command  is used to enter  the data into the  LNGMSGF
data area that you  created.  When the prompt appears, there  will be a
column for  the Language ID.   This appears to be  a 20 character input
field, but only a single byte may be entered.

The alternating  entry  is  a  20 character  input  field  that  should
contain the  qualified  object name  of the  message file  to be  used.
The message file  should be in the first 10  bytes and the message file
library in the last 10.

After you have entered the data, the data area might appear as:

  Sequence   Language     Len =  1       Qlfd MSGF    Len = 20
    010      E___________________        ENGLISH___QGPL______
    020      G___________________        GERMAN____QGPL______
    030      I___________________        ITALIAN___QGPL______
     .
     .

The  user  has created  message files  in  QGPL for  various languages.
Each message file is identified.

Note that  a blank is  not a valid  value in the  Language column.   If
you  have a  default language,  you must  code for  it and  prevent the
override.

For example,

             IF          (&LANG *NE ' ') DO /* Not the default */
             RTVLNGMSGF  LANG(&LANG) RTNMSGF(&MSGF) RTNMSGFL(&MSGFL)
             OVRMSGF     MSGF(USRMSGS) TOMSGF(&MSGFL/&MSGF)
             ENDDO       /* Not the default */

Restrictions
------------

Because  RTVLNGMSGF returns  a variable, the  command can  only be used
in a CL  program.  It  is possible to  call the  CPP directly from  any
HLL program.

The code page is not changed.

Prerequisites
-------------

The following TAA Tools must be on your system:

     CONARR          Constant array
     SNDCOMPMSG      Send completion message
     SNDESCMSG       Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   TAALNGA       *CMD                   TAALNGA       QATTCMD
   TAALNGA2      *CMD                   TAALNGA2      QATTCMD
   TAALNGAC      *PGM       CLP         TAALNGAC      QATTCL
   TAALNGAC2     *PGM       CLP         TAALNGAC2     QATTCL

Structure
---------

RTVLNGMSGF  Cmd
   TAALNGAC   CL pgm

CRTLNGMSGF  Cmd
   TAALNGAC2   CL pgm