dspmsg(1)dspmsg(1)NAMEdspmsg - Displays a selected message from a message catalog
SYNOPSISdspmsg [[-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 vari‐
able.
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 mes‐
sage 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 pre‐
processed 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 symbolic 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. Sym‐
bolic names for default message strings are supported through
different kinds of include files that define macros (for pro‐
grams) 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 inser‐
tion arguments.
DESCRIPTION
The dspmsg utility displays a particular message from a message cata‐
log. 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 envi‐
ronment 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 cat‐
alog, 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 argu‐
ments 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 messages 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. Sym‐
bolic 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 argu‐
ment. The following example is from a POSIX shell script:
. ./store_msg.sh dspmsg-S -s NOSALE store.cat SOLDOUT "${STORE_SOLD‐
OUT}"
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 mes‐
sage 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 envi‐
ronment 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 environment
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 reference
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
SOLDOUT: Sorry, that item is no longer in stock.
Of these examples, the first two illustrate the default format for mes‐
sage 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* environ‐
ment 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 identi‐
fiers. 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 envi‐
ronment 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 variables
must be defined to enable display of identifiers with the -E option and
can be defined to override the default format used for identifiers dis‐
played through the -e option. The dspmsg utility first checks the cat‐
alog-specific environment variable and then, if the catalog-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 mes‐
sage catalog name without the file extension and the prefix. (The pre‐
fix 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 sym‐
bolic 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 iden‐
tifier. 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 follow‐
ing 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
specify the format for message identifiers. These identifiers are dis‐
played 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 identi‐
fier:
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 loa‐
dit 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)