|HP-UX Reference > D
HP-UX 11i Version 3: February 2007
dspmsg — display a selected message from a message catalog
dspmsg [-e | -E] [-s set_number] catalog_name message_number ['default_string' [argument ... ]]
The dspmsg command displays a particular message from a message catalog. The display may include 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. A message identifier consists of one of more of the following items: the catalog name, the set number, and the message number. See the subsection Displaying Message Identifiers with Messages below for more information about these environment variables.
The dspmsg command recognizes the following options:
The dspmsg command recognizes the following operands:
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 dspmsg 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, dspmsg displays nothing if the message cannot be retrieved from the catalog.
The following 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 dspmsg 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 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, dspmsg can specify a symbolic name for the default_string argument. In the following example the file containing default message strings created by mkcatdefs is first sourced in the POSIX shell. Then the dspmsg command is invoked using the name of one of these variables as the default message string.
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 command displays a message by itself or preceded by its message identifier. Display of message identifiers is enabled by one of the following:
Display of message identifiers is disabled under any of the following conditions:
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 identifiers if you use the -e option and do not set one of the CAT_MIDFMT* environment variables. The second example illustrates what happens when you use the -E option and set the CAT_MIDFMT to "%C %M: ", that is, the catalog name followed by a space followed by the message number.
The following subsections discuss the CAT_MIDSET* and CAT_MIDFMT* environment variables in more detail.
Using the CAT_MIDSET* Environment Variables
The CAT_MIDSET_catname and CAT_MIDSET environment variables are used to control how to activate the message identifier feature. You can use them to specify a space-separated 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 identifiers. If you set one of these variables to "", this will disable display of message identifiers for all sets in the message catalog.
The dspmsg command checks for the CAT_MIDSET_catname and CAT_MIDSET environment variables only when the -e option is specified. When this option is specified, dspmsg first determines if the CAT_MIDSET_catname environment variable is set. If it is set, and message_number is in one of the sets specified by the variable, dspmsg precedes the specified message with its message identifier. If a catalog-specific environment variable is not set, dspmsg searches for the CAT_MIDSET environment variable and uses its setting. If neither environment variable is set, dspmsg 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 dspmsg -e to confine display of message identifiers to those kinds of messages.
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. These variables can be defined to override the default format used for identifiers displayed through the -e option. The dspmsg command 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 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".
LANG provides a default value for the internationalization variables that are unset or null. If LANG is unset or null, it defaults to C (see lang(5)).
LC_ALL, when set to a non-empty string value, overrides the values of all other internationalization variables.
LC_MESSAGES determines the language in which messages are displayed.
NLSPATH determines the path to be used for searching the specified message catalog file. It affects how the internationalization variables are being used in locating the desired message catalog.
To display message number 2 in set number 1 of test.cat, enter:
dspmsg test.cat -s 1 2 'Default message.'
If the message does not exist in the set, the string "Default Message" will be displayed.