GENCAT - Generate Message Catalog Utility (OS/2, Windows)

One of the requirements for internationalization of programs is that messages be displayed in the language of the user. This requirement is satisfied by producing versions of the messages that are translated into all supported languages.

The C library messaging support is based on the messaging support described in the X/Open Portability Guide Issue 4 (XPG4) specification. It consists of functions for extracting messages from message catalog files (catopen, catgets, catclose) and utilities for producing message catalog files (GENCAT, MKCATDEF).

The Generate Message Catalog Utility (GENCAT) creates and modifies a message catalog. GENCAT creates the message catalog (usually *.cat) from a message text source file (usually *.msg) or standard input.

If a message catalog with the name specified by the CatalogFile parameter exists, GENCAT modifies it according to the statements in the specified message source files. If the message catalog does not exist, GENCAT creates a catalog file with the name specified by the CatalogFile parameter. For the definition of parameters, please refer to the syntax diagram below.

You can specify any number of message source files. GENCAT processes multiple source files, one after another, in the sequence specified. Each successive source file modifies the catalog. If you do not specify a source file, GENCAT accepts message source data from standard input.

GENCAT does not accept symbolic message identifiers. You must run MKCATDEF if you want to use symbolic message identifiers in your message source file.

Note: To create an internationalized message catalog, the code page used to compose your messages must also be the code page specified in the current locale setting before running the GENCAT or MKCATDEF tool.

Syntax

gencat CatalogFile [ SourceFile ... ]

where:

CatalogFile the name of the catalog file to be created by the gencat command.
SourceFile the name of the source file containing the message text. This file does not contain symbolic identifiers. If you want to use symbolic identifiers, the file must be processed through the MKCATDEF utility.

If no SourceFile is specified and standard input is to be used, replace this option with a dash ( - ).

gencat CatalogFile -

Examples
To generate a test.cat catalog from the source file test.msg, enter:

gencat test.cat test.msg

The test.msg file does not contain symbolic identifiers.

To generate a test.cat catalog from standard input, enter:

gencat test.cat -

Source File Syntax
All fields of a source line are separated by a single blank character. Any other blank characters are considered as being part of the subsequent field.

Comments begin with a $ followed by a space and the text of the comment. For example:

$ This is a comment

A $set directive is used to associate a set number with all subsequent messages, until the end of file or the next $set directive. The format is:

$set <number> <comment>

For example:

$set 1 this is the first set in the file

The set number must be in the range [1, {NL_SETMAX }]. Set numbers must be ascending within the file, but need not be contiguous. Any string following the set number is treated as a comment. If no $set directive is specified in a message text source file, all messages will be located in an implementation-defined default message set NL_SETD.

A $delset directive is used to delete a message set from an existing message file. The format is:

$delset <number> <comment>

For example:

$delset 1 this deletes any previous definition of set 1 from this file

A message consists of a message number followed by the message text. The message number must be in the range [1, {NL_MSGMAX} ]. The message text is stored in the message catalog with the set identifier specified by the last $set directive, and the message number. If the message text is empty, and a blank character field separator is present, an empty string is stored in the message catalog. If a message source line has a message number, but neither a field separator nor message text, the existing message with that number (if any) is deleted from the set. Message numbers must be in ascending order with a single set, but need not be contiguous. The length of the message text must be in the range [0, {NL_TEXTMAX} ].

For example:

1 "This is the first message"
2 "This is the second message"

A $quote directive specifies an optional quote character, which can be used to surround message text so that trailing spaces or null messages are visible in a message source line. By default, or if an empty $quote directive is supplied, no quoting of message text will be recognized. The format is:

$quote <character>

For example:

$quote "

Empty lines in the message file are ignored. The effects of lines starting with any character other than those defined above are implementation-defined.

Text strings can contain the special characters and escape sequences defined in the following table:

Description Sequence
new line character \n
horizontal tab \t
vertical tab \v
backspace \b
carriage return \r
form feed \f
backslash \\
octal character encoding \ddd (three or fewer octal digits)
hexadecimal character encoding \xhhh (one or more hexadecimal digits (A-F, 0-9)

If the character following a backslash is not one of the above or the end-of-line, the backslash is ignored. A backslash at the end of a line is used to continue a string on the following line. For example:

1 This line continues \
to the next line


Localization and Locales


Build a Locale


MKCATDEF - Preprocess Message Source File Utility
RUNCAT - Running Message Catalog File Utility
C Library Reference - catopen
C Library Reference - catgets
C Library Reference - catclose