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.

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 and Open 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.

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 and Open 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”.

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 and Open Server Configuration Guide for Microsoft Windows and Open Client and Open Server Configuration Guide for UNIX to obtain a full understanding of Client-Library’s localization mechanism. For a discussion of programming issues related to localization, see the Open Client and Open 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 and Open Server Configuration Guide for Microsoft Windows and Open Client and Open Server Configuration Guide for UNIX contains instructions for adding locale names.
For more information on localization, see the Open Client and Open 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 and Open Server Configuration Guide for your platform.

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-7: 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.