unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



mkcatdefs(1)							 mkcatdefs(1)



NAME

  mkcatdefs - Preprocesses a message source file

SYNOPSIS

  mkcatdefs [-hS] [-m [-p prefix] [-e extension]] catname source_file...

OPTIONS

  -e extension
      If the -m	option is also specified, identifies the type of include file
      to contain the default message strings and their symbolic	identifiers.
      The value	for extension can be one of the	following:

      h	      Generate macros into a catname_msg.h file. (Default)

      sh      Generate variable	assignments into a catname_msg.sh file.	 This
	      file can be included by POSIX, Bourne, and Korn shell scripts
	      for use with the dspmsg command.

      csh     Generate variable	assignments into a catname_msg.csh file.
	      This file	can be included	by C shell scripts for use with	the
	      dspmsg command.

  -h  Suppresses the generation	of the catname_msg.h file if -m	is not speci-
      fied or -m is specified along with -e sh or -e csh.

      Suppresses the macros that map symbolic identifiers for messages and
      sets to numeric constants	if -m is specified either without the -e
      option or	with -e	h.  (The catname_msg.h file is generated but contains
      only the macros that define symbolic identifiers for default message
      strings.)

  -m  Causes the output	header file or shell script include file to contain
      default message strings and their	symbolic identifiers.

  -p prefix
      Specifies	a prefix used in the identifier	for a default message string.
      If the prefix is not specified with the -p option, DEF_ is prepended to
      the message identifier to	form the identifier for	the default message
      string.

      Explicitly specifying a catalog-specific prefix is recommended if	pro-
      grams and	scripts	access multiple	message	catalogs. Otherwise, there is
      a	risk that the include files generated for the different	catalogs
      might define the same symbol for different message strings. The mkcat-
      defs command returns an error if symbolic	names are not unique within
      the same catalog;	however, multiple symbol definitions that result from
      including	multiple include files causes compiler warnings	or display of
      the wrong	message	string at run time.

  -S  Enables inclusion	of symbolic set	and message identifiers	in the output
      sent to the gencat command. Otherwise, only numeric set and message
      identifiers are included in the output sent to the gencat	command. See
      DESCRIPTION and EXAMPLES for information on how these symbolic identif-
      iers are used at run time.



DESCRIPTION

  The mkcatdefs	utility	preprocesses a message source file to do one or	more
  of the following operations. These operations	ease maintenance of compil-
  able programs, scripts, or both:

    +  Convert symbolic	identifiers for	message	sets and messages into
       numeric constants required by the gencat	command.  The gencat command
       creates the catname.cat file accessed by	the catopen(), catgets(), and
       catgets() functions and by the dspmsg utility.

    +  Create a	catname_msg.h file that	defines	macros to map symbolic iden-
       tifiers to corresponding	numeric	constants in the .cat file. Program
       source code that	specifies an include statement for catname_msg.h can
       therefore use symbolic identifiers rather than numeric constants	to
       identify	the messages to	be retrieved from the message catalog.

       If the -m option	is specified with the -e option	and an h argument,
       the header file also contains macros that define	symbolic identifiers
       for default message strings. A call to the catgets() function or	exe-
       cution of the dspmsg command in a program should	include	a default
       message string to be printed if a message catalog cannot	be found or
       opened for the locale in	which the program is running. When the
       catname_msg.h file includes macros for default message strings, pro-
       gram source code	can include an identifier for the default message
       string in the catgets() call or in an execution call for	the dspmsg
       utility.	This practice helps prevent unintentional inconsistencies
       between a message string	in the message source file and the same
       string specified	in program calls.

    +  Create an include file, similar to catname_msg.h, but for use in
       scripts rather than programs. If	-e sh is specified, the	include	file
       is named	catname_msg.sh and can be included in a	script that executes
       in the POSIX, Bourne, or	Korn shell. If -e csh is specified, the
       include file is named catname_msg.csh and can be	included in a script
       that executes in	the C shell.

       Include files for scripts define	variables only for the default mes-
       sage strings to be displayed when a catalog is not found	or cannot be
       opened. (Unlike the catgets() function, the dspmsg command is enhanced
       to use the symbolic set and message identifiers stored in the catalog
       by the -S option.)

  See gencat(1)	for a description of fundamental rules that govern the format
  of a message source file.  The only difference between gencat	and mkcatdefs
  is that with gencat you must input a number to identify each message set
  and message, while mkcatdefs accepts either a	number or a symbolic name. If
  the -S option	is included on the mkcatdefs command line, an additional mes-
  sage set is included in the input to the gencat command. This	set includes
  information that allows instances of the dspmsg command to retrieve mes-
  sages	from a catalog by using	symbols	rather than numbers. (The catgets()
  function, due	to constraints in the XSH standard, uses numeric constant
  identifiers at run time to retrieve messages from a message catalog.)

  The mkcatdefs	program	sends message source data to standard output. This
  output is suitable as	input to the gencat program.  You can use the right
  angle	bracket	(>>) character to write the preprocessed	message	source code
  to a file, and then use this file as input to	the gencat command. See	EXAM-
  PLES for an illustration of this technique.

  Each message set and message in program source code must have	a unique
  number or symbolic name. You can enable use of these symbolic	identifiers
  in a program by including them in the	message	source file input to the
  mkcatdefs command. Symbolic identifiers can contain English letters,
  digits, and underscores; however, the	first character	cannot be a digit or
  an underscore.  The mkcatdefs	command	converts symbolic names	specified in
  the message source file to numeric constants.	 One restriction is that
  mkcatdefs does not convert symbolic names included in	a $delset command.
  Therefore, if	your message source file contains $delset commands to delete
  message sets,	those commands must identify the sets to be deleted by their
  numeric constant identifiers.

  The mkcatdefs	program	is designed to create new message catalogs, not	to
  change existing ones incrementally.  Thus, the program's first operation on
  each set is to delete	it, in case the	catalog	contains a set with that
  number.  The sets specified in source_file are assigned numbers in ascend-
  ing order, starting at 1.  Within each set, messages are also	assigned
  numbers in ascending order, starting at 1.  If you explicitly	assign a mes-
  sage to a number in your source_file,	mkcatdefs continues its	ascending
  series with that number.

  You can use the runcat command rather	than the mkcatdefs command when	pro-
  cessing a message source file	that contains symbolic identifiers for mes-
  sage sets and	messages. The runcat command automatically sends the message
  source file through the mkcatdefs command and	pipes the files	to the gencat
  command. Note, however, that the runcat command supports only	the default
  behavior of the mkcatdefs command; that is, runcat cannot implement any of
  the operations supported by options on the mkcatdefs command line.

RESTRICTIONS

  Symbolic identifiers for message sets, messages, and default message
  strings are an ease-of-maintenance feature for program source	code and
  shell	scripts; however, symbolic references are a proprietary	extension to
  the XSH standard and might not be supported on all systems conforming	to
  this standard.

  Symbolic identifiers for message sets	and messages provide ease of mainte-
  nance	by reducing the	need to	change references in program source code when
  a catalog is revised.	However, use of	symbolic identifiers does not insu-
  late a program from run-time problems	if it uses the catgets() function to
  retrieve messages from a catalog, the	catalog	is revised, and	the program
  is not recompiled with a new version of the catname_msg.h file. That is
  because the XSH standard constrains the run-time behavior of catgets() to
  the use of numeric identifiers, and the numeric constants mapped to the
  symbolic identifiers can change when a message catalog is rebuilt.

  The mappings of numeric constants to symbols change if the following kinds
  of revisions were made to the	corresponding message source file (or files)
  and a	catalog	is rebuilt:

    +  New message sets	were added before or between existing message sets.

    +  Message sets, other than	the last one in	the file, were deleted.

    +  Existing	message	sets were rearranged.

    +  New messages were added before or between existing messages in a	given
       message set.

    +  Messages, other than the	last one, in a message set were	deleted.

    +  Existing	messages were rearranged within	a message set.

    +  The message catalog was built from multiple message source files	and
       the order in which these	files were specified on	the mkcatdefs command
       line was	changed.

  Therefore, if	these kinds of changes were made to message source code	and a
  catalog was rebuilt, programs	must be	recompiled with	a version of
  catname_msg.h	that was generated from	the revised message source file	or
  files.

  If care is taken to maintain the ordinal position of existing	message	sets
  and messages when the	message	source file is changed (assuming, of course,
  that program source code is not changed to refer to any new or deleted mes-
  sage sets and	messages), recompilation with a	revised	version	of
  catname_msg.h	is not necessary.

  Programs that	execute	a dspmsg command (rather than call the cat*() func-
  tions) to access a catalog can achieve complete independence from changes
  in numeric constant identifiers at run time. This is also true for scripts,
  which	must access a message catalog by using a dspmsg	command. To achieve
  this independence, the following conditions must be met:

    +  The -S must be included on the mkcatdefs	command	line.

    +  The -S, -s set_symbol, and message_symbol arguments must	be included
       in the dspmsg command line.

  Symbolic names for message sets and messages must be unique across all mes-
  sage sets included in	the catalog. By	implication, this also means that
  these	symbolic names must be unique across all message source	files speci-
  fied as input	to the mkcatdefs command.

  See the EXAMPLES section for an illustration of techniques that provide
  insulation from changes in how numeric constants are mapped to symbolic
  identifiers for message sets and messages.

EXAMPLES

   1.  The following example shows a message source file that contains one
       message set and uses a mix of symbolic and numeric identifiers for
       messages:


	    $quote " Use a double quotation mark to delimit message text
	    $set MSFAC	       Message Facility	- symbolic identifiers
	    SYM_FORM "Symbolic identifiers can contain only letters \
	    and	digits and the _ (underscore character)\n"
	    5 "You can mix symbolic identifiers	and numbers \n"
	    $quote
	    MSG_H Remember to include the "_msg.h" file	in your	program\n

       In the preceding	example, the $quote command sets the quote character
       to " (double quote), then disables it before the	last message, which
       contains	double quotes.

       When you	process	the file with mkcatdefs, the modified source is	writ-
       ten to standard output.	Standard output	can either be redirected to a
       file using the >>	redirection symbol or piped to gencat.

   2.  Assume that the preceding file is named symb.src.  It can be processed
       with mkcatdefs as follows:
	    $ mkcatdefs	symb symb.src >>symb.msg

       The symb.msg file contains the following	preprocessed message source
       code:


	    $quote " Use a double quotation mark to delimit message text
	    $delset 1
	    $set 1
	    1  "Symbolic identifiers can contain only letters \
	    and	digits and the _ (underscore character)\n"
	    5 "You can mix symbolic identifiers	and numbers \n"
	    $quote
	    6  Remember	to include the "_msg.h"	file in	your program\n

       Note that the assigned message numbers are noncontiguous	because	the
       symb.src	file contained a specific number. The mkcatdefs	program
       always assigns the previous number plus 1 to the	next symbolic iden-
       tifier.

       The generated symb_msg.h	file contains the following:


	    #ifndef _H_SYMB_MSG
	    #define _H_SYMB_MSG
	    #include <limits.h>
	    #include <nl_types.h>
	    #define MF_SYMB "symb.cat"

	    /* The following was generated from	symb.src. */

	    /* definitions for set MSFAC */
	    #define MSFAC 1

	    #define SYM_FORM 1
	    #define MSG_H 6
	    #endif

       Note that mkcatdefs also	created	the symbol MF_SYMB by prepending MF_
       to catname using	uppercase letters. The mkcatdefs program assumes that
       the name	of the generated catalog should	be catname.cat,	and generates
       this symbol for your use	with the catopen function.

       Because this include file contains include statements for limits.h and
       nl_types.h, you do not need to explicitly include these files in	your
       application program.  (The nl_types.h header file defines special data
       types required by the message facility routines.)

   3.  The following set of examples shows how to enable and use symbolic
       identifiers for sets, messages, and default message strings:

       The message source file used for	this set of examples contains the
       following lines:


	    $quote "
	    $set INFO
	    GREET "Welcome to the Fact Finder program!\n"
	    BYE	"Good-bye. Please come again.\n"
	    ENTER "Please enter	the type of product \
	    you	are interested in: "
	    $set RESULTS
	    NADA "Sorry, we have no information	on that	\
	    kind of product."
	    FOUND "The following products were found."
	    $set PROBLEMS
	    SERVCONN "Cannot connect to	server.	Try again later."
	    BUSYDAY "Still searching. Please wait..."


       The following command creates a message catalog that includes symbolic
       information as well as a	.sh file that can be executed in a POSIX,
       Bourne, or Korn shell script to define symbolic identifiers for
       default message strings:
	    % mkcatdefs	-S -m -e sh PFF	PFF.src	-h | gencat ./PFF.cat
	    mkcatdefs: PFF_msg.sh created


       The following command creates an	include	file for use in	program
       source code, as well as a copy of the preprocessed source code that
       was input directly to the gencat	command	in the preceding example:
	    % mkcatdefs	-S -m -e h PFF PFF.src >&gt; PFF.msg
	    mkcatdefs: PFF_msg.h created


       The following commands show what	is included in the .sh,	.h, and	mes-
       sage catalog files created from these commands:
	    % cat PFF_msg.sh

	    #
	    # Default messages generated from PFF.src
	    #
	    DEF_GREET='Welcome to the Product Fact Finder program!\n'
	    DEF_BYE='Good-bye.	Please come again.\n'
	    DEF_ENTER='Please enter the	type of	product	you are	interested in: '
	    DEF_NADA='Sorry, we	have no	information on that kind of product.'
	    DEF_FOUND='The following products were found.'
	    DEF_SERVCONN='Cannot connect to server. Try	again later.\n'
	    DEF_BUSYDAY='Still searching. Please wait...\n'
	    %
	    % cat PFF_msg.h
	    #ifndef _H_PFF_MSG
	    #define _H_PFF_MSG
	    #include <&lt;limits.h>&gt;
	    #include <&lt;nl_types.h>&gt;
	    #define MF_PFF "PFF.cat"



	    /* The following was generated from	PFF.src. */


	    /* definitions for set INFO	*/
	    #define INFO 1

	    #define GREET 1
	    #define BYE	2
	    #define ENTER 3

	    /* definitions for set RESULTS */
	    #define RESULTS 2

	    #define NADA 1
	    #define FOUND 2

	    /* definitions for set PROBLEMS */
	    #define PROBLEMS 3

	    #define SERVCONN 1
	    #define BUSYDAY 2

	    /* Default messages	generated from PFF.src */

	    #define DEF_GREET	    "Welcome to	the Product Fact Finder	program!\n"
	    #define DEF_BYE "Good-bye.	Please come again.\n"
	    #define DEF_ENTER	    "Please enter the type of product \
	    you	are interested in: "
	    #define DEF_NADA	    "Sorry, we have no information on that \
	    kind of product."
	    #define DEF_FOUND	    "The following products were found."
	    #define DEF_SERVCONN    "Cannot connect to server. Try again later.\n"
	    #define DEF_BUSYDAY	    "Still searching. Please wait...\n"
	    #endif
	    %
	    % dspcat PFF.cat
	    1 :	1 Welcome to the Product Fact Finder program!

	    1 :	2 Good-bye.  Please come again.

	    1 :	3 Please enter the type	of product you are interested in:
	    2 :	1 Sorry, we have no information	on that	kind of	product.
	    2 :	2 The following	products were found.
	    3 :	1 Cannot connect to server. Try	again later.

	    3 :	2 Still	searching. Please wait...
	    4 :	1 GREET	BYE ENTER
	    4 :	2 NADA FOUND
	    4 :	3 SERVCONN BUSYDAY
	    4 :	4 $@ INFO RESULTS PROBLEMS

       In this catalog,	there are three	message	sets defined from those
       specified in the	message	source file. The fourth	message	set is added
       by the mkcatdefs	command	to provide mappings of symbolic	names to
       corresponding numbers. All but the last message number in the fourth
       set correspond to the set numbers in the	first three sets. All but the
       last "message" in the fourth set	is an ordinal listing of the symbolic
       names for messages in a particular set. The last	"message" in the
       fourth set begins with a	magic string ($@), followed by an ordinal
       listing of symbolic names for the first three sets. For example,	the
       symbolic	name for the first message set is INFO,	which contains three
       messages	(specified on lines 1 :	1, 1 : 2, and 1	: 3) whose symbolic
       names are GREET,	BYE, and ENTER,	respectively. When displaying mes-
       sages from this catalog,	the dspmsg command can use either symbolic
       names or	numbers	as set and message identifiers.	For example:
	    % dspmsg	     -s	1 PFF.cat 1
	    Welcome to the Product Fact	Finder program!
	    % dspmsg -S	-s INFO	PFF.cat	GREET
	    Welcome to the Product Fact	Finder program!

       The following script illustrates	the use	of symbols for message sets,
       messages, and default message strings. By default, the dspmsg command
       and cat*() functions search for message catalogs	first in the current
       directory and then in the appropriate locale directory subordinate to
       /usr/lib/nls/msg:


	    #! /bin/sh
	    #
	    # test_dspmsg.sh
		.
		.
		.
	    . ./PFF_msg.sh
		.
		.
		.
	    dspmsg -S -s INFO PFF.cat GREET "${DEF_GREET}"
		.
		.
		.

       The dspmsg command in this script displays the message string whether
       or not the message catalog is found as long as the PFF_msg.sh file is
       installed with the script. For the following example, assume that the
       PFF.cat file is located only in the current directory:
	    % ./test_dspmsg.sh
	    Welcome to the Product Fact	Finder program!
	    % mv PFF.cat hide_PFF.cat
	    % ./test_dspmsg.sh
	    Welcome to the Product Fact	Finder program!

       A default message string	is typically English text, whereas a
       translated message is displayed if a translated version of the catalog
       is available for	the locale. The	advantage of using symbols for
       default message strings is to ensure that only one copy of the origi-
       nal message strings needs to be maintained.  When message strings must
       be maintained both in message source files, in calls to catgets(), and
       in dspmsg commands, inconsistencies are likely to develop between dif-
       ferent instances	of what	is intended to be the same string.

       A message can be	displayed as the message string	alone or as the	mes-
       sage string preceded by its message identifier. See dspmsg(1) for
       examples	of using the dspmsg command to display message strings pre-
       ceded by	their identifiers.

SEE ALSO

  Commands:  dspcat(1),	dspmsg(1), gencat(1), runcat(1)

  Functions:  catclose(3), catgets(3), catopen(3)

  Writing Software for the International Market