dspmsg(1) General Commands Manual dspmsg(1)
NAME
dspmsg - Displays a selected message from a message catalog
SYNOPSIS
dspmsg [[-e | -E]] [-s set_number] catalog_name message_number ['default_string'[argument...]]
dspmsg [[-e | -E]] S [-s set_symbol] catalog_name message_symbol [default_string[argument...]]
OPTIONS
Specifies that message identifiers be displayed along with message strings, but only for those message sets specified by the CAT_MID-
SET_catname or CAT_MIDSET environment variable.
You can override the default format of the message identifier by defining the CAT_MIDFMT_catname or CAT_MIDFMT environment variable.
See DESCRIPTION for more information about using this option and setting the CAT_MID* environment variables. Specifies that the
message identifier is displayed for messages in all message sets under control of the CAT_MIDFMT environment variable.
In other words, the CAT_MIDSET* environment variables have no effect when you use the -E option. However, you must explicitly
define one of the CAT_MIDFMT* environment variables to display the message identifier. In this case, if the message catalog is not
found and the default_string argument is omitted, the message identifier is displayed by itself.
See DESCRIPTION for more information about using this option and setting the CAT_MIDFMT* environment variables. Specifies the set
number or symbolic name. By default, the utility searches for messages in the first message set. Specifies the use of symbolic
names to identify message sets and their messages. These symbolic names can be used only if the message catalog supports them. This
means that the source files used to create the message catalog included these symbolic names and were preprocessed by a mkcatdefs -S
command before being processed by a gencat command.
OPERANDS
Specifies the name of a message catalog. By default, the dspmsg utility searches for the catalog in the current directory and then in the
set of directories specified by the NLSPATH environment variable. For more information about NLSPATH, see catopen(3). Specifies the sym-
bolic name or number of the message.
If the -s option is omitted, the dspmsg utility searches for the message only in the first message set in the catalog. This is true
even when the message is identified by its unique symbolic name. Specifies the message for the command to display if the dspmsg
utility cannot find a message with the specified number in the catalog. If the message includes the %n$s notation for message
inserts, either enclose the default message in single quotes or escape the $ character in the insertion notation (%n$s).
A symbolic name can be substituted for the string itself. Symbolic names for default message strings are supported through different
kinds of include files that define macros (for programs) and variables (for shell scripts). The source files from which the message
catalog was created must be preprocessed by a mkcatdefs command with the -m option and (for scripts) the -e option to produce the
include file used by the program or script. Specifies arguments (up to 10) to be inserted in the catalog message or default message
if it contains either the %s or the %n$s printf() conversion specifications. You must include the default_string argument in order
to specify message insertion arguments.
DESCRIPTION
The dspmsg utility displays a particular message from a message catalog. The display includes a message identifier, depending on the pres-
ence of the -e or -E option and settings for the CAT_MIDSET_catname, CAT_MIDSET, and CAT_MIDFMT environment variables. See "Displaying Mes-
sage Identifiers with Messages" for more information about these environment variables.
You must specify the message catalog (catalog_name) and the message (message_*). You must also specify the message set (set_*) if the cata-
log has more than one message set and the specified message is not in the first set.
The dspmsg utility displays the default_string value if the specified message is not found in the catalog or the catalog cannot be found or
opened. Usually, default_string is identical to the message in the catalog, except for the language in which the text is printed. If you do
not specify default_string, the dspmsg utility displays nothing if the message cannot be retrieved from the catalog. The one exception to
this rule is if you omit the default_string operand, specify the -E option, and the CAT_MIDFMT environment variable is defined. In this
case, the utility displays the message identifier by itself.
The following simple example displays message number 2 in set 3 of test.cat: dspmsg -s 3 store.cat 2 'Sorry, that item is no longer in
stock.'
If the dspmsg utility does not find message number 2 in set number 3 of store.cat (or cannot find or open store.cat), the utility displays
the specified string (Sorry, that item is no longer in stock.)
The following sections discuss the use of symbolic names on the command line and how to display message identifiers along with message
strings.
Using Symbolic Names for Message Sets and Messages
If the message catalog supports the use of symbolic names for sets and messages, you can specify the -S option to use the set_name and mes-
sage_name arguments in place of the set_number and message_number arguments in a dspmsg command. See mkcatdefs(1) for information about
building a message catalog to support symbolic names.
There are two advantages to identifying sets and messages by names rather than numbers: Symbolic identifiers are less subject to uninten-
tional revision when a catalog is revised.
Number identifiers represent the ordinal positions of sets within the source files for a catalog and the ordinal position of mes-
sages within sets. To ensure that the set and message numbers by which a message is retrieved do not change when a catalog is
rebuilt, catalog maintainers must not change the order of sets and messages when adding and deleting them. Symbolic names are more
meaningful to programmers and more likely to be remembered.
For example, the following command retrieves the SOLDOUT message from the NOSALE message set:
dspmsg -S -s NOSALE store.cat SOLDOUT 'Sorry, that item is no longer in stock.'
Using Symbolic Names for Default Message Strings
When the mkcatdefs utility preprocesses a message source file, it can create a file that defines macros or variables for default message
strings. When this file is included in a shell script or program, the dspmsg command can specify a symbolic name for the default_string
argument. The following example is from a POSIX shell script:
. ./store_msg.sh dspmsg -S -s NOSALE store.cat SOLDOUT "${STORE_SOLDOUT}"
The store_msg.sh file was created by the mkcatdefs utility and defines the STORE_SOLDOUT variable to be the string "Sorry, that item is no
longer in stock." The mkcatdefs utility created the variable name by prepending the prefix (STORE_) that was specified with the -p option
to the symbolic name for the message (SOLDOUT). See mkcatdefs(1) for more information about creating include files that define symbolic
names for default message strings.
Displaying Message Identifiers with Messages
The dspmsg utility displays a message by itself or preceded by its message identifier. Display of message identifiers is enabled by one of
the following: The -e option, which must be combined with a setting for the CAT_MIDSET_catname or CAT_MIDSET environment variable and can
be combined with a setting of the CAT_MIDFMT environment variable. The -E option, which must be combined with a setting for the CAT_MIDFMT
environment variable and is not affected by settings of the CAT_MIDSET* environment variables.
Display of message identifiers is disabled under any of the following conditions: For -e: The CAT_MIDSET_catname and CAT_MIDSET environment
variables are not defined. The value of the CAT_MIDSET_catname or (if that variable is not defined) the value of the CAT_MIDSET environ-
ment variable does not include the message set containing the message. The value of the CAT_MIDSET_catname or (if that variable is not
set) the value of the CAT_MIDSET environment variable is set to "". For -E:
The CAT_MIDFMT_catname and CAT_MIDFMTenvironment variables are not defined. For -e and -E:
The value of the CAT_MIDFMT_catname or (if that variable is not defined) the value of the CAT_MIDFMT environment variable is set to
"".
Message identifiers are made up of some combination of the catalog name, set identifier, message identifier, and delimiting characters.
Following are some examples of message identifiers you can display by using the options and environment variables discussed in this refer-
ence page: store/3/2: Sorry, that item is no longer in stock.
Number identifiers for the message set and message are displayed if the catalog does not include support for symbolic names.
store/NOSALE/SOLDOUT: Sorry, that item is no longer in stock. NOSALE_SOLDOUT: Sorry, that item is no longer in stock. store SOLD-
OUT: Sorry, that item is no longer in stock.
Of these examples, the first two illustrate the default format for message identifiers if you use the -e option and do not set one of the
CAT_MIDFMT* environment variables.
The following sections discuss the CAT_MIDSET* and CAT_MIDSET* environment variables in more detail.
Using the CAT_MIDSET* Environment Variables
The CAT_MIDSET_catname and CAT_MIDSET environment variables specify a space-separated list of identifiers (numbers or symbolic names) for
the sets containing messages that will be displayed with message identifiers. For example:
"NOSALE ERRORS" "3 4" "3 ERRORS" "" (Disables display of message identifiers)
The dspmsg utility checks for the CAT_MIDSET_catname and CAT_MIDSET environment variables only when the -e option is specified. When the -e
option is specified, the dspmsg utility first determines if the CAT_MIDSET_catname environment variable is set. If it is set, and mes-
sage_number or message_name is in one of the sets specified by the variable, the utility precedes the specified message with its message
identifier. If a catalog-specific environment variable is not set, the utility searches for the CAT_MIDSET environment variable and uses
its setting. If neither environment variable is set, the utility does not display message identifiers.
Usually, application programmers want to display message identifiers only for messages that are warning or error conditions. If a message
catalog is well designed, messages associated with these conditions reside in different sets from those containing informational messages
or background text strings. You can set the CAT_MIDSET_catname environment variable to list only the message sets that contain warnings or
errors and then use the dspmsg -e command to confine display of message identifiers to those kinds of messages.
The CAT_MIDSET environment variable is useful when catalogs all support symbolic names and the symbolic names for sets containing certain
kinds of messages are consistent across catalogs. For example, if you want message identifiers to be displayed only for errors, and error
messages in all message catalogs being accessed are in a message set named ERROR, you can set CAT_MIDSET to "ERROR" rather than setting
multiple catalog-specific environment variables.
Using the CAT_MIDFMT* Environment Variables
The CAT_MIDFMT_catname and CAT_MIDFMT environment variables control the format of the message identifier. One of these environment vari-
ables must be defined to enable display of identifiers with the -E option and can be defined to override the default format used for iden-
tifiers displayed through the -e option. The dspmsg utility first checks the catalog-specific environment variable and then, if the cata-
log-specific version is not found, checks for the CAT_MIDFMT environment variable.
The value of the CAT_MIDFMT* environment variables can include one or more of the following substitution directives (in any order): The
message catalog name without the file extension and the prefix. (The prefix is prepended to the catalog name by the mkcatdefs utility for
use by programmers as a catalog handle.) The identifier for the message set. This is the symbolic name if the catalog was built to support
symbolic names; otherwise, it is the numeric constant identifier. The message identifier. This is the symbolic name if the catalog was
built to support symbolic names; otherwise, it is the numeric constant identifier. If specified first in the format string, the default
format ("%C%/%S%/%M: "). If not specfied first in the format string, the %D substitution directive is ignored.
The format can include additional ASCII characters, such as the space or colon, as delimiters between segments of the identifier. However,
you cannot include the percent (%) character as a delimiter because of its special meaning to the shell.
Following are some example formats and resulting message identifiers and strings. Assume for these examples that the catalog name is du,
the message set identifier is ERROR, the message identifier is NOMEM, and the message string is "Out of memory". "%C/%S/%M: "
du/ERROR/NOMEM: Out of memory "%D"
du/ERROR/NOMEM: Out of memory "%C-%M: "
du-NOMEM: Out of memory "%C %M: "
du NOMEM: Out of memory
EXAMPLES
The examples in this section are from a script named loadit, which installs or deletes software subsets. This script contains the following
lines, which execute before any of the dspmsg commands that the script contains:
#!/sbin/sh
CAT_MIDFMT="%C %M" export CAT_MIDFMT
. ./loadit_msg.sh
The source file used to create the loadit.cat file, which is the only message catalog used by the loadit script, was preprocessed by the
mkcatdefs utility to include symbolic name support for message sets and messages. The loadit_msg.h file was created from the same message
source file by the mkcatdefs utility to define symbolic names for default message strings. The script sets the CAT_MIDFMT variable to spec-
ify the format for message identifiers. These identifiers are displayed only when a dspmsg command includes the -E option.
The following dspmsg example from the loadit script uses symbolic names to specify the message set, message, and default message string.
The -E option specifies that the message be preceded by the message identifier:
dspmsg -E -S
loadit.cat -s ERROR
ARGS_BAD_SWITCH
"$DEF_ARGS_BAD_SWITCH"
The following example shows how the message is displayed:
# loadit -D PFFBASE301 loadit ARGS_BAD_SWITCH: Unreached in Args()
The same display would result if the dspmsg command used numbers to identify the message set and message:
dspmsg -E
loadit.cat -s 3
28
"$DEF_ARGS_BAD_SWITCH"
However, if the loadit.cat file had not been built with support for symbolic set and message identifiers, this version of the dspmsg com-
mand would result in the following display: # loadit -D PFFBASE301 loadit 28: Unreached in Args()
In this case, the message identifier might not be unique because the set substitution directive (%S) was omitted from the value of the
CAT_MIDFMT variable.
The following dspmsg example from the loadit script also uses symbolic names to specify the message set, message, and default message
string. The command does not include the -E option, so the message identifier is not displayed. This message includes a %s substitution
directive, so an argument is specified after the default message string:
for _S in $NOTTHERE; do
dspmsg -S
loadit.cat -s ERROR
DELETE_CANNOT_DELETE
"$DEF_DELETE_CANNOT_DELETE" $_S done
The following example shows how this message is displayed:
# loadit -d PFFBASE301 PFFOPT301 PFFOPT301 is not installed and cannot be deleted.
SEE ALSO
Commands: dspcat(1), gencat(1), mkcatdefs(1)
Functions: catclose(3), catgets(3), catopen(3)
Writing Software for the International Market
dspmsg(1)