 |
Index for
Section 1 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
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
-e 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.
-E 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.
-s set_*
Specifies the set number or symbolic name. By default, the utility
searches for messages in the first message set.
-S 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
catalog_name
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).
message_*
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.
default_string
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.
argument ...
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 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
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
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 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):
%C 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.)
%S 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.
%M The message identifier. This is the symbolic name if the catalog
was built to support symbolic names; otherwise, it is the numeric
constant identifier.
%D 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 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.
SEE ALSO
Commands: dspcat(1), gencat(1), mkcatdefs(1)
Functions: catclose(3), catgets(3), catopen(3)
Writing Software for the International Market
|
Index for
Section 1 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|