catopen

Opens a message catalog.

Format

#include  <nl_types.h>

nl_catd catopen  (const char *name, int oflag);

Arguments

name: The name of the message catalog to open.
oflag: An object of type int that determines whether the category LC_ MESSAGES or the logical name LANG is used to search for the catalog file.

Description

This function opens the message catalog identified by name. If name contains a colon (:), a square opening bracket ([), or an angle bracket (<), then it is assumed that name is the complete file specification of the catalog. If it does not include these characters, the logical name NLSPATH is used to define the file specification of the message catalog. NLSPATH is defined in the user's process. If the NLSPATH logical name is not defined, then the system-wide logical name SYS$NLSPATH is used to search for a message catalog file.

NLSPATH consists of one or more templates. The catopen function uses each template to construct a file specification. For example, NLSPATH could be defined as:

DEFINE NLSPATH SYS$SYSROOT:[SYS$I18N.MSG]%N.CAT,SYS$COMMON:[SYSMSG]%N.CAT

In this example, catopen first searches the directory SYS$SYSROOT:[SYS$I18N.MSG] for the named catalog. If the named catalog is not found there, the directory SYS$COMMON:[SYSMSG] is searced. The catalog name is constructed by substituting %N with the name passed to catopen, and adding the .cat suffix. %N is known as a substitution field. The following substitution fields are valid:

Field Meaning

%N Substitute the name passed to catopen

%L Substitute the name of the locale from the LANG environment variable or as defined for the LC_MESSAGES category of the current locale.
The period (.) and at-sign (@) characters in the specified name are replaced by an underscore (_) character.
For example, a locale name of "zh_CN.dechanzi@radical" results in a substitution of ZH_CN_DECHANZI_RADICAL.

%l [1] Substitute the language part of the locale name. For example, if the current locale is en_GB.ISO8859-1, then the language part is en.

%t [1] Substitute the territory part of the locale name. For example, if the current locale is en_GB.ISO8859-1, then the territory part is GB.

%c [1] Substitute the codeset name from the locale name. For example, if the current locale is en_ GB.ISO8859-1, then the codeset name is ISO8859-1.

[1] This substitution assumes that the locale name is of the form language_ territory.codeset@mode

Field	Meaning
%N	Substitute the name passed to catopen
%L	Substitute the name of the locale from the LANG environment variable or as defined for the LC_MESSAGES category of the current locale. The period (.) and at-sign (@) characters in the specified name are replaced by an underscore (_) character. For example, a locale name of "zh_CN.dechanzi@radical" results in a substitution of ZH_CN_DECHANZI_RADICAL.
%l [1]	Substitute the language part of the locale name. For example, if the current locale is en_GB.ISO8859-1, then the language part is en.
%t [1]	Substitute the territory part of the locale name. For example, if the current locale is en_GB.ISO8859-1, then the territory part is GB.
%c [1]	Substitute the codeset name from the locale name. For example, if the current locale is en_ GB.ISO8859-1, then the codeset name is ISO8859-1.
[1] This substitution assumes that the locale name is of the form language_ territory.codeset@mode

If the oflag argument is set to NL_CAT_LOCALE, then the current locale as defined for the LC_MESSAGES category is used to determine the substitution for the %L, %l, %t, and %c substitution fields. If the oflag argument is set to 0, then the value of the LANG environment variable is used as a locale name to determine the substitution for these fields. Note that using NL_ CAT_LOCALE conforms to the XPG4 specification while a value of 0 (zero) exists for the purpose of preserving XPG3 compatibility.

If the substitution value is not defined, an empty string is substituted.

Each template is separated by a comma (,). A leading comma or two adjacent commas (,,) is equivalent to specifying %N. For example,

DEFINE NLSPATH ",%N.CAT,SYS$COMMON:[SYSMSG.%L]%N.CAT"

In this example, catopen searches in the following locations in the order shown:

name (in the current directory)
name.cat (in the current directory)
SYS$COMMON:[SYSMSG.locale_name]name.cat

Return Values

x A message catalog file descriptor. Indicates the call was successful. This descriptor is used in calls to catgets and catopen.

(nl_catd) -1 Indicates an error occurred. The function sets errno to one of the following values:

EACCES - Insufficient privilege or file protection violation, or file currently locked by another user.
EMFILE - Process channel count exceeded.
ENAMETOOLONG - The full file specification for message catalogue is too long
ENOENT - Unable to find the requested message catalogue.
ENOMEM - Insufficient memory available.
ENOTDIR - Part of the name argument is not a valid directory.
EVMSERR - An error occurred that does not match any errno value. Check the value of vaxc$errno.

Previous Page | Next Page | Table of Contents | Index