Opens a specified message catalog.
#include <nl_types.h>
nl_catd catopen (CatalogName, Parameter) const char *CatalogName; int Parameter;
The catopen subroutine opens a specified message catalog and returns a catalog descriptor used to retrieve messages from the catalog. The contents of the catalog descriptor are complete when the catgets subroutine accesses the message catalog. The nl_catd data type is used for catalog descriptors and is defined in the nl_types.h file.
If the catalog file name referred to by the CatalogName parameter contains a leading / (slash), it is assumed to be an absolute path name. If the catalog file name is not an absolute path name, the user environment determines which directory paths to search. The NLSPATH environment variable defines the directory search path. When this variable is used, the setlocale subroutine must be called before the catopen subroutine.
A message catalog descriptor remains valid in a process until that process or a successful call to one of the exec functions closes it.
You can use two special variables, %N and %L, in the NLSPATH environment variable. The %N variable is replaced by the catalog name referred to by the call that opens the message catalog. The %L variable is replaced by the value of the LC_MESSAGES category.
The value of the LC_MESSAGES category can be set by specifying values for the LANG, LC_ALL, or LC_MESSAGES environment variable. The value of the LC_MESSAGES category indicates which locale-specific directory to search for message catalogs. For example, if the catopen subroutine specifies a catalog with the name mycmd, and the environment variables are set as follows:
NLSPATH=../%N:./%N:/system/nls/%L/%N:/system/nls/%N LANG=fr_FR
then the application searches for the catalog in the following order:
../mycmd ./mycmd /system/nls/fr_FR/mycmd /system/nls/mycmd
If you omit the %N variable in a directory specification within the NLSPATH environment variable, the application assumes that it defines a catalog name and opens it as such and will not traverse the rest of the search path.
If the NLSPATH environment variable is not defined, the catopen subroutine uses the default path. See the /etc/environment file for the NLSPATH default path. If the LC_MESSAGES category is set to the default value C, and the LC__FASTMSG environment variable is set to true, then subsequent calls to the catgets subroutine generate pointers to the program-supplied default text.
The catopen subroutine treats the first file it finds as a message file. If you specify a non-message file in a NLSPATH, for example, /usr/bin/ls, catopen treats /usr/bin/ls as a message catalog. Thus no messages are found and default messages are returned. If you specify /tmp in a NLSPATH, /tmp is opened and searched for messages and default messages are displayed.
The catopen subroutine returns a catalog descriptor. If the LC_MESSAGES category is set to the default value C, and the LC__FASTMSG environment variable is set to true, the catopen subroutine returns a value of -1.
If the LC_MESSAGES category is not set to the default value C but the catopen subroutine returns a value of -1, an error has occurred during creation of the structure of the nl_catd data type or the catalog name referred to by the CatalogName parameter does not exist.
This subroutine is part of Base Operating System (BOS) Runtime.
The catclose subroutine, catgets subroutine, exec subroutines, setlocale subroutine.
The environment file.
For more information about the Message Facility, see the Message Facility Overview for Programming in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.
For more information about subroutines and libraries, see the Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.