dspmsg man page on Tru64

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
Tru64 logo
[printable version]

dspmsg(1)							     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
       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)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net