mkcatdefs man page on Tru64

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

mkcatdefs(1)							  mkcatdefs(1)

NAME
       mkcatdefs - Preprocesses a message source file

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

OPTIONS
       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: Generate macros
       into a catname_msg.h file. (Default) 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.  Generate  variable
       assignments  into a catname_msg.csh file.  This file can be included by
       C shell scripts for use with the dspmsg command.	 Suppresses the gener‐
       ation  of the catname_msg.h file if -m is not specified or -m is speci‐
       fied 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	gener‐
	      ated  but	 contains only the macros that define symbolic identi‐
	      fiers for default message strings.)  Causes  the	output	header
	      file  or	shell  script  include file to contain default message
	      strings and their symbolic identifiers.  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 mes‐
	      sage string.

	      Explicitly specifying a catalog-specific prefix  is  recommended
	      if programs and scripts access multiple message catalogs. Other‐
	      wise, there is a risk that the include files generated  for  the
	      different	 catalogs  might  define the same symbol for different
	      message strings. The mkcatdefs command returns an error if  sym‐
	      bolic  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.  Enables inclusion of	 symbolic  set
	      and  message  identifiers	 in the output sent to the gencat com‐
	      mand. Otherwise, only numeric set and  message  identifiers  are
	      included	in the output sent to the gencat command. See DESCRIP‐
	      TION and EXAMPLES for information on how these symbolic  identi‐
	      fiers 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
       compilable 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 sym‐
       bolic identifiers to corresponding numeric constants in the file.  Pro‐
       gram  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 argu‐
	      ment, the header file also contains macros that define  symbolic
	      identifiers for default message strings. A call to the catgets()
	      function or execution of the dspmsg command in a program	should
	      include a default message string to be printed if a message cat‐
	      alog cannot be found or opened for the locale in which the  pro‐
	      gram is running. When the catname_msg.h file includes macros for
	      default message strings, program	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 cat‐
	      name_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
	      message 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  identi‐
	      fiers 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 com‐
       mand line, an additional message set is included in the	input  to  the
       gencat  command. This set includes information that allows instances of
       the dspmsg command to retrieve messages 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 EXAMPLES 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  identi‐
       fiers  in  a program by including them in the message source file input
       to the mkcatdefs command. Symbolic identifiers can contain English let‐
       ters, 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 oper‐
       ation  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  num‐
       bers  in ascending order, starting at 1.	 Within each set, messages are
       also assigned numbers in	 ascending  order,  starting  at  1.   If  you
       explicitly  assign a message 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
       processing a message source file that contains symbolic identifiers for
       message 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  conform‐
       ing to this standard.

       Symbolic	 identifiers  for  message  sets  and messages provide ease of
       maintenance by reducing the need to change references in program source
       code  when  a  catalog is revised. However, use of symbolic identifiers
       does not insulate a program from run-time problems if it uses the  cat‐
       gets()  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 message sets and messages), recompilation with a	 revised  ver‐
       sion of catname_msg.h is not necessary.

       Programs	 that  execute	a  dspmsg command (rather than call the cat*()
       functions) 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 com‐
       mand.  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
       message	sets  included in the catalog. By implication, this also means
       that these symbolic names must be  unique  across  all  message	source
       files specified 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
       The  following  example	shows  a message source file that contains one
       message set and uses a mix of symbolic and numeric identifiers for mes‐
       sages:

	      $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  sym‐
	      bolic  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
	      written to standard output.  Standard output can either be redi‐
	      rected to a file using the > redirection symbol or piped to gen‐
	      cat.   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 let‐
	      ters \ 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 identifier.

	      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  prepend‐
	      ing  MF_	to catname using uppercase letters. The mkcatdefs pro‐
	      gram 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  lim‐
	      its.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.)  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 SERV‐
	      CONN "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 file that can be executed in a
	      POSIX,  Bourne,  or Korn shell script to define symbolic identi‐
	      fiers 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 > PFF.msg mkcatdefs:
	      PFF_msg.h created

	      The  following  commands	show  what  is	included  in the % 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	 prod‐
	      uct  you are interested in: ' DEF_NADA='Sorry, we have no infor‐
	      mation on that kind of product.' DEF_FOUND='The following	 prod‐
	      ucts  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
	      <limits.h> #include <nl_types.h> #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 pro‐
	      gram!\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_BUSY‐
	      DAY      "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	 PROB‐
	      LEMS

	      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 particu‐
	      lar 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
	      messages 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 sym‐
	      bols for default message strings is to ensure that only one copy
	      of the original 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 different instances of what is
	      intended to be the same string.

	      A message can be displayed as the message string alone or as the
	      message string preceded by its message identifier. See dspmsg(1)
	      for examples of using the	 dspmsg	 command  to  display  message
	      strings preceded 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

								  mkcatdefs(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