OS/2 Message Table Generator     May 1988
            (A quick 'n dirty production)


Introduction
------------
OS/2 provides support for maintaining messages in
in a separate file from the program. Keeping all
messages in a separate file facilitates the
translation of these messages into other languages.

Using OS/2 message facility
---------------------------
To use this facility, the programmer uses OS/2
calls (eg., DosGetMessage) to refer to messages
in a file. Each message must have a unique number
and the message tables have a very precise format.
The programmer has the bookkeeping burden and must
generally keep track of the mapping of message codes
into messages in the table. This is a PITA.

Purpose of MESSGEN
------------------
MESSGEN allows you to keep a file of mnemonics and messages
using GML tags (thanks to Jim Thatcher for suggesting
that format). It generates the two files needed by
OS/2's MakeMessageFacility.

It also generates files for C, MASM and Pascal
that map the mnemonics to integer numbers. These numbers
match the corresponding messages in the message files.
The numbers are generated in sequence and no bookkeeping
is required.


Example
-------
The file EXAM.TAG contains the following definitions

.*Definitions for the EXAM program
:name.DiskSlow
:type.W
:msg.Your floppy disk is running slowly
:emsg.
:help.Try putting a new battery in it
:ehelp
:ename.
:name.FileLost
:type.E
:bind
:msg.This file has been erased. Sorry
:emsg.
:help.That will teach you not to keep backups
:ename.

Tags MUST start in column 1.

The meaning of the tags are as follows:
   .*         A comment. The line is ignored
   :name.     The mnemonic that you will use to refer to the message
   :type.     OS/2 defines 4 types. They are I, W, E and P.
   :msg.      The message text corresponding to the mnemonic
   :emsg.     Signifies end of msg text
   :help.     Extra help that the user gets on request
   :ehelp.    End of help text
   :ename.    End of this definition
   :bind.     Specifies that this message will be bound
              to an executable file. The sequence number
              is appended to a .PRO file.


The :msg. and :help. sections are optional. If they are not
defined, then empty messages will be generated. You can
define one without the other. The text of messages and extra
help text can span multiple lines.
The :bind. tag is inserted ahead of a :msg. or :help. tag.


Run MESSGEN with the following parameters on the command line

MESSGEN /c exam.tag

The first parameter tells MESSGEN to generate a file suitable
for inclusion in a C program. The second parameter is
the name of the tagged file.


Output from MESSGEN
-------------------

The following files are generated by MESSGEN:

exa.h  (For C)
-----
#define DiskSlow 1
#define FileLost 2

exa.txt (For input to MkMsgF)
-------
EXA
EXA0001W: Your floppy disk is running slowly
EXA0002E: This file has been erased. Sorry

exah.txt (For input to MkMsgF)
--------
EXA
EXA0001H: Try putting a new battery in it
EXA0002H: That will teach you not to keep backups


The mnemonic names can be used in the DosGetMessage calls.



Controlling the output of MESSGEN
---------------------------------

MESSGEN can accept multiple sets of tagged files and can
generate output for several languages.

The general command line format for MESSGEN is:

MESSGEN  Õ/pþ Õ/cþ Õ/mþ Õ/b <file>þ Õ/iþ <source files>


   Switch       Meaning
   --------------------
   /p           Generate constants for Pascal
   /c           Generate #define macros for C
   /m           Generate EQU statements for Masm
   /i           Ignore case when checking for duplicates
   /b           Generate a .PRO file which specifies binding
                information. <file> should be the name of the
                executable file to which messages will be bound
                with the MSGBIND program (See the toolkit for more
                details on the subject of binding)

At least one language switch must be used. Ignoring the case
of names is useful when generating output for Pascal. It's also
useful for Masm if you use Masm's case sensitivity option.
You can then specify a list of one or more files that contain
tagged definitions for processing. Seperate file names with
spaces. Each file may contain a set of definitions. You must
not spread one definition over multiple files.

Typing MESSGEN by itself on the command line will generate the
usage message showing the format of parameters.


Duplicate names
---------------
MESSGEN will detect duplicate names in the definitions. It will
display the filename and line number of the previous definition.
Upper and lower case names are distinct unless you use the /i
option.


David Jameson