mkcatdefs(1)mkcatdefs(1)NAMEmkcatdefs - preprocess a message source file
SYNOPSIS
prefix] extension]] catname source_file...
DESCRIPTION
The command 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 command. The command
creates the catname.cat file accessed by the and functions and
by the utility.
· Create a catname_msg.h file that defines macros to map sym‐
bolic 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 identi‐
fiers rather than numeric constants to identify the messages
to be retrieved from the message catalog.
If the option is specified with the header file also contains
macros that define symbolic identifiers for default message
strings. A call to the function or execution of the 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 file
includes macros for default message strings, program source
code can include an identifier for the default message string
in the call or in an execution call for the 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 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 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.
See gencat(1) for a description of fundamental rules that govern the
format of a message source file. The only difference between and is
that with you must input a number to identify each message set and mes‐
sage, while accepts either a number or a symbolic name.
Options
If the 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 command.
Generate variable assignments into a
catname_msg.csh file. This file can be
included by C shell scripts for use with the
command.
Suppresses the generation of the
catname_msg.h file if is not specified or is
specified along with or
Suppresses the macros that map symbolic identi‐
fiers for messages and sets to numeric constants
if is specified either without the option or with
(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 iden‐
tifiers.
Specifies a prefix used in the identifier for a default mes‐
sage string. If the prefix is not specified with
the option, the string "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 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.
The command sends message source data to standard output. This output
is suitable as input to the 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 command.
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 command. Symbolic identifiers can contain English letters, dig‐
its, and underscores; however, the first character cannot be a digit or
an underscore. The command converts symbolic names specified in the
message source file to numeric constants. One restriction is that does
not convert symbolic names included in a command. Therefore, if your
message source file contains commands to delete message sets, those
commands must identify the sets to be deleted by their numeric constant
identifiers.
The program is designed to create new message catalogs, not to change
existing ones incrementally. 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,
continues its ascending series with that number.
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 func‐
tion 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 behav‐
ior of 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
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.
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 command.
See the section for an illustration of techniques that provide insula‐
tion from changes in how numeric constants are mapped to symbolic iden‐
tifiers for message sets and messages.
EXTERNAL INFLUENCES
Environment Variables
provides a default value for the internationalization variables that
are unset or null. If is unset or null, it defaults to (see lang(5)).
when set to a non-empty string value, overrides the values of all other
internationalization variables.
determines the language in which error messages are displayed.
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 symbolic identifiers and numbers \n"
$quote
MSG_H Remember to include the "_msg.h" file in your program\n
In this example, the 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 the modified source is written to stan‐
dard output. Standard output can either be redirected to a file using
the redirection symbol or piped to
Assume that the preceding file is named symb.src. It can be processed
with as follows:
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 Message Facility - symbolic identifiers
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 the specific message number 5. The program
always assigns the previous number plus 1 to the next symbolic identi‐
fier.
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"
/* 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 also created the symbol MF_SYMB by prepending MF_ to catname
using uppercase letters. The command assumes that the name of the gen‐
erated catalog should be catname.cat, and generates this symbol for
your use with the 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 mes‐
sage source file PFF.src 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.\n"
FOUND "The following products were found: "
$set PROBLEMS
SERVCONN "Cannot connect to server. Try again later.\n"
BUSYDAY "Still searching. Please wait...\n"
The following command creates a message catalog that includes a .sh
file that can be executed in a POSIX, Bourne, or Korn shell script to
define symbolic identifiers for default message strings:
mkcatdefs: PFF_msg.h is created.
mkcatdefs: PFF_msg.sh is 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 command in the preceding example:
mkcatdefs: PFF_msg.h is created
The following and 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.\n'
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"
/* 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
#endif
/* 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.\n"
#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...
In this catalog, there are three message sets defined from those speci‐
fied in the message source file. When displaying messages from this
catalog, the command uses numbers as set and message identifiers. For
example:
Welcome to the Product Fact Finder program!
The following script illustrates the use of symbols for default message
strings. By default, searches for message catalogs first in the appro‐
priate locale directory subordinate to /usr/lib/nls/msg and then in the
current directory:
#! /bin/sh
#
# test_dspmsg.sh
.
.
.
. ./PFF_msg.sh
.
.
.
dspmsg -s 1 PFF.cat 1 "${DEF_GREET}"
.
.
.
The command in this script displays the message string:
Welcome to the Product Fact Finder program!
A default message string is typically English text, whereas a trans‐
lated 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 main‐
tained both in message source files, in calls to and in 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 mes‐
sage string preceded by its message identifier. See dspmsg(1) for
examples of using the command to display message strings preceded by
their identifiers.
AUTHOR
The command was developed by OSF and HP.
SEE ALSOdspcat(1), dspmsg(1), gencat(1), catclose(3C), catgets(3C),
catopen(3C).
mkcatdefs(1)
