dspmsg - Displays a selected message from a message catalog
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...]]
Specifies that message identifiers be displayed along with
message strings, but only for those message sets specified
by the CAT_MIDSET_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.
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. 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.
The dspmsg utility displays a particular message from a
message catalog. The display includes a message identifier,
depending on the presence of the -e or -E option and
settings for the CAT_MIDSET_catname, CAT_MIDSET, and
CAT_MIDFMT environment variables. See "Displaying Message
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 catalog 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 [Toc] [Back]
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 message_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 unintentional 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. 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 [Toc] [Back]
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 [Toc] [Back]
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 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 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 message_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 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 displayed
through the -e option. The dspmsg utility first
checks the catalog-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 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
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 specify 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 command 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.
Commands: dspcat(1), gencat(1), mkcatdefs(1)
Functions: catclose(3), catgets(3), catopen(3)
Writing Software for the International Market
dspmsg(1)
[ Back ] |
