dspmsg(1)dspmsg(1)NAMEdspmsg - display a selected message from a message catalog
SYNOPSIS
| set_number] catalog_name message_number ['default_string' [argument
... ]]
DESCRIPTION
The command displays a particular message from a message catalog. The
display may include a message identifier, depending on the presence of
the or option and settings for the and environment variables. A mes‐
sage identifier consists of one of more of the following items: the
catalog name, the set number, and the message number. See the subsec‐
tion below for more information about these environment variables.
Options
The command recognizes the following options:
Specifies that message identifiers be displayed along with mes‐
sage
strings, but only for those message sets speci‐
fied by the or environment variables.
You can override the default format of the mes‐
sage identifier by defining the or environment
variable. See the subsection for more informa‐
tion.
Specifies that the message identifier is displayed for messages
in all
message sets under control of the environment
variable. If you use this option, the environ‐
ment variables have no effect. However, you must
explicitly define one of the environment vari‐
ables to display the message identifiers. When
you use this option, if the message catalog is
not found and the default_string argument is
omitted, the message identifier is displayed by
itself. For example, will be displayed if the
catalog_name is and the message_number is and the
set_number is
Specifies the set number.
If not specified, searches for messages in the
first message set.
Operands
The command recognizes the following operands:
catalog_name Specifies the name of a message catalog. By
default searches for the catalog in the set of
directories specified by the environment variable
and then in the current directory. The search
can be disabled by prefixing a path name to the
catalog. For more information about see envi‐
ron(5).
message_number Specifies the message number in the specified
set.
If the option is omitted, only searches for the
message in the first message set in the catalog.
default_string Specifies the message for the command to display
if cannot find a message with the specified num‐
ber in the catalog. If the message includes the
notation for message inserts, either enclose the
default message in single quotes or escape the
character in the insertion notation
argument ... Specifies arguments (up to 10) to be inserted in
the catalog message or default message if it con‐
tains either the or the conversion specifica‐
tions. You must include the default_string argu‐
ment in order to specify message insertion argu‐
ments.
You must specify the message catalog (catalog_name) and the message
(message_number). You must also specify the message set (set_number)
if the catalog has more than one message set and the specified message
is not in the first set.
The command 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, displays nothing if the message cannot be
retrieved from the catalog.
The following example displays message number 2 in set 3 of test.cat:
If does not find the specified message in the catalog or cannot find or
open the catalog, it displays the string "Sorry, that item is no longer
in stock."
Using Symbolic Names for Default Message Strings
When the 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, can specify a
symbolic name for the default_string argument. In the following exam‐
ple the file containing default message strings created by is first
sourced in the POSIX shell. Then the command is invoked using the name
of one of these variables as the default message string.
dspmsg-s 3 store.cat 2 "${STORE_SOLDOUT}"
The store_msg.sh file was created by the utility and defines the
STORE_SOLDOUT variable to be the string "Sorry, that item is no longer
in stock." The utility created the variable name by prepending the
prefix (STORE_) that was specified with the 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 command displays a message by itself or preceded by its message
identifier. Display of message identifiers is enabled by one of the
following:
1) The option, which must be combined with a setting for the or
environment variable and can be combined with a setting of
the environment variable. The catname is the name of the
message catalog file in uppercase and without the ".cat"
extension. It overrides the environment variable, if
defined.
2) The option, which must be combined with a setting for the
environment variable and is not affected by settings of the
environment variables.
Display of message identifiers is disabled under any of the following
conditions:
1) For the option:
· The and environment variables are not defined.
· The value of the or (if that variable is not defined) the
value of the environment variable does not include the mes‐
sage set containing the message.
· The value of the or (if that variable is not set) the value
of the environment variable is set to "", that is, NULL.
2) For the option:
The and environment variables are not defined.
3) For the and options:
The value of the or (if that variable is not defined) the
value of the environment variable is set to "", that is,
NULL.
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 manpage:
·
·
The first example illustrates the default format for message identi‐
fiers if you use the option and do not set one of the environment vari‐
ables. The second example illustrates what happens when you use the
option and set the to "", that is, the catalog name followed by a space
followed by the message number.
The following subsections discuss the and environment variables in more
detail.
Using the CAT_MIDSET* Environment Variables
The and environment variables are used to control how to activate the
message identifier feature. You can use them to specify a space-sepa‐
rated list of numeric identifiers for the sets containing messages that
will be displayed with message identifiers. For example, if you set
one of these variables to "3 4", only messages in sets 3 and 4 will
have their message identfiers displayed. The messages in other sets in
the message catalog will be displayed without their message identi‐
fiers. If you set one of these variables to "", this will disable dis‐
play of message identifiers for all sets in the message catalog.
The command checks for the and environment variables only when the
option is specified. When this option is specified, first determines
if the environment variable is set. If it is set, and message_number
is in one of the sets specified by the variable, precedes the specified
message with its message identifier. If a catalog-specific environment
variable is not set, searches for the environment variable and uses its
setting. If neither environment variable is set, does not display mes‐
sage 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 environment variable to
list only the message sets that contain warnings or errors and then use
to confine display of message identifiers to those kinds of messages.
Using the CAT_MIDFMT* Environment Variables
The and environment variables control the format of the message identi‐
fier. One of these environment variables must be defined to enable
display of identifiers with the option. These variables can be defined
to override the default format used for identifiers displayed through
the option. The command first checks the catalog-specific environment
variable and then, if the catalog-specific version is not found, checks
for the environment variable.
The value of the environment variables can include one or more of the
following substitution directives (in any order):
The message catalog name without the file extension.
The identifier for the message set.
This is the numeric constant identifier.
The message identifier.
This is the numeric constant identifier.
The default format.
If specified first in the format string, the default format
(""). If not specified first in the format string, the
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 3, the message identifier is 2, and the
message string is "Out of memory".
· ""
du/3/2: Out of memory
· ""
du/3/2: Out of memory
· ""
du-2: Out of memory
· ""
du 2: Out of memory
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 messages are displayed.
determines the path to be used for searching the specified message cat‐
alog file. It affects how the internationalization variables are being
used in locating the desired message catalog.
EXAMPLES
To display message number 2 in set number 1 of test.cat, enter:
If the message does not exist in the set, the string "Default Message"
will be displayed.
AUTHOR
The command was developed by OSF and HP.
SEE ALSOdspcat(1), gencat(1), mkcatdefs(1), catclose(3C), catgets(3C),
catopen(3C).
dspmsg(1)
