gencat(1)gencat(1)NAMEgencat - Creates and modifies a message catalog
SYNOPSISgencat catalog_file source_file...
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
gencat: XCU5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
OPERANDS
Specifies the message catalog to be modified or created. You can sub‐
stitute - (a dash) for this operand to direct command results to the
standard output rather than to a file.
[Tru64 UNIX] The convention is to include the extension on the
filename of a message catalog. Specifies the message text
source file, or files, used to modify or create the message cat‐
alog. You can substitute - (a dash) for this operand to direct
gencat to accept message source data from the standard input.
[Tru64 UNIX] You can also omit the source_file operand to
direct gencat to accept message source data from the standard
input. This extension is supported only to ensure backward com‐
patibility for existing scripts. For new scripts, it is recom‐
mended that you specify - (a dash) for source_file when you want
gencat to accept message source data from the standard input.
[Tru64 UNIX] The convention is to include the extension on the
filename of a message text source file.
DESCRIPTION
The gencat command creates or modifies a message catalog from a message
text source file.
A message text source file is a text file that you create to hold mes‐
sages printed by your program. You can use any text editor to enter
messages into the text source file. Messages can be grouped into sets,
generally to represent functional subsets of your program. Each mes‐
sage has a numeric identifier, which must be unique within its set.
The message text source file can also contain commands recognized by
gencat for manipulating sets and individual messages.
[Tru64 UNIX] Programmers can use symbolic names rather than numeric
constants to refer to messages within programs. The gencat utility
does not recognize symbolic names, but the mkcatdefs: Accepts messages
preceded by a symbolic name and assigns a numeric value to each Creates
a header file that applications can include to map message symbols to
their numeric values
[Tru64 UNIX] Therefore, the most convenient way to generate a message
catalog is to pass your symbolic constants and associated messages
through mkcatdefs and then pass its output to gencat.
If a message catalog with the name catalog_file exists, gencat modifies
it according to the statements in the message source files. If the cat‐
alog does not exist, gencat creates the catalog with the name cata‐
log_file.
You can specify any number of message text source files. The gencat
command processes multiple source files one after the other in the
sequence that you specify them. Each successive source file modifies
the catalog. If you specify - (a dash) in place of source_file, the
gencat command accepts message source data from the standard input.
Note that you can specify a - (dash) for the catalog file (standard
output), the source file (standard input), or both.
The source_file can contain the following commands. Each initial key‐
word or number must be followed by white space. The gencat utility
ignores any line beginning with a space, a tab, or a $ (dollar sign)
character followed by a space, a tab, or a newline character. Thus, you
can use these sequences to start comments in your source_file. Blank
lines are also ignored. Finally, you can place comments on the same
line after the $delset, $quote, $len, or $set commands, because the
gencat utility ignores anything following the preceding syntax ele‐
ments. Inserts text as a message with the identifier message_number.
Numbers must be ascending within each set: you can skip a number, but
you cannot go back to add a missing number or replace an existing num‐
ber during a gencat session.
The value for message_number must be in the range 1 to NL_MSG‐
MAX, which is defined in the <limits.h> header file.
If the message text is empty, and a space or tab 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 within that
number (if any) is deleted from the catalog.
Refer to the following description of $len for a discussion of
the length limits that apply to message text. Deletes the set
of messages indicated by set_number.
The set_number parameter must be in the range 0 to NL_SETMAX,
which is defined in the <limits.h> header file. Sets the quote
character to character. See the explanation later in this sec‐
tion. [Tru64 UNIX] Sets the maximum length allowed for mes‐
sages in your catalog. If this command is not used, or if you
use it without the max_length argument, the maximum length is
8192 bytes (the value set by NL_TEXTMAX, which is defined in the
<limits.h> header file). XCU does not include the $len command
and specifies that the length of message text be in the range 0
to NL_TEXTMAX.
[Tru64 UNIX] If gencat does not encounter a digit immediately
following the single nonblank character separator between $len
and its first argument, the command ignores the rest of the
line. Therefore, if you intend to include the optional
max_length parameter, make sure only one space or tab character
separates the number from $len. Indicates that all messages
entered after this command are placed in the set indicated by
set_number. You can change the set by entering another $set
command. However, set numbers must be entered in ascending
order; you cannot go back to a lower-numbered set during the
gencat session. If the command is not used, the default set num‐
ber is the value of NL_SETD in the <nl_types.h> header file.
This value is vendor-defined. On this operating system, the
NL_SETD value is 1.
The set_number parameter must be in the range 1 to NL_SETMAX,
which is defined in the <limits.h> header file.
A line beginning with a digit marks a message to be included in the
catalog. You can specify any amount of white space between the message
ID number and the message text; however, one space or tab character is
recommended when the message text is not delimited by quotes. When mes‐
sage text is not quoted, gencat treats additional white space as part
of the message. When message text is quoted, gencat ignores all spaces
or tabs between the message ID and the first quotation character.
Escape sequences, like those recognized by the C language, can be used
in text; these are listed after the commands. Use a \ (backslash) char‐
acter to continue message text on the following line.
The gencat command does not accept symbolic identifiers.
[Tru64 UNIX] You must run the mkcatdefs command if you want to use
symbolic identifiers for messages in your program.
The Escape character \ (backslash) can be used to include the following
special characters in the message text: Inserts a newline (NL or LF).
Inserts a horizontal tab (HT). Inserts a vertical tab (VT). Performs
a backspace function (BS). Inserts a carriage return (CR). Inserts a
form feed (FF). Inserts a backslash (\). Inserts the single-byte
character associated with the octal value represented by the octal dig‐
its ddd. One, two, or three octal digits can be specified; however, you
must include leading zeros if the characters following the octal digits
are also valid octal digits. For example, the octal value for $ (dol‐
lar sign) is 44. To insert $5.00 into a message, use \0445.00, not
\445.00, or the 5 will be parsed as part of the octal value. [Tru64
UNIX] Inserts the character associated with the hexadecimal value rep‐
resented by the hexadecimal digits. The gencat command inserts a sin‐
gle-byte character when you specify two valid digits (dd) and a double-
byte character when you specify four valid digits (dddd). See \ddd for
a way to avoid parsing errors when the hexadecimal value precedes an
actual digit.
You can also include printf() conversion specifications in messages
that are printed by the printf() family of calls in C code or by the
printf command in shell scripts.
[Tru64 UNIX] If you display a message from a shell script with the
dspmsg command, the only conversion specifications that can be used in
the message are %s and %n$s.
EXIT STATUS
On successful completion, the gencat command returns 0 (zero); on
error, the command returns a value greater than zero. When gencat
returns an error value, no action is taken on any commands, and an
existing catalog is left unchanged.
ERRORS
[Tru64 UNIX] You can enter the following command to display the mes‐
sages returned by the gencat command: % dspcat msgfac.cat | grep gencatEXAMPLES
To use the $set command in a source file to give a group of messages a
set number, enter: $set 10 Communication Error Messages
The message set number is 10. All messages following the $set
command are assigned that set number, up until the next occur‐
rence of a $set command. (Set numbers must be assigned in
ascending order, but need not be contiguous. Large gaps in the
number sequence are discouraged in order to increase efficiency
and performance. There is no performance advantage to using
more than one set number in a catalog.)
You can include a comment in the $set command, but it is not
required. To use the $delset command to remove all of the mes‐
sages belonging to the specified set from a catalog, enter:
$delset 10 Communication Error Messages
The message set is specified by n. The $delset command must be
placed in the proper set number order with respect to any $set
commands in the same source file. You can include a comment in
the $delset command also. Enter the message text and assign
message ID numbers as follows: 12 "file removed"
This command assigns the message ID number 12 to the text that
follows it.
You must leave at least one space or tab character between the
message ID number and the message text, but you can include more
spaces or tabs if you prefer. If you do include more spaces or
tabs, they will be ignored when message text is quoted and con‐
sidered part of the text when message text is not quoted.
Message numbers must be in ascending order within a single mes‐
sage set, but need not be contiguous.
All text following the message number is included as message
text, up to the end of the line. If you place the escape char‐
acter \ (backslash) as the last character on the line, the mes‐
sage text continues on the following line. Consider the follow‐
ing example:
This is the text associated with \ message number 5.
These two lines define the following single-line message:
This is the text associated with message number 5. The follow‐
ing example shows the effect of a quote character:
$quote " Use a double quote to delimit message text $set 10
Message Facility - Quote command messages 1 "Use the $quote com‐
mand to define a character \ \n for delimiting message text" \n
2 "You can include the \"quote\" character in a message \n \ by
placing a \\ (backslash) in front of it" \n 3 You can include
the "quote" character in a message \n \ by having another char‐
acter as the first nonspace \ \n character after the message ID
number \n $quote 4 You can disable the quote mechanism by \n \
using the $quote command without \n a character \ after it \n
In this example, the $quote command defines the " (double quote)
as the quote character. The quote character must be the first
nonspace character following the message number. Any text fol‐
lowing the next occurrence of the quote character is ignored.
The example also shows two ways the quote character can be
included in the message text: Place a \ in front of the quote
character. Use some other character as the first nonspace char‐
acter following the message number. This disables the quote
character only for that message.
The example also shows the following: A \ is still required to
split a quoted message across lines. To display a \ in a mes‐
sage, you must place another \ in front of it. You can format
your message with a newline character by using \n. If you use
the $quote command with no character argument, you disable the
quote mechanism.
ENVIRONMENT VARIABLES
The following locale environment variables (see i18n_intro(5) and
l10n_intro(5)) affect gencat operation: Provides a default value for
locale category variables that are not set. If any of these variables
contains an invalid setting, the gencat command behaves as if none of
them were defined. If set to a non-empty string, overrides values in
all locale variables, including LANG. Determines the locale for the
interpretation in text data of byte sequences as characters. Deter‐
mines the locale used for diagnostic messages. Determines the location
of message catalogs for the processing of LC_MESSAGES.
SEE ALSO
Commands: dspcat(1), dspmsg(1), extract(1), mkcatdefs(1), printf(1),
runcat(1), strextract(1), strmerge(1), trans(1)
Functions: catclose(3), catgets(3), catopen(3)
Files: patterns(4)
Others: i18n_intro(5), l10n_intro(5), iconv_intro(5), standards(5)
Writing Software for the International Market
gencat(1)
