catopen - Opens a Specified Message Catalog

Syntax

#include <nl_types.h>

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

Description
The catopen subroutine opens a specified message catalog and returns a catalog descriptor used to retrieve messages from the catalog. The contents of the catalog descriptor are complete when the catgets function accesses the message catalog. The nl_catd data type is used for catalog descriptors. This data type is defined in the nl_types.h file.

If the catalog file name referred to by the CatalogName parameter contains a drive letter or a \, it is assumed to be an absolute pathname. That is, the catalog looked for following that path. If the catalog file name is not an absolute path name, the user environment determines which directory paths to search. The NLSPATH environment variable defines the directory search path.

Single-letter keywords for the NLSPATH are used as special variables as follows:

• N
  The value of the name parameter that is passed to catopen.
  %L
  The value of the category LC_MESSAGES.
  %l
  The language element of the category LC_MESSAGES.
  %t
  The territory element of the category LC_MESSAGES.
  %c
  The codeset element of the category LC_MESSAGES.
  %%
  A single '%' character.

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

  NLSPATH=..\%N;\%N;\system\nls\%L\%N;\system\nls\%NLANG=Fr_FR.IBM-850
  

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

  • mycmd
    
  • mycmd
    
  • system\nls\Fr_FR.IBM-850\mycmd
    
  • system\nls\mycmd

  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 the NLSPATH environment variable is not defined, the default path of . (current directory) is used.

  The parameters are:

  name

  Specifies the catalog file to open.
  oflag
  If the value of the oflag argument is 0, the LANG environment variable is used to locate the catalog without regard to the LC_MESSAGES category. If the oflag argument is NL_CAT_LOCALE, the LC_MESSAGES category is used to locate the message catalog.
Returns

The catopen subroutine returns a catalog descriptor.

If the catopen subroutine returns a value of CATD_ERR ( (nl_catd) -1), an error has occurred during creation of the nl_catd structure.

Example Code

#include <stdio.h>#include <nl_types.h>

void load_cat(char *tcat)
{
  nl_catd catd;                         /* Catalog descriptor. */

  if ((catd = catopen(tcat, 0)) == CATD_ERR)
  {
     printf("Unable to load specified catalog. \n");
     exit(1);
  }

  if (catclose(catd) == -1)
     printf("Error when trying to close catalog file\n");

}

Related Information

• setlocale
  
• catgets
  
• catclose

---

[Back: catgets - Retrieves a Message from a Catalog]
[Next: ceil - Find Integer >= Argument]