HP OpenVMS Systems Documentation
Compaq C Run-Time Library Utilities Reference Manual
|Symbol Name||Hexadecimal Encoding|
A charmap file has the following components:
Specifies the name of the codeset for which the charmap file is defined. This value determines the value returned by the nl_langinfo (CODESET) subroutine. If <code_set_name> is not declared, the name for the Portable Character Set is used.
Specifies the maximum number of bytes in a character for the codeset. Valid values are 1 to 4. The default value is 1.
Specifies the minimum number of bytes in a character for the codeset. Since all supported codesets have the Portable Character Set as a proper subset, this value must be 1.
Specifies the escape character that indicates encodings in hexadecimal or octal notation. The default value is a backslash (\).
Specifies the character used to indicate a comment within a charmap file. The default value is the number sign (#).
<A> \d65 #decimal constant <B> \x42 #hexadecimal constant <j10101> \x81\xA1 #multiple hexadecimal constants
<j0101> \d129\d254 <j0102> \d129\d255 <j0103> \d130\d0 <j0104> \d130\d1
<period> \x2e <full-stop> \x2e
The following is a portion of a sample charmap file:
CHARMAP <code_set_name> "ISO8859-1" <mb_cur_max> 1 <mb_cur_min> 1 <escape_char> \ <comment_char> # <NUL> \x00 <SOH> \x01 <STX> \x02 <ETX> \x03 <EOT> \x04 <ENQ> \x05 <ACK> \x06 <alert> \x07 <backspace> \x08 <tab> \x09 <newline> \x0a <vertical-tab> \x0b <form-feed> \x0c <carriage-return> \x0d END CHARMAP
This section describes the following commands offered by the Compaq C Run-Time Library utilities:
Merges message text source files into a message catalog file.
GENCAT msgfile[,...] catfile
Name of the message text source file. The default file type is .MSGX.
Name of the message catalog output file. If catfile already exists, a new version is created that includes the messages in the existing catalog. The file type must be .CAT.
The GENCAT command creates new message catalogs from one or more input source files and an existing catalog file (if one exists). A message catalog is a binary file containing the messages for an application. This includes all messages that the application issues, such as error messages, screen displays, and prompts. Applications retrieve messages from a message catalog using the catopen , catgets , and catclose C Run-Time Library routines. See the Compaq C Run-Time Library Reference Manual for OpenVMS Systems for details of these routines.
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, usually 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.
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 a message catalog with the name catfile exists, GENCAT creates a new version of the file that includes the contents of the older version and then modifies it. If the catalog does not exist, GENCAT creates the catalog with the name catfile.
The catfile can contain the following commands:
- message_number text
Inserts text as a message with the identifier message_number. Follow these guidelines:
- 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 with 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 Examples section for more information.
- $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 cannot go back to a lower numbered set during the GENCAT session. If the command is not used, the default set number is 1.
Each initial keyword or number must be followed by white space. The GENCAT utility ignores any line that begins with a space, a tab, or a dollar sign ($) character followed by a space, a tab, or a newline character. Therefore, you can use these sequences to start comments in your catfile. Blank lines are also ignored. Finally, you can place comments on the same line after the $delset, $quote, or $set commands because GENCAT ignores anything that follows these commands.
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, when the message text is not delimited by quotation marks, one space or tab character is recommended. When message text is not in quotation marks, GENCAT treats additional white space as part of the message. When message text is enclosed in quotation marks, GENCAT ignores all spaces or tabs between the message ID and the first quotation character.
Escape sequences such as those recognized by the C language can be used in text. The escape character (\), a backslash, can be used to insert special characters in the message text. See Table 4-1.
Table 4-1 GENCAT Command: Special Characters Escape Sequence Character \n New Line \t Horizontal Tab \v Vertical Tab \b Backspace \r Carriage Return \f Form Feed \\ Backslash Character (\). Use to continue message text on the following line. \ ddd The single-byte character associated with the octal value ddd. You can specify one, two, or three octal digits. 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; otherwise the 5 is parsed as part of the octal value.
When GENCAT reports an error, no action is taken on any commands and an existing catalog is left unchanged.
$set 10 Communication Error Messages
This example uses the $set command in a source file to assign a set number to a group of messages.
The message set number is 10. All messages after the $set command and up to the next $set command are assigned a message set number of 10. (Set numbers must be assigned in ascending order but they need not be contiguous.)
You can include a comment in the $set command.
$delset 10 Communication Error Messages
This example uses the $delset command to remove from a catalog all messages belonging to the specified message set (10, in this case).
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.
12 "file removed"
This example shows how to enter the message text and assign a message ID number to it. In this case, a message ID of 12 is assigned to the text that follows it.
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 are ignored when the message text is in quotation marks and they are considered part of the text when the message text is not in quotation marks.
Message numbers must be in ascending order within a single message set but they need not be contiguous.
All text following the message number and up to the end of the line is included as message text. If you place the escape character (\), a 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 two lines in the example define the following single-line message:
This is the text associated with message number 5.
$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
This example shows the effect of a quote character.
The $quote command defines the double quote (") as the quote character. The quote character must be the first nonspace character after the message number. Any text following the next occurrence of the quote character is ignored.
This example also shows two ways to include the quote character in the message text:
- Place a backslash (\) in front of the quote character.
- Use another character as the first nonspace character after the message number. This disables the quote character for that message only.
This example also shows the following:
- A backslash (\) is still required to split a quoted message across lines.
- To display a backslash (\) in a message, you must place another backslash (\) in front of it.
- You can format your message with a new-line character by using \n.
- If you use the $quote command with no character argument, you disable the quote mechanism.