unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



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

  -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 defin-
      ing the CAT_MIDFMT_catname or CAT_MIDFMT environment variable.

      See DESCRIPTION for more information about using this option and set-
      ting 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 identif-
      ier.  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 set-
      ting 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 mes-
      sage 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 mes-
      sage 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 (mes-
  sage_*). 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	mes-
  sage 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 mes-
  sages, 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 main-
       tainers 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 follow-
  ing:

    +  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	con-
  ditions:

    +  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	vari-
  able,	the utility precedes the specified message with	its message identif-
  ier. 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 dif-
  ferent 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 mes-
  sage 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	util-
	  ity 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	can-
  not 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	mes-
  sage 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	iden-
  tifiers. 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 iden-
  tify 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 sym-
  bolic	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 argu-
  ment 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