Document revision date: 19 July 1999

This section describes the following commands offered by the DEC C Run-Time Library utilities:

• GENCAT
• ICONV COMPILE
• ICONV CONVERT
• LOCALE COMPILE
• LOCALE LOAD
• LOCALE UNLOAD
• LOCALE SHOW CHARACTER_DEFINITIONS
• LOCALE SHOW CURRENT
• LOCALE SHOW PUBLIC
• LOCALE SHOW VALUE
• zic

Merges message text source files into a message catalog file.

Format

GENCAT msgfile[,...] catfile

Parameters

msgfile

Required.

Name of the message text source file. The default file type is .MSGX.

catfile

Required.

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.

Qualifiers

None.

Description

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 DEC 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.

errors

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

Examples

$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.

Creates a conversion table file from a conversion source file. The conversion table file is used by the ICONV CONVERT command to convert characters in a file from one codeset to another.

Format

ICONV COMPILE sourcefile tablefile

Parameters

sourcefile

Required.

Name of the conversion source file. The default file type is .ISRC. The file naming convention that Digital uses for conversion source files is:

fromcodeset_tocodeset.isrc

tablefile

Required.

Name of the conversion table file to be created. The default file type is .ICONV. The required file naming convention for conversion table files is:

fromcodeset_tocodeset.iconv

Public conversion table files are in the directory defined by the logical name SYS$I18N_ICONV. Put new conversion table files in the same directory if you want to make them available systemwide.

Qualifiers

/LISTING[=listfile]

Directs ICONV COMPILE to produce a listing file, which contains the source file listing and any error messages generated during compilation. If the file name is omitted from the qualifier, the default listing file name is sourcefile.LIS.

Description

The ICONV commands support any 1- to 4-byte codesets that are state independent. They do not support state-dependent codesets.

Note There is an implementation restriction in the tocodeset encodings in this implementation. The characters in tocodeset must not use 0XFF in the fourth byte.

The conversion source file contains the character conversion rules for a specific conversion.

The format of a codeset conversion source file is defined as follows:

<fromcodeset_mb_cur_max> value <fromcodeset_mb_cur_min> value <tocodeset_mb_cur_max> value <tocodeset_mb_cur_min> value <fallback_code> value <escape_char> value <comment_char> value <fromcodeset_range> value...value;value...value;...;value...value ICONV_TABLE fromvalue tovalue fromvalue tovalue . . . . . . fromvalue tovalue END ICONV_TABLE

where the <...> symbols and their associated values are codeset declarations, and the fromvalue/tovalue pairs are character conversion rules.

Codeset Declarations

The codeset declarations must precede the character conversion rules. Each declaration consists of a symbol, starting in column 1 and including the surrounding brackets, followed by one or more blanks (tabs or spaces), followed by the value to be assigned to the symbol. See Table 4-2.

Table 4-2 Codeset Declarations

Symbol	Value
<fromcodeset_mb_cur_max>	The maximum number of bytes in a character in the fromcodeset. This value defaults to 1.
<fromcodeset_mb_cur_min>	The minimum number of bytes in a character in the fromcodeset. This value must be less than or equal to fromcodeset_mb_cur_max. If this value is not specified, it defaults to the value of fromcodeset_mb_cur_max.
<tocodeset_mb_cur_max>	The maximum number of bytes in a character in the tocodeset. This value defaults to 1.
<tocodeset_mb_cur_min>	The minimum number of bytes in a character in the tocodeset. This value must be less than or equal to tocodeset_mb_cur_max. If this value is not specified, it defaults to the value of tocodeset_mb_cur_max.
<fallback_code>	The tovalues for the fromvalues that appear in the <fromcodeset_range> but are not specified between ICONV_TABLE and END ICONV_TABLE. Specify one of three kinds of values: SAME --- Specifies that the tovalues are the same as the fromvalues. ERROR --- Specifies that the conversion from the fromvalue to a tovalue is not supported. ICONV CONVERT issues a warning and ignores the rest of the record read. The DEC C Run-Time Library routine iconv returns to the caller with an "illegal character" error. User-defined tovalue --- The fromvalues are converted to the specified user-defined tovalue. The user-defined tovalue can represent a multibyte character with the restriction that 0XFF cannot be used as the value in the fourth byte. The settings for user-defined tovalues for <fallback_code> are the same as the settings for character conversion rule values. You can use octal, decimal, or hexadecimal digits. If the <fallback_code> is not specified, it defaults to SAME.
<escape_char>	The escape character used to indicate that subsequent characters are interpreted in a special way. The escape character defaults to backslash (\).
<comment_char>	The character that, when placed in column 1 of a line, indicates that the line will be ignored. The default comment character is the number sign (#).
<fromcodeset_range>	The fromcodeset encoding ranges. Specify this declaration if the fromcodeset is a multibyte codeset. If the fromcodeset is omitted, it defaults to a single-byte codeset and the table created by ICONV COMPILE will support only single-byte fromcodeset conversions.

When specifying codeset encoding ranges for the fromcodeset, every zone of characters must be specified. If any zones of characters are missing from the <fromcodeset_range> specification, the codeset conversion might be incorrect. It is very important to specify the codeset encoding ranges correctly for the fromcodesets supported by the rest of the DEC C Run-Time Library. If this is not done, the codeset support for iconv and the rest of the DEC C Run-Time Library will not be consistent.

For example, the fromcodeset ranges for EUCJP are specified as:

<fromcodeset_range> \x0...\x7f;\x8e\xa1...\x8e\xfe; \xa1\xa1...\xfe\xfe;\x8f\xa1\xa1...\x8f\xfe\xfe

The settings for <fromcodeset_range> values are the same as the settings for character conversion rule values. You can use octal, decimal, or hexadecimal digits.

Character Conversion Rules

The character conversion rules are all the lines between the string ICONV_TABLE starting in column 1 and END ICONV_TABLE starting in column 1.

Character conversion rules must begin in column 1.

Empty lines and lines containing a comment_char in the first column are ignored. Comments are optional.

Character conversion rules can have one of two forms:

fromvalue tovalue fromvalue...fromvalue tovalue

Place one or more blanks (tabs or spaces) between fromvalue and tovalue.

Use the first format to define a single-character conversion rule. For example:

\d32 \d101 \d37 \d106

Use the second format to define a range of character conversion rules. In this format, the ending fromvalue must be equal to or greater than the starting fromvalue. The subsequent fromvalues defined by the range are converted to tovalues in increasing order.

For example, consider the following line:

\d223\d32...\d223\d35 \d129\d254

This line is interpreted as:

\d223\d32 \d129\d254 \d223\d33 \d129\d255 \d223\d34 \d130\d0 \d223\d35 \d130\d1

For settings of fromvalue and tovalue:

• A decimal constant is defined as one, two, or three decimal digits preceded by the escape character and lowercase d. For example: \d42.
• An octal constant is defined as one, two, or three octal digits preceded by the escape character. For example: \141.
• A hexadecimal constant is defined as one or two hexadecimal digits preceded by the escape character and a lowercase x. For example: \x6a.

Each constant represents a single-byte value. You can represent multibyte values by concatenating two or more decimal, octal, or hexadecimal constants.

Note When constants are concatenated for multibyte values, they must have the same radix (decimal, octal, or hexadecimal). Only characters in the Portable Character Set can be used to construct conversion source files.

Also see the ICONV CONVERT command.

errors

If an error is encountered during processing, ICONV COMPILE does not generate an output tablefile. If a warning is encountered, a valid table file is created. However, because a warning can indicate a user error, always check the returned warning messages.

Some ICONV COMPILE error messages and their descriptions follow.

%ICONV-E-INVFCSRNG, syntax error in <fromcodeset_range> definition

The previous error occurs when the definition of the <fromcodeset_range> symbol does not conform to the required syntax. The <fromcodeset_range> symbol defines encoding ranges and is required for multibyte codesets.

%ICONV-E-INVSYNTAX, invalid file syntax

The previous error occurs when a line in the source does not conform to the required syntax.

%ICONV-E-BADTABLE, bad table caused by invalid value for <fromcodeset_range> definition

The previous error occurs when an invalid value is specified for the codeset encoding ranges. The encoding ranges are defined by the <fromcodeset_range> symbol.

Examples

$ ICONV COMPILE /LISTING EUCTW_DECHANYU.ISRC EUCTW_DECHANYU.ICONV
 
      

This example shows how to create a conversion table file to convert the EUCTW codeset to the DECHANYU codeset. The listing file, EUCTW_DECHANYU.LIS, contains a listing of the source file and any error messages generated by the compiler.

	privacy and legal statement
6494PRO_004.HTML