gencat - Creates and modifies a message catalog
gencat catalog_file source_file...
Interfaces documented on this reference page conform to
industry standards as follows:
gencat: XCU5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the message catalog to be modified or created.
You can substitute - (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 catalog. 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 compatibility for
existing scripts. For new scripts, it is recommended
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.
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 messages 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 message 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 catalog does not exist, gencat
creates the catalog with the name catalog_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 keyword 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 elements. 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 number during a gencat session.
The value for message_number must be in the range 1
to NL_MSGMAX, 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 section.
[Tru64 UNIX] Sets the maximum length allowed for
messages 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 number is the value of NL_SETD in the
<nl_types.h> header file. This value is vendordefined.
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
message 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) character 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 digits 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
$ (dollar 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 represented by the
hexadecimal digits. The gencat command inserts a singlebyte
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.
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.
[Tru64 UNIX] You can enter the following command to display
the messages returned by the gencat command: % dspcat
msgfac.cat | grep gencat
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 occurrence 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 messages 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
considered part of the text when message text is
not quoted.
Message numbers must be in ascending order within a
single message 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 character \ (backslash) as the
last character on the line, the message text continues
on the following line. Consider the following
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 following 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 command 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 character
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 following 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 character 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 message, 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 [Toc] [Back] 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. Determines the locale
used for diagnostic messages. Determines the location of
message catalogs for the processing of LC_MESSAGES.
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)
[ Back ] |
