### catopen -- Open Message Catalog

Format

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

Language Level: XPG4
catopen opens a message catalog specified by name, which must be done before you can retrieve a message. catopen then returns a message catalog descriptor for use on subsequent calls to catclose() and catgets(). The nl_catd data type, defined in the <nl_types.h> file, is used for catalog descriptors.

If the catalog file name contains a drive letter, or one or more slash (/) characters, the catalog file name is interpreted to be an absolute path name of the catalog to open.

In order for catopen to find your catalog, you must do one of the following:

1. specify an absolute path name; OR
2. define NLSPATH.

Otherwise, catopen will fail to find your catalog.

Note: The NLSPATH environment variable defines the directory search path for message catalogs.

If the value of oflag is NL_CAT_LOCALE, then the setting of the LC_MESSAGES environment variable may affect the search path. If the value of oflag is 0, then the LANG environment variable may affect the search path.

You can use two special variables, %N and %L, supported by the NLSPATH environment variable. The catalog name, referred to by the call that opens the message catalog, replaces the %N variable, and the value of the LC_MESSAGES category replaces the %L variable. However, if the value of oflag is 0, then the value of LANG replaces the %L variable.

On both OS/2 and Windows, the above implementation supports the following additional special variables:

%l | expands to the ISO 2-character language code
%t | expands to the ISO 2-character territory code
%c | expands to the code page (for example, IBM-850)

You can set the value of the LC_MESSAGES category 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 catopen specifies a catalog with the name mycmd, and the environment variables are set as follows,

>     NLSPATH=..\%N;.\%N;C:\language\message\%L\%N;c:\language\message\%N
>     LANG=fr_fr

then the application searches for the catalog in the following order:

1. ..\mycmd
2. .\mycmd
3. c:\language\message\fr_fr\mycmd
4. c:\language\message\mycmd

On Windows 95, it is necessary to double up the percents, for example, %%N.

If you omit the %N variable in a directory specification within the NLSPATH environment variable, the application assumes that the path defines a directory and searches for the catalog in that directory before searching the next specified path.

If you do not define the NLSPATH environment variable, then the current directory is used. If the LC_MESSAGES category is set to the default C locale (LC_MESSAGES=C), when oflag=NL_CAT_LOCALE, then %L expands to a NULL string. If the application does not explicitly set the locale (or the call to setlocale fails), then the LC_MESSAGES category will be "C". All the special variables whose values are derived from LC_MESSAGES will have a value of null string when the active locale is the C locale. The variables are %L, %l, %t, and %c.

On OS/2 and Windows, the 2-character ISO language code could be used to distinguish between different translations. For example, if NLSPATH is set to

> `\language\message\%l\%N`

then the application searches for the catalog in a subdirectory under \language\message. For example,

>     \language\message\fr\myprod.cat
>     \language\message\en\myprod.cat
>     \language\message\de\myprod.cat

If necessary, the ISO territory code could be used to distinguish between different translations for the same language. For example, if NLSPATH is set to

> `\language\message\%l%t\%N`

then the application searches for the catalog in a subdirectory under \language\message. For example,

>     \language\message\frca\myprod.cat
>     \language\message\frfr\myprod.cat

Finally, %c can be used to distinguish between code pages if necessary.

The message catalog descriptor will remain valid until it is closed by a call to catclose.

Return Value
If catopen opens the message catalog successfully, then a valid catalog descriptor (nl_catd) is returned. If catopen is unsuccessful, then it returns a NULL pointer.

catopen might fail under the following conditions. To indicate error, the value of errno may be set to:

ENOENT | The message catalog does not exist, or the name argument points to an empty string. Another possible cause is that the contents of the named file are not in the expected format.
ENOMEM | Insufficient storage space is available.
EACCES | Search permission is denied for the component of the path prefix of the message catalog, or read permission is denied for the message catalog.

Example

mkcatdef Command
gencat Command
runcat Command

catclose -- Close Message Catalog
catgets -- Read a Message
setlocale -- Set Locale
<nl_types.h>
NLSPATH Environment Variable