### Example (catclose, catgets, catopen)

The following example has dependencies on the following message catalog, test.msg:

    $ This is an example of a mnemonic source file for messages.
    $ For comments, use the dollar symbol plus a blank.
    $ For symbol definitions, use the dollar symbol followed by the definition.
    $ An example of a symbol definition:
    $quote "

    $ For set definitions, use the dollar symbol plus the immediate set:
    $set MS_SET1  This is set one of the messages

    MSG_1  "On: %2$s at: %3$s the file: %1$s was printed on printer: %4$s.\n"

    $ Define a new quote character for purposes of illustration:
    $quote '

    $set MS_SET2  This is set two of the messages

    EMSG_1  'This is a message from the message catalog.\n'

Before running the following example, you must run mkcatdef followed by gencat. To process the test.msg message source file, and redirect the output to the test.src file, enter:

>     mkcatdef test test.msg > test.src
>     gencat test.cat test.src

The generated test.h file looks similar to the following:

    #ifndef _H_TEST_MSG
    #define _H_TEST_MSG
    #include <limits.h>
    #include <nl_types.h>
    #define MF_TEST "test.cat"

    /* The following was generated from test.msg. */

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

    #define MSG_1 1

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

    #define EMSG_1 1
    #endif

This example incorporates the three functions -- catclose, catgets, catopen -- to open a catalog, read a message from it, and close a catalog.

    /******************************************************/
    /***   Global defines.                              ***/
    /******************************************************/

    #define BELL        7  /* Character to print a bell.  */
    #define EXIT_ERROR  1  /* The program exited with an error.*/

    /******************************************************/
    /***   Include files.                               ***/
    /******************************************************/

    #include <stdlib.h>
    #include <stdio.h>     /* Standard IO.                */
    #include <locale.h>    /* Locale-specific information.*/
    #include <nl_types.h>
    #include "test.h"      /* Header file for catalog IDs.*/

    /******************************************************/
    /***   Global variables.                            ***/
    /******************************************************/

    nl_catd cat_handle;   /* Handle to catalog file.      */
    char *ret_string;     /* String returned from catgets.*/

    /******************************************************/
    /***   Main program.                                ***/
    /******************************************************/

    void main(void)
    {

       /***************************************************/
       /* Set the locale. Print out the locale we are in  */
       /* for messages.                                   */
       /***************************************************/

       setlocale(LC_ALL, "");
       printf("\nName of messaging locale is: %s\n\n",
              setlocale(LC_MESSAGES, NULL));

       /***************************************************/
       /* Open the catalog. (Using LC_MESSAGES, not LANG  */
       /* via the second argument). If catalog not        */
       /* found... Print an error message. Exit the       */
       /* program.                                        */
       /***************************************************/

       cat_handle = catopen (MF_TEST, NL_CAT_LOCALE);
       if (cat_handle == CATD_ERR) {
          printf("%cCould not open catalog!\n", BELL);
          exit(EXIT_ERROR);
       }

       /****************************************************/
       /* Read a message from the catalog. Print out the   */
       /* message.                                         */
       /****************************************************/

       ret_string = catgets(cat_handle, MS_SET2, MSG_1, "No message read.");
       printf("String: %s\n", ret_string);

       /****************************************************/
       /* Attempt to read a message which is not in the    */
       /* catalog. Print out the results.                  */
       /****************************************************/

       ret_string = catgets(cat_handle, 400, 500, "No message read.\n");
       printf("String: %s\n", ret_string);

       /****************************************************/
       /* Read a message so we can put in positional       */
       /* arguments. Print a header. Print the string      */
       /* with four positional arguments. (NOTE: The order */
       /* of the arguments in the printf call is NOT the   */
       /* order in which they are printed in the output    */
       /* string.)                                         */
       /****************************************************/

       ret_string = catgets(cat_handle, MS_SET1, MSG_1, "No message read.\n");
       printf("String: ");
       printf(ret_string, "myfile.sys", "3/29/94", "5:04PM", "PS");

       catclose(cat_handle);    /* Close the catalog.      */

       /****************************************************/
       /* Now try to read a message from a catalog with an */
       /* invalid handle. This should return back the      */
       /* default message.                                 */
       /****************************************************/

       ret_string = catgets(cat_handle, MS_SET_1, "No catalog open.\n");
       printf("\nString: %s\n", ret_string);

       return;

       /*****************************************************
          The output should be:

          Name of messaging locale is: en_us
          String: This is a message from the message catalog
          String: No message read
          String: On: 3/29/94 at: 5:04PM the file:
                  myfile.sys was printed on printer: PS
          String: No catalog open
       *****************************************************/
    }