NAME

gencat - Creates and modifies a message catalog

SYNOPSIS

gencat catalog_file [source_file ...]

DESCRIPTION

The gencat command can be used to create a message catalog (usually ending in .cat) from a message text source file (usually ending in .msg). 

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. 

Generally, programmers use symbolic names rather than numeric constants to refer to messages within programs.  The gencat utility does not recognize symbolic names, but OSF/1 provides a utility named mkcatdefs that accepts messages preceded by a symbolic name and assigns a numeric value to each.  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 do not specify a source file, the gencat command accepts message source data from standard input.  Note that you can specify a - (dash) for the catalog file (standard output) or the source file (standard input). 

The catalog_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 catalog_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.  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. 

$delset set_number
Deletes the set of messages indicated by set_number. 

$quote character
Sets the quote character to character.  See the explanation later in this section. 

$len [max_length]
Sets the maximum length allowed for messages in your catalogue.  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).  Note that $len is an extension to X/Open specifications and therefore may not be supported by all systems that conform to XPG4. 

$set set_number
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 can not go back to a lower-numbered set during the gencat session. If the command is not used, the default set number is 1. 

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.  You must run the mkcatdefs command if you want to use symbolic identifiers. 

The Escape character \ (backslash) can be used to include the following special characters in the message text:

\nInserts a newline. 

\tInserts a horizontal tab character. 

\vInserts a vertical tab. 

\bPerforms a backspace function. 

\rInserts a carriage return. 

\fInserts a formfeed character. 

\\Inserts a \ (backslash) character. 

\dddInserts 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
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.  This escape sequence is an extension to X/Open specifications. 

You can also include printf() conversion specifications in messages that are printed by the printf() family of calls in C code.  If you display a message from a shell script with dspmsg, the only conversion specifications that can be used in the message are %s and %n$s. 

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.

The preceding two lines define the 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. 

NOTES

The gencat command conforms to X/Open specifications.  In an X/Open conforming application, set numbers must be integers in the range of 1 to NL_SETMAX, inclusive, and message numbers must be integers in the range of 1 to NL_MSGMAX, inclusive. 

DIAGNOSTICS

When gencat reports an error, no action is taken on any commands, and an existing catalog is left unchanged. 

RELATED INFORMATION

Commands:  dspcat(1), dspmsg(1), extract(1), mkcatdefs(1), runcat(1), strextract(1), strmerge(1), trans(1). 

Functions:  catclose(3), catgets(3), catopen(3). 

Files: patterns(4).