ILE C/C++ Run-Time Library Functions


catopen() -- Open Message Catalog

Format

#include <nl_types.h>
nl_catd catopen(const char *name, int oflag);

Language Level: XPG4

Threadsafe: Yes.

Description

The catopen() function opens a message catalog, which must be done before a message can be retrieved. The NLSPATH environment variable and the LC_MESSAGES category are used to find the specified message catalog if no slash (/) characters are found in the name. If the name contains one or more slash (/) characters, then the name is interpreted as a path name of the catalog to open.

If there is no NLSPATH environment variable, or if a message catalog cannot be found in the path specified by NLSPATH, then a default path will be used. The default path may be affected by the setting of the LC_MESSAGES locale category if the value of oflag is NL_CAT_LOCALE, or by the LANG environment variable if the value of oflag is zero.

The message catalog descriptor will remain valid until it is closed by a call to catclose(). If the LC_MESSAGES locale category is changed, it may invalidate existing open message catalogs.

Note:
This function is not available when either LOCALETYPE(*CLD) or SYSIFCOPT(*NOIFSIO) is specified on the compilation command. The name of the message catalog must be a valid Integrated File System file name.

Return Value

If the message catalog is opened successfully, then a valid catalog descriptor is returned. If catopen() is unsuccessful, then it returns CATD_ERR ((nl_catd)-1).

The catopen() function might fail under the following conditions, and the value of errno may be set to:

EACCES
Insufficient authority to read the message catalog specified, or to search the component of the path prefix of the message catalog specified.

ECONVERT
A conversion error occurred.

EMFILE
NL_MAXOPEN message catalogs are currently open.

ENAMETOOLONG
The length of the path name of the message catalog exceeds PATH_MAX, or a path name component is longer than NAME_MAX.

ENFILE
Too many files are currently open in the system.

ENOENT
The message catalog does not exist, or the name argument points to an empty string.

Example that uses catopen()


#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


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]