OpenCatalogA

open a message catalog. (V38)

OpenCatalog

varargs stub for OpenCatalogA(). (V38)

This function opens a message catalog. Catalogs contain all the text strings that an application uses. These strings can easily be replaced by strings in a different language, which causes the application to magically start operating in that new language.

Catalogs originally come from disk files. This function searches for them in the following places:

where languageName is the name of the language associated with the locale parameter. So assuming an application called WizPaint:

Passing NULL as first parameter to OpenCatalog() indicates you wish to use the system's default locale. Assuming the default locale specifies "deutsch" as language, OpenCatalog() tries to open the catalog as:

and if that file is not found, then OpenCatalog() tries to open it as:

PROGDIR:

is not always checked before LOCALE: is. If the volume which

PROGDIR:

is assigned to is NOT currently mounted, and if the one

which LOCALE: is assigned to IS mounted, then LOCALE: is checked first, followed by PROGDIR: if needed. This is done in order to minimize the number of disk swaps on floppy systems.

The OC_BuiltInLanguage tag specifies the language of the strings that are built into the application. If the language of the built-in strings matches that of the locale, then no catalog need be loaded from disk and the built-in strings can be used directly.

locale.library caches text catalogs in order to minimize disk access. As such, OpenCatalog() may or may not cause disk access. This fact should be taken into consideration. Unused catalogs are automatically flushed from the system when there is not enough memory. When there is disk access, it is possible a DOS requester may be opened asking for a volume to be inserted. You can avoid this requester opening by setting your process' pr_WindowPtr field to -1.

locale

The locale for which the catalog should be opened, or NULL. When NULL, then the system's default locale is used. This should generally be NULL

name

The NULL-terminated name of the catalog to open, typically the application name with a ".catalog" extension

tagList

Pointer to an array of tags providing optional extra parameters, or NULL

OC_BuiltInLanguage (STRPTR)

Language of built-in strings of the application. That is, this tag identifies the language used for the "defaultString" parameter used in the GetCatalogStr() function. Default is "english". Providing this tag and setting its value to NULL indicates that there are no built-in strings.

OC_BuiltInCodeSet (ULONG)

Code set of built-in strings. Default is 0. THIS TAG SHOULD ALWAYS BE SET TO 0 FOR NOW.

OC_Language (STRPTR)

Language explicitly requested for the catalog. A catalog of this language will be returned if possible, otherwise a catalog in one of the user's preferred languages. This tag should normally not be provided as it overrides the user's preferences.

OC_Version (UWORD)

Catalog version number required. Default is 0 which means to accept any version of the catalog that is found. Note that if a version is specified, the catalog's version must match it exactly. This is different from version numbers used by OpenLibrary().

catalog

A message catalog to use with GetCatalogStr() or NULL. A NULL result does not necessarily indicate an error. If OpenCatalog() determines that the built-in strings of the application can be used instead of an external catalog from disk, then NULL is returned. To determine whether a NULL result actually indicates an error, look at the return value of dos.library/IoErr(). 0 means no error.

GetCatalogStr() interprets a NULL catalog as meaning to use the built-in strings.

In most cases, failing to open a catalog should not be considered a fatal error, and the application should continue operating and simply use the built-in set of strings instead of the disk-based catalog. Note that GetCatalogStr() accepts a NULL catalog pointer for this very reason.

Also note that displaying an error message when a catalog fails to open can be a meaningless endeavor as the message is likely in a language the user does not understand.

Short of media read errors or failing to open a catalog file practically no kind of error, such as corrupted catalog file contents, will be reported if a catalog fails to open.

CloseCatalog(), GetCatalogStr()