mkcatdefs(1int) 														   mkcatdefs(1int)

Name
       mkcatdefs - Preprocesses a message source file

Syntax
       mkcatdefs symbol_name source_file ...

Description
       The message facility program preprocesses a message source file. The source_file message text source file contains mnemonic identifiers.

       The  program  produces  the symbol_name_msg.h file containing definition statements equating your mnemonic identifiers with set numbers and
       message ID numbers assigned by The symbol_name _msg.h file is required in your application program if you use mnemonic identifiers.

       The program sends message source data, with numbers instead of mnemonic identifiers, to standard output. This output is suitable  as  input
       to  the program. You can use the > (redirection mnemonic) to write the message source to a file, then use the file as input to You can cre-
       ate a message text source file using any text editor to enter the messages.

       Assign message set numbers and message ID numbers to each message by using the commands described in the following section.

   Symbolic Message Identifiers
       The operating system provides a mechanism that allows mnemonic references to messages by letting you use alphanumeric  identifiers  instead
       of  set	numbers  and  message  ID  numbers. You assign the identifiers to sets and messages in the source file in the same manner that you
       assign set numbers and message ID numbers.

       The mnemonic identifiers can contain ASCII letters, digits, and underscores. The first character cannot be a digit. The maximum length can-
       not exceed 64 bytes.

       The following example shows a message source file with mnemonic message identifiers:
       $set symbolic	  Message Facility - Symbolic ID's
       $quote *
       ID_names  *Symbolic identifier syntax: 
 
       	ASCII alphanumerics or underscores 
 
       	non-digit first character 
 
       	64 byte maximum length *
       set_use	 *To assign set ID: 
 
       	$set "identifier" [comment] *
       msg_use	 *To assign message ID: 
 
       	"identifier" message-text *

   Subcommands
       Use the $set command in a source file to give a group of messages a set number. The format of the $set command is as follows:
       $ set n [ comment ]
       The  set number is specified by n. Instead of a number, you can specify a mnemonic identifier that must contain only ASCII letters, digits,
       or the _ (underscore character). The maximum length of an identifier is 65 bytes. The program assigns a set number to the  identifier.  The
       assigned  set  number  is one higher than the preceding set number, or 1 if it is the first $set.  The program inserts a $delset before the
       $set in the output message source file.

       You can mix numbers and mnemonic identifiers.  You can include a comment in the $set command, but it is not required. The following example
       includes a comment:
       set CEM	Communication Error Messages
       Use  the  $delset command to remove all of the messages belonging to the specified set from a catalog. The format of the $delset command is
       as follows:
       $delset n [ comment ]

       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.

       You can include a comment line anywhere in the source file, except within message text. Indicate comments as follows:
       $ [ comment ]

       You must leave at least one space after the $ prompt.

       Enter the message text and mnemonic message identifier as follows:
       identifier message_text

       identifier  can	be  either a number or a mnemonic identifier and can contain only ASCII letters, digits, or the _  (underscore character).
       The maximum length of an identifier is 65 bytes. The program assigns a message number to the identifier. The assigned number is one  higher
       than the preceding message number, or 1 if it is the first message after the $set command.

       Note that inserts a $delset before the $set, which means you cannot add, delete, or replace single messages in the catalog if you are using
       mnemonic message identifiers. You must enter all of the messages in the set.

       You can mix numbers and mnemonic identifiers.

       You must leave at least one space after the message identifier or number.

       Any amount of white space is allowed after the message ID number; however, X/Open specifies that you leave only one space between the  mes-
       sage  number  and the message text. All text following the first nonspace character to the end of the line is included in the message text.
       If the source contains a $quote command preceding the message, all text between the quotation marks is included. Use a  (backslash)  char-
       acter to continue message text on the following line.  The  must be the last character on the line, as in the following example:
       FIVE	Text associated with 
       message FIVE.
       These two lines define the following single-line message:
       FIVE	Text associated with message FIVE.
       The  can be used to include special characters in the message text. These special characters are defined as follows:

       
     Inserts a newline character.

       	     Inserts a horizontal tab character.

       v     Inserts a vertical tab.

            Inserts a backspace character.

       
     Inserts a carriage-return character.

       f     Inserts a formfeed character.

       \     Inserts a  (backslash) character.

       ddd   Inserts  the  single-byte  character  associated with the octal value represented by the valid 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 $ is 44. To display $5.00, use 445.00, not 445.00, or the 5 is parsed as part of
	      the octal value.

       You can also include conversion specifications in messages that are displayed by applications using You can use the  $quote  command  in  a
       message source file to define a character for delimiting message text. The format for this command is as follows:
       $quote [ char ] [ comment ]

       Use the specified character before and after the message text as shown in the following example source file:
       $quote "  Use a double quotation mark to delimit message text
       $set MSFAC	  Message Facility - symbolic identifiers
       SYM_FORM   "Symbolic identifiers can only contain ASCII letters 
       or digits or the _ (underscore character)
"
       SYM_LEN	  "Symbolic identifiers cannot be more than 65 
       bytes long
"
       5	      "You can mix symbolic identifiers and numbers 
"
       $quote
       MSG_H	 Remember to include the "msg_h" file in
       your program


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

       The preceding file can be processed with as follows:

       $ mkcatdefs symb symb.src >symb.msg

       When you process the file with the modified source is written to standard output.  Standard output can either be redirected to a file using
       the > (redirection mnemonic) or piped to

       The following source is created:
       $quote "     Use double quotation marks to delimit message text
       $delset 1
       $set 1
       1     "Symbolic identifiers can only contain ASCII letters 
       or digits or the _ (underscore character)
"
       2     "Symbolic identifiers cannot be more than 65 
       bytes long
"
       5     "You can mix symbolic identifiers and numbers
"
       $quote
       6     remember to include the "msg_h" file in your program

       Note  that  the	assigned  message numbers are noncontiguous because the source contained a specific number. The program always assigns the
       previous number plus 1 to a mnemonic identifier.

       The program also produces a definition file for inclusion in your program.  The name of the file is symbol_name,  and  is  entered  as  the
       first argument to the command.

Examples
       If the message text source defined under Subcommands were in a file called symb.src, you could use the command as follows:
       $ mkcatdefs symb symb.src >symb.msg
       or
       $ mkcatdefs symb symb.src | gencat symb.cat
       The generated symb_msg.h file would appear as follows:
       #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 SYM_LEN 2
       #define MSG_H 6
       Note  that  also created  a mnemonic MF_SYMB by adding MF_ to the symbol_name using uppercase letters. The program assumes that the name of
       the generated catalog should be symbol_name.cat, and generates this mnemonic for your use with The symbol_name.cat file	includes  limits.h
       and  nl_types.h, you do not need to include them in your application program.  (nl_types defines special data types required by the message
       facility routines.)

See Also
       extract(1int), gencat(1int), trans(1int), catgets(3int), catopen(3int), environ(5int)
       Guide to Developing International Software

																   mkcatdefs(1int)