*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> gencat (1)              



NAME    [Toc]    [Back]

       gencat - Creates and modifies a message catalog

SYNOPSIS    [Toc]    [Back]

       gencat catalog_file source_file...

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       gencat:  XCU5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

OPERANDS    [Toc]    [Back]

       Specifies  the  message catalog to be modified or created.
       You can substitute - (a dash) for this operand  to  direct
       command  results  to  the standard output rather than to a

              [Tru64 UNIX]  The  convention  is  to  include  the
              extension  on  the  filename  of a message catalog.
              Specifies the message text source file,  or  files,
              used  to  modify or create the message catalog. You
              can substitute -  (a  dash)  for  this  operand  to
              direct  gencat  to  accept message source data from
              the standard input.

              [Tru64 UNIX]  You can  also  omit  the  source_file
              operand  to  direct gencat to accept message source
              data from the standard input.   This  extension  is
              supported only to ensure backward compatibility for
              existing scripts.  For new scripts,  it  is  recommended
  that you specify - (a dash) for source_file
              when you want gencat to accept message source  data
              from the standard input.

              [Tru64  UNIX]  The  convention  is  to  include the
              extension on the filename of a message text  source

DESCRIPTION    [Toc]    [Back]

       The  gencat  command creates or modifies a message catalog
       from a message text source file.

       A message text source file is a text file that you  create
       to hold messages printed by your program.  You can use any
       text editor to enter messages into the text  source  file.
       Messages  can be grouped into sets, generally to represent
       functional subsets of your program.  Each  message  has  a
       numeric  identifier,  which must be unique within its set.
       The message text source file  can  also  contain  commands
       recognized  by gencat for manipulating sets and individual

       [Tru64 UNIX]  Programmers can use  symbolic  names  rather
       than  numeric  constants  to refer to messages within programs.
  The gencat utility  does  not  recognize  symbolic
       names,  but  the mkcatdefs: Accepts messages preceded by a
       symbolic name and assigns a numeric value to each  Creates
       a header file that applications can include to map message
       symbols to their numeric values

       [Tru64 UNIX]  Therefore, the most convenient way to generate
  a  message catalog is to pass your symbolic constants
       and associated messages through mkcatdefs  and  then  pass
       its output to gencat.

       If  a  message  catalog with the name catalog_file exists,
       gencat modifies it according to the statements in the message
  source  files. If the catalog does not exist, gencat
       creates the catalog with the name catalog_file.

       You can specify any number of message text  source  files.
       The  gencat  command  processes  multiple source files one
       after the other in the sequence  that  you  specify  them.
       Each  successive  source file modifies the catalog. If you
       specify - (a dash) in place  of  source_file,  the  gencat
       command  accepts  message  source  data  from the standard
       input. Note that you can specify a - (dash) for the  catalog
  file  (standard  output),  the  source file (standard
       input), or both.

       The source_file can contain the following commands.   Each
       initial keyword or number must be followed by white space.
       The gencat utility  ignores  any  line  beginning  with  a
       space, a tab, or a $ (dollar sign) character followed by a
       space, a tab, or a newline character. Thus,  you  can  use
       these  sequences  to  start  comments in your source_file.
       Blank lines are also ignored.  Finally, you can place comments
 on the same line after the $delset, $quote, $len, or
       $set commands, because the gencat utility ignores anything
       following  the preceding syntax elements.  Inserts text as
       a message with  the  identifier  message_number.   Numbers
       must  be ascending within each set: you can skip a number,
       but you cannot go back to add a missing number or  replace
       an existing number during a gencat session.

              The value for message_number must be in the range 1
              to NL_MSGMAX, which is defined  in  the  <limits.h>
              header file.

              If  the  message  text is empty, and a space or tab
              field separator is  present,  an  empty  string  is
              stored  in the message catalog. If a message source
              line has a message number, but neither a field separator
  nor  message  text,  the  existing  message
              within that number (if any)  is  deleted  from  the

              Refer  to  the  following description of $len for a
              discussion of the length limits that apply to  message
  text.   Deletes the set of messages indicated
              by set_number.

              The set_number parameter must be in the range 0  to
              NL_SETMAX,  which  is  defined  in  the  <limits.h>
              header file.  Sets the quote character  to  character.
   See  the  explanation later in this section.
              [Tru64 UNIX]  Sets the maximum length  allowed  for
              messages  in  your  catalog. If this command is not
              used, or if you use it without the max_length argument,
  the  maximum length is 8192 bytes (the value
              set by NL_TEXTMAX, which is defined  in  the  <limits.h>
  header file). XCU does not include the $len
              command and specifies that the  length  of  message
              text be in the range 0 to NL_TEXTMAX.

              [Tru64  UNIX]  If gencat does not encounter a digit
              immediately following the single nonblank character
              separator  between $len and its first argument, the
              command ignores the rest of the line. Therefore, if
              you  intend  to  include  the  optional  max_length
              parameter, make sure only one space or tab  character
 separates the number from $len.  Indicates that
              all messages entered after this command are  placed
              in the set indicated by set_number.  You can change
              the set by entering another $set command.  However,
              set numbers must be entered in ascending order; you
              cannot go back to a lower-numbered set  during  the
              gencat  session.  If  the  command is not used, the
              default set number is the value of NL_SETD  in  the
              <nl_types.h>  header  file.   This value is vendordefined.
  On this  operating  system,  the  NL_SETD
              value is 1.

              The  set_number parameter must be in the range 1 to
              NL_SETMAX,  which  is  defined  in  the  <limits.h>
              header file.

       A  line  beginning  with  a  digit  marks  a message to be
       included in the catalog. You can  specify  any  amount  of
       white  space between the message ID number and the message
       text; however, one space or tab character  is  recommended
       when  the  message  text  is not delimited by quotes. When
       message text is not quoted, gencat treats additional white
       space  as  part  of  the  message.   When  message text is
       quoted, gencat ignores all spaces or tabs between the message
 ID and the first quotation character.

       Escape sequences, like those recognized by the C language,
       can be used in text; these are listed after the  commands.
       Use  a \ (backslash) character to continue message text on
       the following line.

       The gencat command does not accept symbolic identifiers.

       [Tru64 UNIX]  You must run the mkcatdefs  command  if  you
       want to use symbolic identifiers for messages in your program.

       The Escape character \ (backslash) can be used to  include
       the  following  special  characters  in  the message text:
       Inserts a newline (NL or LF).  Inserts  a  horizontal  tab
       (HT).   Inserts a vertical tab (VT).  Performs a backspace
       function (BS).  Inserts a carriage return (CR).  Inserts a
       form  feed  (FF).   Inserts  a backslash (\).  Inserts the
       single-byte character associated with the octal value represented
 by the octal digits ddd. One, two, or three octal
       digits can be specified; however, you must include leading
       zeros  if  the  characters  following the octal digits are
       also valid octal digits.  For example, the octal value for
       $  (dollar  sign)  is 44.  To insert $5.00 into a message,
       use \0445.00, not \445.00, or the 5 will be parsed as part
       of  the  octal value.  [Tru64 UNIX]  Inserts the character
       associated with the hexadecimal value represented  by  the
       hexadecimal  digits.  The gencat command inserts a singlebyte
 character when you specify two valid digits (dd)  and
       a double-byte character when you specify four valid digits
       (dddd). See \ddd for a way to avoid  parsing  errors  when
       the hexadecimal value precedes an actual digit.

       You can also include printf() conversion specifications in
       messages that are printed by the printf() family of  calls
       in C code or by the printf command in shell scripts.

       [Tru64 UNIX]  If you display a message from a shell script
       with the dspmsg command, the  only  conversion  specifications
 that can be used in the message are %s and %n$s.

EXIT STATUS    [Toc]    [Back]

       On  successful  completion,  the  gencat command returns 0
       (zero); on error, the command returns a value greater than
       zero.  When  gencat  returns  an error value, no action is
       taken on any commands, and an  existing  catalog  is  left

ERRORS    [Toc]    [Back]

       [Tru64  UNIX]  You can enter the following command to display
 the messages returned by the gencat command: % dspcat
       msgfac.cat | grep gencat

EXAMPLES    [Toc]    [Back]

       To  use  the $set command in a source file to give a group
       of messages a set number,  enter:  $set  10  Communication
       Error Messages

              The message set number is 10.  All messages following
 the $set command are assigned that set  number,
              up  until  the  next  occurrence of a $set command.
              (Set numbers must be assigned in  ascending  order,
              but need not be contiguous.  Large gaps in the number
 sequence are discouraged in order  to  increase
              efficiency  and  performance.   There is no performance
 advantage to using more than one  set  number
              in a catalog.)

              You  can include a comment in the $set command, but
              it is not required.  To use the $delset command  to
              remove  all of the messages belonging to the specified
 set from a catalog, enter: $delset 10 Communication
 Error Messages

              The message set is specified by n. The $delset command
 must be placed in the proper set number  order
              with  respect  to  any  $set  commands  in the same
              source file.  You can  include  a  comment  in  the
              $delset  command  also.  Enter the message text and
              assign message ID  numbers  as  follows:  12  "file

              This  command  assigns  the message ID number 12 to
              the text that follows it.

              You must leave at least one space or tab  character
              between the message ID number and the message text,
              but you can include more spaces or tabs if you prefer.
  If  you  do include more spaces or tabs, they
              will be ignored when message  text  is  quoted  and
              considered  part  of  the text when message text is
              not quoted.

              Message numbers must be in ascending order within a
              single message set, but need not be contiguous.

              All  text  following the message number is included
              as message text, up to the end of the line.  If you
              place  the  escape  character  \ (backslash) as the
              last character on the line, the message  text  continues
 on the following line.  Consider the following

              This is the text associated with \  message  number

              These  two  lines  define the following single-line

              This is the text associated with message number  5.
              The  following  example shows the effect of a quote

              $quote "   Use a double quote  to  delimit  message
              text  $set  10             Message Facility - Quote
              command messages  1  "Use  the  $quote  command  to
              define  a  character  \  \n  for delimiting message
              text" \n 2 "You can include the \"quote\" character
              in  a  message  \n \ by placing a \\ (backslash) in
              front of it" \n 3 You can include the "quote" character
 in a message \n \ by having another character
              as the first nonspace \ \n character after the message
  ID  number  \n  $quote  4 You can disable the
              quote mechanism by \n \ using  the  $quote  command
              without \n a character \ after it \n

              In  this  example, the $quote command defines the "
              (double quote) as the quote  character.  The  quote
              character must be the first nonspace character following
 the message number. Any text  following  the
              next  occurrence of the quote character is ignored.

              The example also shows two ways the quote character
              can  be  included in the message text: Place a \ in
              front of the quote character.  Use some other character
 as the first nonspace character following the
              message number. This disables the  quote  character
              only for that message.

              The  example also shows the following: A \ is still
              required to split a quoted  message  across  lines.
              To display a \ in a message, you must place another
              \ in front of it.  You can format your message with
              a  newline  character  by using \n.  If you use the
              $quote command with no character argument, you disable
 the quote mechanism.


       The    following   locale   environment   variables   (see
       i18n_intro(5) and l10n_intro(5)) affect gencat  operation:
       Provides  a  default  value  for locale category variables
       that are not set. If any of these  variables  contains  an
       invalid  setting, the gencat command behaves as if none of
       them were defined.  If set to a  non-empty  string,  overrides
  values  in  all  locale  variables, including LANG.
       Determines the locale for the interpretation in text  data
       of  byte  sequences  as characters.  Determines the locale
       used for diagnostic messages.  Determines the location  of
       message catalogs for the processing of LC_MESSAGES.

SEE ALSO    [Toc]    [Back]

       Commands:  dspcat(1), dspmsg(1), extract(1), mkcatdefs(1),
       printf(1), runcat(1), strextract(1), strmerge(1), trans(1)

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

       Files:  patterns(4)

       Others:  i18n_intro(5),   l10n_intro(5),   iconv_intro(5),

       Writing Software for the International Market

[ Back ]
 Similar pages
Name OS Title
voledit Tru64 Creates, removes, and modifies Logical Storage Manager (LSM) records
dspmsg Tru64 Displays a selected message from a message catalog
catgetmsg IRIX Reads a message from a message catalog
catopen NetBSD open message catalog
catopen OpenBSD open message catalog
catclose FreeBSD close message catalog
catopen FreeBSD open message catalog
catclose NetBSD close message catalog
catgets Tru64 Retrieve a message from a catalog
catclose OpenBSD close message catalog
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service