mkcatdefs - Preprocesses a message source file
mkcatdefs [-hS] [-m [-p prefix] [-e extension]] catname
source_file...
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
generation of the catname_msg.h file if -m is not specified
or -m is specified 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 generated but contains
only the macros that define symbolic identifiers
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 message string.
Explicitly specifying a catalog-specific prefix is
recommended if programs and scripts access multiple
message catalogs. Otherwise, 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 symbolic 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 command. Otherwise, only numeric
set and message identifiers are included in the
output sent to the gencat command. See DESCRIPTION
and EXAMPLES for information on how these symbolic
identifiers are used at run time.
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 symbolic identifiers
to corresponding numeric constants in the file.
Program 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 argument, 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 catalog cannot be found or
opened for the locale in which the program 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 catname_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 identifiers
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
command 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 identifiers in a program by including
them in the message source file input to the mkcatdefs
command. Symbolic identifiers can contain English letters,
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 operation 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
numbers 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.
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 conforming
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 catgets()
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 version
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 command.
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.
The following example shows a message source file that
contains one message set and uses a mix of symbolic and
numeric identifiers for messages:
$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 symbolic
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 redirected to a file
using the > redirection symbol or piped to gencat.
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 letters \ 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 prepending MF_ to catname using uppercase letters.
The mkcatdefs program 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 limits.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 SERVCONN "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 identifiers
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 product you are
interested in: ' DEF_NADA='Sorry, we have no information
on that kind of product.' DEF_FOUND='The
following products 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 program!\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_BUSYDAY
"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 PROBLEMS
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 particular
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 symbols 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.
Commands: dspcat(1), dspmsg(1), gencat(1), runcat(1)
Functions: catclose(3), catgets(3), catopen(3)
Writing Software for the International Market
mkcatdefs(1)
[ Back ] |
