catgets() — Retrieve a Message from a Message Catalog

Format

#include <nl_types.h>
char *catgets(nl_catd catd, int set_id, int msg_id, char *s);

Language Level

XPG4

Threadsafe

Yes

Locale Sensitive

The behavior of this function might be affected by the LC_CTYPE category of the current locale. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Integrated File System Interface

This function is not available when SYSIFCOPT(*NOIFSIO) is specified on the compilation command.

Description

The catgets() function retrieves message msg_id, in set set_id from the message catalog that is identified by catd. catd is a message catalog descriptor that is returned by a previous call to catopen(). The s argument points to a default message which will be returned by catgets() if the identified message cannot be retrieved.

Return Value

If the message is retrieved successfully, then catgets() returns a pointer to the message string that is contained in the message catalog. The CCSID of the retrieved message is determined by the flags specified in the oflag parameter on the previous call to the catopen() function, when the message catalog file was opened.
  • If the NL_CAT_JOB_MODE flag was specified, then the retrieved message is in the CCSID of the job.
  • If the NL_CAT_CTYPE_MODE flag was specified, then the retrieved message is in the CCSID of the LC_CTYPE category of the current locale.
  • If neither flag was specified, the CCSID of the retrieved message matches the CCSID of the message catalog file.
If the message is retrieved unsuccessfully, then a pointer to the default string s is returned.
The value of errno can be set to the following:
EBADF
The catalog descriptor is not valid.
ECONVERT
A conversion error occurred.
EINTR
The function was interrupted by a signal.

Example

#include <stdio.h>
#include <nl_types.h>
#include <locale.h>
 
/* Name of the message catalog is "/qsys.lib/mylib.lib/msgs.usrspc" */
 
int main(void) {
 
   nl_catd msg_file;
   char * my_msg;
   char * my_locale;
 
   setlocale(LC_ALL, NULL);
   msg_file = catopen("/qsys.lib/mylib.lib/msgs.usrspc", 0);
 
   if (msg_file != CATD_ERR)  {
 
     my_msg = catgets(msg_file, 1, 2, "oops");
 
     printf("%s\n", my_msg);
 
     catclose(msg_file);
   }
}

Related Information