Retrieves a message from a message catalog.

    Format

      #include  <nl_types.h>

      char *catgets  (nl_catd catd, int set_id, int msg_id, const char *s);

1 - Function Variants

    The catgets function has variants named _catgets32 and _catgets64
    for use with 32-bit and 64-bit pointer sizes, respectively.

2 - Arguments

 catd

    A message catalog descriptor. This is returned by a successful
    call to catopen.

 set_id

    An integer set identifier.

 msg_id

    An integer message identifier.

 s

    A pointer to a default message string that is returned by the
    function if the message cannot be retrieved.

3 - Description

    The catgets function retrieves a message identified by set_id
    and msg_id, in the message catalog catd. The message is stored in
    a message buffer in the nl_catd structure, which is overwritten
    by subsequent calls to catgets. If a message string needs to
    be preserved, it should be copied to another location by the
    program.

4 - Return Values

    x                  Pointer to the retrieved message.
    s                  Pointer to the default message string.
                       Indicates that the function is not able
                       to retrieve the requested message from
                       the catalog. This condition can arise if
                       the requested pair (set_d, msg_id) does
                       not represent an existing message from the
                       open catalog, or it indicates that an error
                       occurred. If an error occurred, the function
                       sets errno to one of the following values:

                       o  EBADF - The catalog descriptor is not
                          valid.

                       o  EVMSRR - An OpenVMS I/O read error;
                          the OpenVMS error code can be found in
                          vaxc$errno.

5 - Example

 #include <nl_types.h>
 #include <locale.h>
 #include <stdarg.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <unixio.h>

  /* This test makes use of all the message catalog routines. catopen  */
  /* opens the catalog ready for reading, then each of the three       */
  /* messages in the catalog are extracted in turn using catgets and   */
  /* printed out. catclose closes the catalog after use.               */
  /* The catalog source file used to create the catalog is as follows: */
  /* $ This is a message file
  * $
  * $quote "
  * $ another comment line
  * $set 1
  * 1 "First set, first message"
  * 2 "second message - This long message uses a backslash \
  * for continuation."
  * $set 2
  * 1 "Second set, first message"                                      */

 char *default_msg = "this is the first message.";

 main()
 {
   nl_catd catalog;
   int msg1,
       msg2,
       retval;

   char *cat = "sys$disk:[]catgets_example.cat"; /*Force local catalog*/

   char *msgtxt;

   char string[128];

   /* Create the message test catalog */

   system("gencat catgets_example.msgx catgets_example.cat") ;

   if ((catalog = catopen(cat, 0)) == (nl_catd) - 1) {
       perror("catopen");
       exit(EXIT_FAILURE);
   }

   msgtxt = catgets(catalog, 1, 1, default_msg);
   printf("%s\n", msgtxt);

   msgtxt = catgets(catalog, 1, 2, default_msg);
   printf("%s\n", msgtxt);

   msgtxt = catgets(catalog, 2, 1, default_msg);
   printf("%s\n", msgtxt);

   if ((retval = catclose(catalog)) == -1) {
       perror("catclose");
       exit(EXIT_FAILURE);
   }

   delete("catgets_example.cat;") ;  /* Remove the test catalog */
 }

      Running the example program produces the following result:

        First set, first message
        second message - This long message uses a backslash for
                                                  continuation.
        Second set, first message