cs_locale

Description

Loads a CS_LOCALE structure with localization values or retrieve the locale name previously used to load a CS_LOCALE structure.

Syntax

CS_RETCODE cs_locale(context, action, locale, type,
                 buffer, buflen, outlen)
 
 CS_CONTEXT      *context;
 CS_INT                 action;
 CS_LOCALE         *locale;
 CS_INT                 type;
 CS_CHAR             *buffer;
 CS_INT                 buflen;
 CS_INT                 *outlen;

Parameters

context: A pointer to the CS_CONTEXT structure that represents the context in which the CS_LOCALE was allocated.

action

One of the following symbolic values:

Value of action	cs_locale
CS_SET	Loads the CS_LOCALE with new localization values.
CS_GET	Retrieves the locale name that was used to load the CS_LOCALE.

locale: A pointer to a CS_LOCALE structure. If action is CS_SET, cs_locale modifies this structure. If action is CS_GET, cs_locale examines the structure to determine the locale name that was previously used to load it.

type

One of the following symbolic values:

Value of type	Indicates
CS_LC_ALL	All types of localization information. CS_LC_ALL is “set only”; that is, action must be CS_SET when type is CS_LC_ALL.
CS_LC_COLLATE	The collating sequence (also called “sort order”). Open Client uses a collating sequence when sorting and comparing character data.
CS_LC_CTYPE	The character set. Open Client uses a character set when it converts to or from character datatypes.
CS_LC_MESSAGE	The language and character set to use for Open Client/Server and Adaptive Server error messages.
CS_LC_TIME	The language and character set to use when converting between datetime and character datatypes. CS_LC_TIME controls month names and abbreviations, datepart ordering, and whether the “am/pm” string is used.
CS_SYB_LANG, CS_SYB_CHARSET, CS_SYB_SORTORDER, CS_SYB_LANG_CHARSET	For information on these values, see “Using language, character set, and sort order names with cs_locale”.

WARNING! Open Server application programmers must set type to CS_LC_ALL when configuring the CS_LOCALE structure that applies to the Open Server application as a whole.

buffer

If action is CS_SET, buffer points to a character string that represents a locale name, a character set name, a language name, a sort order name, or a language/character set pair.

If action is CS_GET, buffer points to the space in which cs_locale will place a locale name, a character set name, a language name, a sort order name, or a language/character set pair. On output, all names are null-terminated. The buffer must be long enough for the name plus a null terminator.

buflen

The length, in bytes, of *buffer.

If action is CS_SET and the value in *buffer is null-terminated, pass buflen as CS_NULLTERM.

outlen

A pointer to an integer variable.

outlen is not used if action is CS_SET.

If action is CS_GET and outlen is supplied, cs_locale sets *outlen to the length, in bytes, of the locale name.

If the name is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the name.

If action is CS_SET or if an application does not require return length information, it can pass outlen as NULL.

Returns

cs_locale returns:

Returns	Indicates
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

Common reasons for a cs_locale failure include:

action is CS_SET and the *buffer locale name cannot be found in the Sybase locales file.
action is CS_GET and buflen indicates that the *buffer data space is too small.
Missing localization files.

Usage

cs_locale’s behavior depends on platform-specific configuration issues. You must read the localization chapter in the Open Client/Server Configuration Guide to obtain a full understanding of Client-Library’s localization mechanism. For a discussion of programming issues related to localization, see the Open Client/Server International Developer’s Guide.

cs_locale(CS_SET) loads a CS_LOCALE structure with localization values. cs_locale(CS_GET) retrieves current settings from the CS_LOCALE structure.
A locale name is a character string that represents a language/ character set/sort order combination. For example, the locale name “fr” might represent the language/character set/sort order combination “French, iso_1, binary.”
- Sybase predefines some locale names in the default locales file.
- A System Administrator can define additional locale names and add them to the Sybase locales file. The Open Client/Server Configuration Guide contains instructions for adding locale names.
For more information on localization, see the Open Client/Server International Developer’s Guide.

Loading a CS_LOCALE structure

An application needs to initialize, or “load,” a CS_LOCALE before using it to define custom localization values for a context, connection, or data element.
cs_locale(CS_SET) loads a CS_LOCALE structure with localization values. Any localization value can be specified by giving a locale name. Character sets, languages, and sort orders can also be specified directly by name.
When specifying a locale name, buffer must specify a name that corresponds to an entry in the Sybase locales file.

buffer can also be passed as NULL to specify the default locale. In this case, cs_locale searches the operating system for a locale name to use. If an appropriate locale name cannot be found in the operating system environment, cs_locale uses a platform-dependent default locale name.

The localization item(s) of interest are loaded based on the configuration of the locales file entry. For more information about the locales file and the cs_locale search process, see the Open Client/Server Configuration Guide.
For instructions for directly specifying character set, language, or sort order names, see “Using language, character set, and sort order names with cs_locale”.
After loading a CS_LOCALE with custom values, an application can:
- Call cs_config with property as CS_LOC_PROP to copy the custom localization values into a context structure.
- Call ct_con_props with property as CS_LOC_PROP to copy the custom localization values into a connection structure.
- Supply the CS_LOCALE as a parameter to a routine that accepts custom localization values (cs_dt_info, cs_strcmp, cs_time).
- Include the CS_LOCALE in a CS_DATAFMT structure describing a destination program variable (cs_convert, ct_bind).
Because cs_config copies locale information, an application can deallocate a CS_LOCALE structure after calling cs_config to set the CS_LOC_PROP property. Likewise, an application can deallocate a CS_LOCALE structure after calling ct_con_props to set the CS_LOC_PROP property. If a CS_DATAFMT structure uses a CS_LOCALE structure, however, the application must not deallocate the CS_LOCALE until the CS_DATAFMT no longer references it.
The first time a locale name is referenced, all localization information for the language, character set, and sort order that the locale name identifies is read from the environment and cached into *context. If this locale name is referenced again, cs_locale reads the information from the CS_CONTEXT instead of the environment.

Retrieving a locale name

An application can retrieve the locale name that was used to load a CS_LOCALE by calling cs_locale(CS_GET) with type as the type of localization information of interest and locale as a pointer to the CS_LOCALE structure.
cs_locale sets *buffer to a null-terminated character string representing the locale name that was used to load the CS_LOCALE.

Using language, character set, and sort order names with cs_locale

It is possible for an application to use language, character set, and sort order names, instead of a locale name, when calling cs_locale.

To use a language, character set, or sort order name, an application calls cs_locale with type as CS_SYB_LANG, CS_SYB_CHARSET, CS_SYB_SORTORDER, or CS_SYB_LANG_CHARSET. The following table summarizes cs_locale parameters for these values of type:

**Table 2-6: Using language, character set, and sort order names with cs_locale**
Value of type	action is	buffer is	cs_locale
CS_SYB_LANG	CS_SET	A pointer to a language name.	Loads the CS_LOCALE with the specified language information.
CS_SYB_LANG	CS_GET	A pointer to data space.	Places the current language name in *buffer. The name is null terminated.
CS_SYB_CHARSET	CS_SET	A pointer to a character set name.	Loads the CS_LOCALE with the specified character set information.
CS_SYB_CHARSET	CS_GET	A pointer to data space.	Places the current character set name in *buffer. The name is null terminated.
CS_SYB_SORTORDER	CS_SET	A pointer to a sort order name.	Loads the CS_LOCALE with the specified sort order information.
CS_SYB_SORTORDER	CS_GET	A pointer to data space.	Places the current sort order name in *buffer. The name is null terminated.
CS_SYB_LANG_CHARSET	CS_SET	A pointer to a string of the form language_name. character_set_name.	Loads the CS_LOCALE with the specified language and character set information.
CS_SYB_LANG_CHARSET	CS_GET	A pointer to data space.	Places a string of the form language_name.character_set_ name in *buffer. The string is null terminated.

The application must have previously loaded the CS_LOCALE structure with consistent information by calling cs_locale with type as CS_LC_ALL.
If an application specifies only a language name, then cs_locale uses the character set and sort order already specified in the preloaded CS_LOCALE structure.

If an application specifies only a character-set name, then cs_locale uses the language and sort order already specified in the preloaded CS_LOCALE structure.

If an application specifies only a sort-order name, then cs_locale uses the language and character set already specified in the preloaded CS_LOCALE structure.

If a language, character set, and sort-order combination is not valid, cs_locale returns CS_FAIL.
Valid language names correspond to subdirectories in the $SYBASE/locales directory. Valid character-set names correspond to subdirectories in the $SYBASE/charsets directory. Valid sort-order names for a character set correspond to file names, stripped of any suffix, in the $SYBASE/charsets/character_set_name directory.
If the required localization files for the requested language or character set do not exist, cs_locale returns CS_FAIL.