OSF

NAME

mkcatdefs − Preprocesses a message source file

SYNOPSIS

mkcatdefs [-h] symbol_name source_file ... 

The mkcatdefs message facility program preprocesses a message source file. The source_file message source file contains symbolic identifiers. 

FLAGS

-hSuppresses the generation of a _msg.h file. 

DESCRIPTION

The mkcatdefs program produces the symbol_name_msg.h file containing definition statements equating your symbolic identifiers with set numbers and message ID numbers assigned by mkcatdefs.  symbol_name _msg.h file is required in your application program if you use symbolic identifiers. 

The mkcatdefs program sends message source data, with numbers instead of symbolic identifiers, to standard output. This output is suitable as input to the gencat program. You can use the > (redirection symbol) to write the message source to a file, then use the file as input to gencat.  You can create a message text source file using any text editor to enter the messages. 

Assign message set numbers and message ID numbers to each message by using the commands described in the following section. 

Symbolic Message Identifiers

The OSF/1 operating system provides a mechanism that allows symbolic references to messages by letting you use alphanumeric identifiers instead of set numbers and message ID numbers. You assign the identifiers to sets and messages in the source file in the same manner that you assign set numbers and message ID numbers. 

The symbolic identifiers can contain ASCII letters, digits, and underscores. The first character cannot be a digit. The maximum length cannot exceed 64 bytes. 

The following example shows a message source file with symbolic message identifiers:

$set symbolicMessage Facility - Symbolic ID’s
$quote ∗
ID_names  ∗Symbolic identifier syntax: \n \
\tASCII alphanumerics or underscores \n \
\tnon-digit first character \n \
\t64 byte maximum length ∗
set_use∗To assign set ID: \n \
\t$set "identifier" [comment] ∗
msg_use∗To assign message ID: \n \
\t"identifier" message-text ∗

Japanese Language Support

If Japanese Language Support is enabled on your system, this command is not available. 

SUBCOMMANDS

Use the $set command in a source file to give a group of messages a set number. The format of the $set command is as follows:

$ set n [ comment ]

The set number is specified by n. Instead of a number, you can specify a symbolic identifier that must contain only ASCII letters, digits, or the _ (underscore character). The maximum length of an identifier is 65 bytes. The mkcatdefs program assigns a set number to the identifier. The assigned set number is one higher than the preceding set number, or 1 if it is the first $set. 

Note that mkcatdefs inserts a $delset before the $set in the output message source file. 

You can mix numbers and symbolic identifiers. 

You can include a comment in the $set command, but it is not required. The following example includes a comment:

set CEM  Communication Error Messages

Use the $delset command to remove all of the messages belonging to the specified set from a catalog. The format of the $delset command is as follows:

$delset n [ comment ]

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. 

You can include a comment line anywhere in the source file, except within message text. Indicate comments as follows:

$ [ comment ]

You must leave at least one space after the $ prompt. 

Enter the message text and symbolic message identifier as follows:

identifier message_text

identifier can be either a number or a symbolic identifier and can contain only ASCII letters, digits, or the _  (underscore character). The maximum length of an identifier is 65 bytes. The mkcatdefs program assigns a message number to the identifier. The assigned number is one higher than the preceding message number, or 1 if it is the first message after the $set command. 

Note that mkcatdefs inserts a $delset before the $set, which means you cannot add, delete, or replace single messages in the catalog if you are using symbolic message identifiers. You must enter all of the messages in the set. 

You can mix numbers and symbolic identifiers. 

You must leave at least one space after the message identifier or number. 

OSF/1 allows any amount of white space after the message ID number; however, X/Open specifies that you leave only one space between the message number and the message text. All text following the first nonspace character to the end of the line is included in the message text.  If the source contains a $quote command preceding the message, all text between the quotation marks is included. Use a \ (backslash) character to continue message text on the following line.  The \ must be the last character on the line, as in the following example:

FIVEText associated with \
message FIVE.

These two lines define the following single-line message:

FIVEText associated with message FIVE.

The \ can be used to include special characters in the message text. These special characters are defined as follows:

\nInserts a newline character. 

\tInserts a horizontal tab character. 

\vInserts a vertical tab. 

\bInserts a backspace character. 

\rInserts a carriage-return character. 

\fInserts a formfeed character. 

\\Inserts a \ (backslash) character. 

\dddInserts the single-byte character associated with the octal value represented by the valid 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 $ is 44. To display $5.00, use \0445.00, not \445.00, or the 5 will be parsed as part of the octal value. 

This escape sequence is an OSF/1 extension to X/Open. 

\xddddDisplays the single-byte or double-byte character associated with the hexadecimal value represented by the four valid hexadecimal digits dddd. You can specify one, two, three, or four digits, but you must include leading zeros to avoid parsing errors (see \ddd). 

You can also include printf() conversion specifications in messages that are displayed by applications using printf().  If you display a message from a shell script with dspmsg, the message can contain the %s or %n$s conversion specifications.  You can use the $quote command in a message source file to define a character for delimiting message text. The format for this command is as follows:

$quote [ char ] [ comment ]

Use the specified character before and after the message text as shown in the following example source file:

$quote "Use a double quotation mark to delimit message text
$set MSFACMessage Facility - symbolic identifiers
SYM_FORM"Symbolic identifiers can only contain ASCII letters \
or digits or the _ (underscore character)\n"
SYM_LEN"Symbolic identifiers cannot be more than 65 \
bytes long\n"
5"You can mix symbolic identifiers and numbers \n"
$quote
MSG_HRemember to include the "msg_h" file in
your program\n

In this example, the $quote command sets the quote character to " (double quote), then disables it before the last message, which contains double quotes. 

The preceding file can be processed with mkcatdefs as follows:

$ mkcatdefs symb symb.src >symb.msg

When you process the file with mkcatdefs, the modified source is written to standard output.  Standard output can either be redirected to a file using the > (redirection symbol) or piped to gencat. 

The following source is created:

$quote "Use double quotation marks to delimit message text
$delset 1
$set 1
1"Symbolic identifiers can only contain ASCII letters \
or digits or the _ (underscore character)\n"
2"Symbolic identifiers cannot be more than 65 \
bytes long\n"
5"You can mix symbolic identifiers and numbers\n"
$quote
6remember to include the "msg_h" file in your program

Note that the assigned message numbers are noncontiguous because the source contained a specific number. The mkcatdefs program always assigns the previous number plus 1 to a symbolic identifier. 

The mkcatdefs program also produces a definition file for inclusion in your program. The name of the file is symbol_name, and is entered as the first argument to the mkcatdefs command.  (If you specify the -h flag instead of the symbol_name, no definition file is produced.) 

EXAMPLES

If the symbolic source defined in SUBCOMMANDS were in a file called symb.src, you could use the mkcatdefs command as follows:

$ mkcatdefs symb symb.src >symb.msg

The generated symb_msg.h file would appear as follows:

#ifndef _H_SYMB_MSG
#define _H_SYMB_MSG
#include <limits.h>
#include <nl_types.h>
#define MF_SYMB "symb.cat"
/∗ The following was generated from symb.src. ∗/
/∗ definitions for set MSFAC ∗/
#define MSFAC 1
#define SYM_FORM 1
#define SYM_LEN 2
#define MSG_H 6

Note that mkcatdefs also created  a symbol MF_SYMB by adding MF_ to the symbol_name using uppercase letters. The mkcatdefs program assumes that the name of the generated catalog should be symbol_name.cat, and generates this symbol for your use with catopen. 

Because this file includes limits.h and nl_types.h, you do not need to include them in your application program.  (nl_types defines special data types required by the message facility routines.) 

RELATED INFORMATION

Commands:  dspcat(1), dspmsg(1), gencat(1). 

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

Implementation Specifics

Symbolic references are not defined by X/Open, but are an OSF/1 extension that contain symbolic identifiers, allowing gencat to create the symbol_name message catalog.