Extract a copy of the messages from the code and write them to a text file. UNICOS, UNICOS/mk, and IRIX text processing utilities such as grep(1), awk(1), and sed(1) are useful for this process. If the messages are generated by a consistent mechanism, this will be an easy task. If they are not, this step will take longer.

Add a number or symbolic name to the beginning of each message. Using the convention you decided on during the planning step, number the messages. Each message must have a unique number. The numbers must appear in the text file in ascending order, but they do not have to be consecutive.

Edit the copy of the messages that you extracted in step 2. Remove the printing command (fprintf, printf, and so on). Delete variable argument names, the name of the command issuing the message, the severity level, and any quotation marks added for print command syntax. (The message formatting function, catmsgfmt(3), inserts the command name and severity level when it formats the messages.) If you have a newline character (\n) at the end of the message, delete it also. Add the $msg tag to the beginning of the message and place single quotation marks (' ') around variables.

For example, suppose your code contains the following message:

fprintf(stderr,"ja: Unknown account name
%s\n", arg)

You should edit the message line so that it appears in the text file as follows:

$msg 100 Unknown account name '%s'

Edit each message in the text file in this way. The following listing shows a sample message text file.

$ message catalog for ja (part of group 'acct')
$msg 100 Unknown account name '%s'
$msg 101 Unknown group name '%s'
$msg 102 getoptlst() failed
$msg 103 Unknown user name '%s'
$msg 104 report modifying option(s) used without requesting a report
$msg 105 -m option cannot be selected when issuing a report
$msg 106 -m and -t options are mutually exclusive
$msg 107 -h option must be used with -l option
$msg 108 process is not part of a job
$msg 109 can't find TMPDIR in environment
$msg 110 can't make file name
$msg 111 file name exceeds max length
$msg 112 empty or nonexistent job accounting file
$msg 113 no commands seen
$msg 114 '%s' not removed
$msg 115 couldn't get space for selection by name
$msg 116 invalid regular expression for selection by name
$msg 117 couldn't get space for positioning marks
$msg 118 -p option's argument is invalid
$msg 119 cannot position to last entry
$msg 120 unable to position file
$msg 121 error in reading job accounting file
$   Next message is a warning
$msg 122 command flow tree overflow

The messages shown in the listing have not been edited to conform with the guidelines presented in Appendix A, “Guidelines for Messages and Explanations”. You may want to edit your messages with the guidelines in mind at this point in the procedure, or you may want to complete the conversion of your code, perform preliminary testing, and then return to the message file and concentrate on improving the text of the messages.

Use the caterr(1) utility to build the text file into a binary catalog. Give caterr the name of your message text file and the name of the catalog file you want to produce; caterr processes the message text file into a catalog binary. For details of the syntax of the caterr utility, see the caterr(1) man page.

For example, to build a catalog file called /home/me/messages/lib.cat from a message text file called lib.msg in the current directory, issue the following command:

caterr -c /home/me/messages/lib.cat lib.msg

Change the NLSPATH environment variable to point to the output of the caterr utility. For example, suppose the catalog binary file is in the following directory:

/home/cypress/me/messages

Set NLSPATH to the following value:

/home/cypress/me/messages/%N.cat

This lets you test your program by using a local message catalog.

Add a line to include the <nl_types.h> header file in the program. The <nl_types.h> file defines variables used by the message system. For a description of the file, see the nl_types(5) man page.

The include line appears in the program as follows:

#include <nl_types.h>

Add a line to define a message catalog file descriptor:

nl_catd  mcfd;

Change the code that issues each message. You can change the code on a message-by-message basis, or you can write a message routine that can be called each time you want to issue a user message. You decide which method works best for you, given the characteristics of your product.

The following code example illustrates one possible message processing routine designed to be called each time a user message is issued. The code is offered here as an example of an error processing routine. It is specific to one piece of code (ja(1)) and may not work for any other application.

The following assumptions were made when designing the routine:

You could easily modify the code to use more severity levels, more replaceable parameters, and different types of parameters.

/*
 *  Retrieve and print error message
 */
#include <stdio.h>
#include <nl_types.h>
#define BUFL 200

processerror (
  int err_num,      /* Message error number                    */
  int fatal,        /* Fatal flag (0 = warning, 1 = fatal)     */
  char *parameter   /* Optional substitution string parameter  */
)

{
        char    *s;             /* Error severity                  */
        char    *p;             /* Pointer to error message        */
        char    buf1[BUFL];     /* Error message buffer            */
        char    buf2[BUFL];     /* Error message buffer            */
        char    buf3[BUFL];     /* Error message buffer            */
        nl_catd mcfd;           /* Message catalog file descriptor */
        /* Open the message catalog                                */
        mcfd = catopen("acct", 0);
        p = catgetmsg(mcfd, NL_MSGSET, err_num, buf1, BUFL);

        /* If a parameter was passed in, insert it into the message */
        if (_numargs() >= 3) {
                (void) sprintf(buf2, p, parameter);
                p = buf2;
        }

        /* Set s to the appropriate severity level                 */
        if (fatal == 1)
                s = "UNRECOVERABLE";
        else
                s = "WARNING";

        /* Format the message using the catmsgfmt function         */
        (void) catmsgfmt("ja", "acct", err_num, s, p, buf3, BUFL);

        /* Print the formatted message to stderr                   */
        fprintf(stderr, buf3);

        /* If error is fatal, return error status                  */
        if (fatal == 1)
                return(1);

        return(0);
}