gencat - Create or modify message catalogs

Format

gencat CatalogFile MessageFile ...

Description

gencat merges the message text source files MessageFile (typically *.msg) into a formatted message catalog CatalogFile (typically *.cat). The file CatalogFile is created if it does not already exist. If CatalogFile does exist, its messages are modified according to the directives in the MessageFiles. If set and message numbers are the same, the new message text defined in MessageFile replaces the message text defined in CatalogFile.

You can specify any number of MessageFiles. gencat processes the MessageFiles one after another, in the sequence specified. Each successive MessageFile modifies the CatalogFile.

If - is specified for CatalogFile, standard output (stdout) is used. If - is specified for MessageFile, standard input (stdin) is used.

gencat does not accept symbolic message identifiers. You must use mkcatdefs if you want to use symbolic message identifiers.

Extended description

The format of a message text source file is defined as follows. All characters must be encoded as single-byte characters except where noted. The fields of a message text source line are separated by a single blank character. Any other blank characters are considered as being a part of the subsequent field.
$set n comment
Specifies the set identifier of the following messages until the next $set or end of file appears. The n denotes the set identifier, which is defined as a number in the range 1-NL_SETMAX. Set identifiers must be in ascending order within a single source file, but need not be contiguous. Any string following the set identifier is treated as a comment. If no $set directive is specified in a message text source file, all messages are located in default message set NL_SETD.
$delset n comment
Deletes message set n from an existing message catalog. The n denotes the set number, 1-NL_SETMAX. Any string following the set number is treated as a comment.
$ comment
A line beginning with $ followed by a blank character is treated as a comment.
m message-text
The m denotes the message identifier, which is defined as a number in the range 1-NL_MSGMAX. Message identifiers must be in ascending order within a single set, but need not be contiguous. The length of message-text must be in the range -NL_TEXTMAX. The message text is stored in the message catalog with the set identifier that is specified by the last $set directive, and with message identifier m. 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 not a field separator or message text, the existing message with that number (if any) is deleted from the catalog. The message text can contain double-byte characters.
$quote c
Specifies an optional quotation mark character c, which can be used to surround message-text so trailing spaces or null (empty) messages are visible in a message source line. By default, or if an empty $quote directive is supplied, no quoting of message-text is recognized. The quotation mark character can be a double-byte character.
$time stamp
Specifies a time stamp that can be used to identity the subsequent .cat file as having come from this file. The timestamp can be up to 20 characters long and can be any format you want. Typically it follows this format: 
$timestamp 1994 137 19:09 UTC
The mkcatdefs command automatically generates a time stamp in the file it creates for input to gencat.

Empty lines in a message text source file are ignored. Lines starting with any character other than those defined are considered invalid.

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

Description Sequence
Backspace \b
Backslash \
Carriage-return \r
Double quotation mark \"
Form-feed \f
Horizontal tab \t
Newline \n
Octal bit pattern \ddd
Vertical tab \v

These sequences must be encoded as single-byte characters.

The escape sequence \ddd consists of backslash followed by one, two, or three octal digits, which are taken to specify the value of the desired character. If the character following a backslash is not one of those specified, the backslash is ignored.

A backslash (\) followed by a newline character is also used to continue a string on the following line. Thus the following two lines describe a single message string: 
1 This line continues \
to the next line
which is equivalent to: 
1 This line continues to the next line

Portability of message catalogs

gencat works with the z/OS XL C/C++ runtime library function catgets() to correctly display message text in the locale that the C program using catgets() is running in. gencat adds information to the CatalogFile about the code set that was in effect when gencat processed the CatalogFile. gencat should be run with the same locale that the recipients of the messages will be using. This should be the same locale that was used to create the message text in MessageFile.

Message catalogs produced by gencat are binary-encoded, meaning that their portability cannot be guaranteed between systems. Thus, just as C programs need to be recompiled, so message catalogs must be recreated via gencat when moved to another system.

Examples

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

Localization

gencat uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_CTYPE
  • LC_MESSAGES
  • LC_SYNTAX
  • NLSPATH

Exit values

0
Successful completion.
1
An error occurred.

Portability

X/Open Portability Guide.