Opens a message catalog.

    Format

      #include  <nl_types.h>

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

1  –  Arguments

 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.

2  –  Description

    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

3  –  Return Values

    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.