 |
Index for
Section 1 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
gencat(1)
NAME
gencat - Creates and modifies a message catalog
SYNOPSIS
gencat catalog_file source_file...
STANDARDS
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.
OPERANDS
catalog_file
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 .cat extension on the
filename of a message catalog.
source_file...
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 .msg 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 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.
message_number text
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.
$delset set_number [comment]
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.
$quote character [comment]
Sets the quote character to character. See the explanation later in
this section.
$len [max_length] [comment]
[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.
$set set_number [comment]
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
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 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:
\n Inserts a newline (NL or LF).
\t Inserts a horizontal tab (HT).
\v Inserts a vertical tab (VT).
\b Performs a backspace function (BS).
\r Inserts a carriage return (CR).
\f Inserts a form feed (FF).
\\ Inserts a backslash (\).
\ddd
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.
\xdd or \xdddd
[Tru64 UNIX] Inserts the character associated with the hexadecimal
value represented by the hexadecimal digits. The gencat command inserts
a single-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 messages
returned by the gencat command:
% dspcat msgfac.cat | grep gencat
EXAMPLES
1. 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.
2. 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.
3. 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.
4. 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
The following locale environment variables (see i18n_intro(5) and
l10n_intro(5)) affect gencat operation:
LANG
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.
LC_ALL
If set to a non-empty string, overrides values in all locale variables,
including LANG.
LC_CTYPE
Determines the locale for the interpretation in text data of byte
sequences as characters.
LC_MESSAGES
Determines the locale used for diagnostic messages.
NLSPATH
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
|
Index for
Section 1 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|