Open System Services Library Calls Reference Manual (G06.27+, H06.04+)

catopen(3) OSS Library Calls Reference Manual

NAME

catopen - Opens a speciﬁed message catalog

LIBRARY

G-series native OSS processes: /G/system/sysnn/zcrtlsrl

H-series OSS processes: /G/system/zdllnnn/zcrtldll

SYNOPSIS

#include <nl_types.h>

nl_catd catopen(

const char *name,

int oﬂag);

PARAMETERS

name Speciﬁes the catalog ﬁle to open.

oflag Speciﬁes if the LANG or LC_MESSAGES environment variable is used to

locate the catalog.

DESCRIPTION

The catopen( ) function opens a speciﬁed message catalog and returns a catalog descriptor that is

used to retrieve messages from the catalog.

The name parameter speciﬁes the name of the message catalog to be opened. If name contains a

/ (slash), then name speciﬁes a full pathname for the message catalog. Otherwise, the environ-

ment variable NLSPATH is used with substitutions based on the value of the name parameter

and the value of the LC_MESSAGES locale category. NLSPATH is a colon-separated list of

pathnames. The catopen( ) function makes variable substitutions in each pathname and attempts

to open the speciﬁed catalog. If the open succeeds, it returns the catalog descriptor for that cata-

log. If the open does not succeed, the catopen( ) function attempts to open the next pathname in

the value of the NLSPATH environment variable.

If NLSPATH does not exist in the environment, then the following system default for

NLSPATH is used: /usr/lib/nls/msg/%L/%N.

If no message catalog can be opened in any of the components speciﬁed by NLSPATH, then

catopen() returns a value of -1 cast to (nl_catd). This is not a valid catalog descriptor and

causes subsequent calls to catgets() to return a pointer to the default message string.

The following lists the meanings of the variables in the NLSPATH environment variable.

%N The value passed in the name parameter

%L The current locale name deﬁned for the LC_MESSAGES category, for example,

fr_BE.ISO8859-1.

%l The language element of the current locale name, for example, fr.

%t The territory element from the current locale name, for example, BE.

%c The code set element from the current locale name, for example, ISO8859-1.

%% A single % (percent sign) character.

If the oﬂag parameter is set to 0, then the LANG environment variable is used to locate the mes-

sage catalog. If the oﬂag is set to 1 (or NL_CAT_LOCALE which is deﬁned as 1 in the

nl_types.h header ﬁle), the LC_MESSAGES environment variable is used.

For example, if the catopen( ) function speciﬁes a catalog with the name mycmd.cat, and the

environment variables are set as follows:

1−36 Hewlett-Packard Company 527187-004