VMS Help
CRTL, catopen
*Conan The Librarian
|
Opens a message catalog.
Format
#include <nl_types.h>
nl_catd catopen (const char *name, int oflag);
name
The name of the message catalog to open.
oflag
An object of type int that determines whether the locale set for
the LC_MESSAGES category in the current program's locale or the
logical name LANG is used to search for the catalog file.
The catopen function opens the message catalog identified by
name.
If name contains a colon (:), a square opening bracket ([), or
an angle bracket (<), or is defined as a logical name, then it
is assumed that name is the complete file specification of the
catalog.
If it does not include these characters, catopen assumes that
name is a logical name pointing to an existing catalog file. If
name is not a logical name, then 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, or no message catalog can be opened in any of the
components specified by the NLSPATH, then the SYS$NLSPATH logical
name is used to search for a message catalog file.
Both NLSPATH and SYS$NLSPATH are comma-separated lists of
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
searched. 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 locale name.
The period (.) and at-sign (@) characters in the locale
name are replaced by an underscore (_) character.
For example, the "zh_CN.dechanzi@radical" locale name
results in a substitution of ZH_CN_DECHANZI_RADICAL.
%l Substitute the language part of the locale name. For
example, the language part of the en_GB.ISO8859-1 locale
name is en.
%t Substitute the territory part of the locale name. For
example, the territory part of the en_GB.ISO8859-1 locale
is GB.
%c Substitute the codeset name from the locale name. For
example, the codeset name of the en_GB.ISO8859-1 locale
name is ISO8859-1.
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.
Note also, that catopen uses the value of the LANG environment
variable without checking whether the program's locale can be set
using this value. That is, catopen does not check whether this
value can serve as a valid locale argument in the setlocale call.
If the substitution value is not defined, an empty string is
substituted.
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:
1. name (in the current directory)
2. name.cat (in the current directory)
3. SYS$COMMON:[SYSMSG.locale_name]name.cat
x A message catalog file descriptor. Indicates
the call was successful. This descriptor is
used in calls to catgets and catclose.
(nl_catd) -1 Indicates an error occurred. The function sets
errno to one of the following values:
o EACCES - Insufficient privilege or file
protection violation, or file currently
locked by another user.
o EMFILE - Process channel count exceeded.
o ENAMETOOLONG - The full file specification
for message catalog is too long
o ENOENT - Unable to find the requested
message catalog.
o ENOMEM - Insufficient memory available.
o ENOTDIR - Part of the name argument is not
a valid directory.
o EVMSERR - An error occurred that does not
match any errno value. Check the value of
vaxc$errno.