 |
Index for
Section 1 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
mkcatdefs(1)
NAME
mkcatdefs - Preprocesses a message source file
SYNOPSIS
mkcatdefs [-hS] [-m [-p prefix] [-e extension]] catname source_file...
OPTIONS
-e extension
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:
h Generate macros into a catname_msg.h file. (Default)
sh 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.
csh Generate variable assignments into a catname_msg.csh file.
This file can be included by C shell scripts for use with the
dspmsg command.
-h 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.)
-m Causes the output header file or shell script include file to contain
default message strings and their symbolic identifiers.
-p prefix
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.
-S 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.
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 symbolic
identifiers to corresponding numeric constants in the .cat 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.
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 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.
EXAMPLES
1. 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.
2. 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.)
3. 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 .sh 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 .sh, .h, and
message catalog files created from these commands:
% 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.
SEE ALSO
Commands: dspcat(1), dspmsg(1), gencat(1), runcat(1)
Functions: catclose(3), catgets(3), catopen(3)
Writing Software for the International Market
|
Index for
Section 1 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|