mkcatdefs(1)mkcatdefs(1)NAMEmkcatdefs - Preprocesses a message source file
SYNOPSISmkcatdefs [-hS] [-m [-p prefix] [-e extension]] catname source_file...
OPTIONS
If the -m option is also specified, identifies the type of include file
to contain the default message strings and their symbolic identifiers.
The value for extension can be one of the following: Generate macros
into a catname_msg.h file. (Default) Generate variable assignments into
a catname_msg.sh file. This file can be included by POSIX, Bourne, and
Korn shell scripts for use with the dspmsg command. Generate variable
assignments into a catname_msg.csh file. This file can be included by
C shell scripts for use with the dspmsg command. Suppresses the gener‐
ation of the catname_msg.h file if -m is not specified or -m is speci‐
fied along with -e sh or -e csh.
Suppresses the macros that map symbolic identifiers for messages
and sets to numeric constants if -m is specified either without
the -e option or with -e h. (The catname_msg.h file is gener‐
ated but contains only the macros that define symbolic identi‐
fiers for default message strings.) Causes the output header
file or shell script include file to contain default message
strings and their symbolic identifiers. Specifies a prefix used
in the identifier for a default message string. If the prefix
is not specified with the -p option, DEF_ is prepended to the
message identifier to form the identifier for the default mes‐
sage string.
Explicitly specifying a catalog-specific prefix is recommended
if programs and scripts access multiple message catalogs. Other‐
wise, there is a risk that the include files generated for the
different catalogs might define the same symbol for different
message strings. The mkcatdefs command returns an error if sym‐
bolic names are not unique within the same catalog; however,
multiple symbol definitions that result from including multiple
include files causes compiler warnings or display of the wrong
message string at run time. Enables inclusion of symbolic set
and message identifiers in the output sent to the gencat com‐
mand. Otherwise, only numeric set and message identifiers are
included in the output sent to the gencat command. See DESCRIP‐
TION and EXAMPLES for information on how these symbolic identi‐
fiers are used at run time.
DESCRIPTION
The mkcatdefs utility preprocesses a message source file to do one or
more of the following operations. These operations ease maintenance of
compilable programs, scripts, or both: Convert symbolic identifiers for
message sets and messages into numeric constants required by the gencat
command. The gencat command creates the catname.cat file accessed by
the catopen(), catgets(), and catgets() functions and by the dspmsg
utility. Create a catname_msg.h file that defines macros to map sym‐
bolic identifiers to corresponding numeric constants in the file. Pro‐
gram source code that specifies an include statement for catname_msg.h
can therefore use symbolic identifiers rather than numeric constants to
identify the messages to be retrieved from the message catalog.
If the -m option is specified with the -e option and an h argu‐
ment, the header file also contains macros that define symbolic
identifiers for default message strings. A call to the catgets()
function or execution of the dspmsg command in a program should
include a default message string to be printed if a message cat‐
alog cannot be found or opened for the locale in which the pro‐
gram is running. When the catname_msg.h file includes macros for
default message strings, program source code can include an
identifier for the default message string in the catgets() call
or in an execution call for the dspmsg utility. This practice
helps prevent unintentional inconsistencies between a message
string in the message source file and the same string specified
in program calls. Create an include file, similar to cat‐
name_msg.h, but for use in scripts rather than programs. If -e
sh is specified, the include file is named catname_msg.sh and
can be included in a script that executes in the POSIX, Bourne,
or Korn shell. If -e csh is specified, the include file is named
catname_msg.csh and can be included in a script that executes in
the C shell.
Include files for scripts define variables only for the default
message strings to be displayed when a catalog is not found or
cannot be opened. (Unlike the catgets() function, the dspmsg
command is enhanced to use the symbolic set and message identi‐
fiers stored in the catalog by the -S option.)
See gencat(1) for a description of fundamental rules that govern the
format of a message source file. The only difference between gencat
and mkcatdefs is that with gencat you must input a number to identify
each message set and message, while mkcatdefs accepts either a number
or a symbolic name. If the -S option is included on the mkcatdefs com‐
mand line, an additional message set is included in the input to the
gencat command. This set includes information that allows instances of
the dspmsg command to retrieve messages from a catalog by using symbols
rather than numbers. (The catgets() function, due to constraints in the
XSH standard, uses numeric constant identifiers at run time to retrieve
messages from a message catalog.)
The mkcatdefs program sends message source data to standard output.
This output is suitable as input to the gencat program. You can use
the right angle bracket (>) character to write the preprocessed message
source code to a file, and then use this file as input to the gencat
command. See EXAMPLES for an illustration of this technique.
Each message set and message in program source code must have a unique
number or symbolic name. You can enable use of these symbolic identi‐
fiers in a program by including them in the message source file input
to the mkcatdefs command. Symbolic identifiers can contain English let‐
ters, digits, and underscores; however, the first character cannot be a
digit or an underscore. The mkcatdefs command converts symbolic names
specified in the message source file to numeric constants. One
restriction is that mkcatdefs does not convert symbolic names included
in a $delset command. Therefore, if your message source file contains
$delset commands to delete message sets, those commands must identify
the sets to be deleted by their numeric constant identifiers.
The mkcatdefs program is designed to create new message catalogs, not
to change existing ones incrementally. Thus, the program's first oper‐
ation on each set is to delete it, in case the catalog contains a set
with that number. The sets specified in source_file are assigned num‐
bers in ascending order, starting at 1. Within each set, messages are
also assigned numbers in ascending order, starting at 1. If you
explicitly assign a message to a number in your source_file, mkcatdefs
continues its ascending series with that number.
You can use the runcat command rather than the mkcatdefs command when
processing a message source file that contains symbolic identifiers for
message sets and messages. The runcat command automatically sends the
message source file through the mkcatdefs command and pipes the files
to the gencat command. Note, however, that the runcat command supports
only the default behavior of the mkcatdefs command; that is, runcat
cannot implement any of the operations supported by options on the
mkcatdefs command line.
RESTRICTIONS
Symbolic identifiers for message sets, messages, and default message
strings are an ease-of-maintenance feature for program source code and
shell scripts; however, symbolic references are a proprietary extension
to the XSH standard and might not be supported on all systems conform‐
ing to this standard.
Symbolic identifiers for message sets and messages provide ease of
maintenance by reducing the need to change references in program source
code when a catalog is revised. However, use of symbolic identifiers
does not insulate a program from run-time problems if it uses the cat‐
gets() function to retrieve messages from a catalog, the catalog is
revised, and the program is not recompiled with a new version of the
catname_msg.h file. That is because the XSH standard constrains the
run-time behavior of catgets() to the use of numeric identifiers, and
the numeric constants mapped to the symbolic identifiers can change
when a message catalog is rebuilt.
The mappings of numeric constants to symbols change if the following
kinds of revisions were made to the corresponding message source file
(or files) and a catalog is rebuilt: New message sets were added before
or between existing message sets. Message sets, other than the last
one in the file, were deleted. Existing message sets were rearranged.
New messages were added before or between existing messages in a given
message set. Messages, other than the last one, in a message set were
deleted. Existing messages were rearranged within a message set. The
message catalog was built from multiple message source files and the
order in which these files were specified on the mkcatdefs command line
was changed.
Therefore, if these kinds of changes were made to message source code
and a catalog was rebuilt, programs must be recompiled with a version
of catname_msg.h that was generated from the revised message source
file or files.
If care is taken to maintain the ordinal position of existing message
sets and messages when the message source file is changed (assuming, of
course, that program source code is not changed to refer to any new or
deleted message sets and messages), recompilation with a revised ver‐
sion of catname_msg.h is not necessary.
Programs that execute a dspmsg command (rather than call the cat*()
functions) to access a catalog can achieve complete independence from
changes in numeric constant identifiers at run time. This is also true
for scripts, which must access a message catalog by using a dspmsg com‐
mand. To achieve this independence, the following conditions must be
met: The -S must be included on the mkcatdefs command line. The -S, -s
set_symbol, and message_symbol arguments must be included in the dspmsg
command line.
Symbolic names for message sets and messages must be unique across all
message sets included in the catalog. By implication, this also means
that these symbolic names must be unique across all message source
files specified as input to the mkcatdefs command.
See the EXAMPLES section for an illustration of techniques that provide
insulation from changes in how numeric constants are mapped to symbolic
identifiers for message sets and messages.
EXAMPLES
The following example shows a message source file that contains one
message set and uses a mix of symbolic and numeric identifiers for mes‐
sages:
$quote " Use a double quotation mark to delimit message text
$set MSFAC Message Facility - symbolic identifiers
SYM_FORM "Symbolic identifiers can contain only letters \ and
digits and the _ (underscore character)\n" 5 "You can mix sym‐
bolic identifiers and numbers \n" $quote MSG_H Remember to
include the "_msg.h" file in your program\n
In the preceding example, the $quote command sets the quote
character to " (double quote), then disables it before the last
message, which contains double quotes.
When you process the file with mkcatdefs, the modified source is
written to standard output. Standard output can either be redi‐
rected to a file using the > redirection symbol or piped to gen‐
cat. Assume that the preceding file is named symb.src. It can
be processed with mkcatdefs as follows: $ mkcatdefs symb
symb.src >symb.msg
The symb.msg file contains the following preprocessed message
source code:
$quote " Use a double quotation mark to delimit message text
$delset 1 $set 1 1 "Symbolic identifiers can contain only let‐
ters \ and digits and the _ (underscore character)\n" 5 "You can
mix symbolic identifiers and numbers \n" $quote 6 Remember to
include the "_msg.h" file in your program\n
Note that the assigned message numbers are noncontiguous because
the symb.src file contained a specific number. The mkcatdefs
program always assigns the previous number plus 1 to the next
symbolic identifier.
The generated symb_msg.h file contains the following:
#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 MSG_H 6 #endif
Note that mkcatdefs also created the symbol MF_SYMB by prepend‐
ing MF_ to catname using uppercase letters. The mkcatdefs pro‐
gram assumes that the name of the generated catalog should be
catname.cat, and generates this symbol for your use with the
catopen function.
Because this include file contains include statements for lim‐
its.h and nl_types.h, you do not need to explicitly include
these files in your application program. (The nl_types.h header
file defines special data types required by the message facility
routines.) The following set of examples shows how to enable
and use symbolic identifiers for sets, messages, and default
message strings:
The message source file used for this set of examples contains
the following lines:
$quote " $set INFO GREET "Welcome to the Fact Finder program!\n"
BYE "Good-bye. Please come again.\n" ENTER "Please enter the
type of product \ you are interested in: " $set RESULTS NADA
"Sorry, we have no information on that \ kind of product."
FOUND "The following products were found." $set PROBLEMS SERV‐
CONN "Cannot connect to server. Try again later." BUSYDAY
"Still searching. Please wait..."
The following command creates a message catalog that includes
symbolic information as well as a file that can be executed in a
POSIX, Bourne, or Korn shell script to define symbolic identi‐
fiers for default message strings: % mkcatdefs-S -m -e sh PFF
PFF.src -h | gencat ./PFF.cat mkcatdefs: PFF_msg.sh created
The following command creates an include file for use in program
source code, as well as a copy of the preprocessed source code
that was input directly to the gencat command in the preceding
example: % mkcatdefs-S -m -e h PFF PFF.src > PFF.msg mkcatdefs:
PFF_msg.h created
The following commands show what is included in the % cat
PFF_msg.sh
# # Default messages generated from PFF.src # DEF_GREET='Welcome
to the Product Fact Finder program!\n' DEF_BYE='Good-bye.
Please come again.\n' DEF_ENTER='Please enter the type of prod‐
uct you are interested in: ' DEF_NADA='Sorry, we have no infor‐
mation on that kind of product.' DEF_FOUND='The following prod‐
ucts were found.' DEF_SERVCONN='Cannot connect to server. Try
again later.\n' DEF_BUSYDAY='Still searching. Please wait...\n'
% % cat PFF_msg.h #ifndef _H_PFF_MSG #define _H_PFF_MSG #include
<limits.h> #include <nl_types.h> #define MF_PFF "PFF.cat"
/* The following was generated from PFF.src. */
/* definitions for set INFO */ #define INFO 1
#define GREET 1 #define BYE 2 #define ENTER 3
/* definitions for set RESULTS */ #define RESULTS 2
#define NADA 1 #define FOUND 2
/* definitions for set PROBLEMS */ #define PROBLEMS 3
#define SERVCONN 1 #define BUSYDAY 2
/* Default messages generated from PFF.src */
#define DEF_GREET "Welcome to the Product Fact Finder pro‐
gram!\n" #define DEF_BYE "Good-bye. Please come again.\n"
#define DEF_ENTER "Please enter the type of product \ you
are interested in: " #define DEF_NADA "Sorry, we have no
information on that \ kind of product." #define DEF_FOUND
"The following products were found." #define DEF_SERVCONN
"Cannot connect to server. Try again later.\n" #define DEF_BUSY‐
DAY "Still searching. Please wait...\n" #endif % % dspcat
PFF.cat 1 : 1 Welcome to the Product Fact Finder program!
1 : 2 Good-bye. Please come again.
1 : 3 Please enter the type of product you are interested in: 2
: 1 Sorry, we have no information on that kind of product. 2 :
2 The following products were found. 3 : 1 Cannot connect to
server. Try again later.
3 : 2 Still searching. Please wait... 4 : 1 GREET BYE ENTER 4 :
2 NADA FOUND 4 : 3 SERVCONN BUSYDAY 4 : 4 $@ INFO RESULTS PROB‐
LEMS
In this catalog, there are three message sets defined from those
specified in the message source file. The fourth message set is
added by the mkcatdefs command to provide mappings of symbolic
names to corresponding numbers. All but the last message number
in the fourth set correspond to the set numbers in the first
three sets. All but the last “message” in the fourth set is an
ordinal listing of the symbolic names for messages in a particu‐
lar set. The last “message” in the fourth set begins with a
magic string ($@), followed by an ordinal listing of symbolic
names for the first three sets. For example, the symbolic name
for the first message set is INFO, which contains three messages
(specified on lines 1 : 1, 1 : 2, and 1 : 3) whose symbolic
names are GREET, BYE, and ENTER, respectively. When displaying
messages from this catalog, the dspmsg command can use either
symbolic names or numbers as set and message identifiers. For
example: % dspmsg -s 1 PFF.cat 1 Welcome to the Product Fact
Finder program! % dspmsg -S -s INFO PFF.cat GREET Welcome to
the Product Fact Finder program!
The following script illustrates the use of symbols for message
sets, messages, and default message strings. By default, the
dspmsg command and cat*() functions search for message catalogs
first in the current directory and then in the appropriate
locale directory subordinate to /usr/lib/nls/msg:
#! /bin/sh # # test_dspmsg.sh
.
.
. . ./PFF_msg.sh
.
.
. dspmsg -S -s INFO PFF.cat GREET "${DEF_GREET}"
.
.
.
The dspmsg command in this script displays the message string
whether or not the message catalog is found as long as the
PFF_msg.sh file is installed with the script. For the following
example, assume that the PFF.cat file is located only in the
current directory: % ./test_dspmsg.sh Welcome to the Product
Fact Finder program! % mv PFF.cat hide_PFF.cat %
./test_dspmsg.sh Welcome to the Product Fact Finder program!
A default message string is typically English text, whereas a
translated message is displayed if a translated version of the
catalog is available for the locale. The advantage of using sym‐
bols for default message strings is to ensure that only one copy
of the original message strings needs to be maintained. When
message strings must be maintained both in message source files,
in calls to catgets(), and in dspmsg commands, inconsistencies
are likely to develop between different instances of what is
intended to be the same string.
A message can be displayed as the message string alone or as the
message string preceded by its message identifier. See dspmsg(1)
for examples of using the dspmsg command to display message
strings preceded by their identifiers.
SEE ALSO
Commands: dspcat(1), dspmsg(1), gencat(1), runcat(1)
Functions: catclose(3), catgets(3), catopen(3)
Writing Software for the International Market
mkcatdefs(1)