catgets

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);

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.

Description

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 catalogue. This condition can arise if the requested pair (set_d, msg_id) does not represent an existing message from the open catalogue, or it indicates that an error occurred. If an error occurred, the function sets errno to one of the following values: EBADF - The catalog descriptor is not valid. EVMSRR - A VMS I/O read error; the VMS error code can be found in vaxc$errno.

Example

#include <nl_types.h>
#include <locale.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.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:[]test.cat";
char *msgtxt;

char string[128];

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);
   }

}

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