catopen() — Open Message Catalog

Format

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

Language Level: XPG4

Threadsafe: Yes.

Locale Sensitive: The behavior of this function might be affected by the LC_MESSAGES 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 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 is used. The default path might be affected by the setting of the LANG environment variable; if the NL_CAT_LOCALE flag is set in the oflag parameter or if the LANG environment variable is not set, the default path might be affected by the LC_MESSAGES locale category.

Three values can be specified for the oflag parameter: NL_CAT_LOCALE, NL_CAT_JOB_MODE, and NL_CAT_CTYPE_MODE. NL_CAT_JOB_MODE and NL_CAT_CTYPE_MODE are mutually exclusive. If the NL_CAT_JOB_MODE and NL_CAT_CTYPE_MODE flags are both set in the oflag parameter, the catopen() function will fail with a return value of CATD_ERR.

If you want the catalog messages to be converted to the job CCSID before they are returned by the catgets() function, set the parameter to NL_CAT_JOB_MODE. If you want the catalog messages to be converted to the LC_CTYPE CCSID before they are returned by catgets(), set the parameter to NL_CAT_CTYPE_MODE. If you do not set the parameter to NL_CAT_JOB_MODE or NL_CAT_CTYPE_MODE, the messages are returned without conversion and are in the CCSID of the message file.

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 might invalidate existing open message catalogs.

Note:

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 can 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 | Contents | Index ]