INFORMIX
Informix Guide to GLS Functionality
Chapter 1: GLS Fundamentals
Home Contents Index Master Index New Book

How Do Informix Products Use GLS Locales?

Informix products use GLS locales for the following tasks:

Supporting Non-ASCII Characters

An Informix product determines which code set it uses from the name of a GLS locale. Informix provides locales that support both single-byte and multibyte code sets. All code sets that Informix supports define the ASCII characters. Most also support additional non-ASCII characters (8-bit or multibyte characters). For more information on code sets and non-ASCII characters, see page 1-8.

The following types of GLS locales are examples of locales that contain non-ASCII characters in their code sets:

UNIX
    Nondefault locales that support the UNIX default code set, ISO8859-1, include British English (en_gb.8859-1), French (fr_fr.8859-1), Spanish (es_es.8859-1), and German (de_de.8859-1).

The following table summarizes contexts in which you can use non-ASCII characters, including multibyte characters.
Context for Non-ASCII Characters For More Information

SQL data

Chapter 3, "SQL Features"

Universal Server data

Chapter 4, "INFORMIX-Universal Server Features"

OnLine data

Chapter 5, "INFORMIX-OnLine Dynamic Server Features"

SE data

Chapter 6, "INFORMIX-SE Features"

SQL API data

Chapter 7, "General SQL API Features"

However, for an Informix product to support non-ASCII characters, it must use a locale that supports a code set with these same non-ASCII characters.

Establishing a Database Connection

When a client application requests a connection to a database, the database server uses GLS locales to perform the following steps:

    1. Examine the client locale information that the client passes.

    2. Verify that it can establish a connection between the client application and the database that it requested.

    3. Determine the server-processing locale, which the database server uses to handle locale-specific information for the connection.

Sending the Client Locale

When the client application requests a connection, it sends the following environment variables from the client locale to the database server:

      If CLIENT_LOCALE is not set (and DBNLS is not set), the client sets it to the default locale. If DB_LOCALE is not set (and DBNLS is not set), the client does not send a DB_LOCALE value to the database server.

      The client application sends the LC_* environment variables only if DBNLS is set. If DBNLS is set but the LC_* variables are not, the client sets the appropriate LC_* values, based on the LANG environment variable, and sends these LC_* values to the database server. The client application does not send the value of the LANG environment variable to the database server.

      A Version 5.x ALS client application can send DBCODESET to a Version 7.2 database server; the database server converts the DBCODESET value to a valid locale name and uses it as DB_LOCALE. A Version 6.x ALS client application sends the CLIENT_LOCALE and DB_LOCALE environment variables.

    If you do not set any of these environment variables, the client application does not send them to the database server, and the database server uses the end-user formats that the client locale defines.

The database server uses this information to verify the database locale and to establish the server-processing locale.

Verifying the Database Locale

To open an existing database, the client application must correctly identify the database locale for the database(s) that it needs to access. The database server verifies the database locale from the information that the client sends when it requests a database server connection. To perform this verification, the database server compares the following two database locales:

Two database locales match if their language, territory, code set, and any optional locale modifiers are the same. If these database locales do not match, the database server performs the following actions:

Warning: Check for the SQLWARN7 warning flag after your ESQL client application requests a connection. If the two database locales do not match, the client application might incorrectly interpret data that it retrieves from the database, or the database server might incorrectly interpret data that it receives from the client. If you proceed with such a connection, it is your responsibility to understand the format of the data that is being exchanged.
For example, suppose your client application uses CLIENT_LOCALE set to en_us.1252 and DB_LOCALE set to en_us.8859-1 and then opens a database with the French fr_fr.8859-1 locale. The database server sets SQLWARN7 because the languages and territories of the two locales are different. The database server then uses the locale of the database (fr_fr.8859-1) for the localized order of the data.

However, your application might choose to use this connection. It might be acceptable for the application to receive the NCHAR and NVARCHAR data that is sorted in a French localized order. Any code-set conversion that the client application performs would still be valid because both database locales support the ISO8859-1 code set. (For more information on code-set conversion, see page 1-40.)

Instead, if the application opens a database with the Japanese SJIS (ja_jp.sjis) locale, the database server sets the SQLWARN7 flag because the language, territory, and code sets differ. The database server then uses the ja_jp.sjis locale for the localized order of the data.Your application would probably not continue with this connection. Because the code sets are different, the client application would not perform code-set conversion correctly.

NLS
If DBNLS is set to one (1), the database server does not allow the client to connect to a database if the database locale that the client sends does not match the database locale of the NLS database that the client requested.

Determining the Server-Processing Locale

The database server uses the server-processing locale to obtain locale information for its own internal sessions and for any connections. When the database server begins execution, it initializes the server-processing locale to the default locale. When a client application requests a connection, the database server must redetermine the server-processing locale to include the client and database locales. The database server uses the server-processing locale to obtain locale information that it needs when it transfers data between the client and database.

Once the Informix database server verifies the database locale (see page 1-33), it uses a precedence of environment variables from the client and database locales to set the server-processing locale. Figure 1-3 shows the relationship between the client locale, database locale, server locale, and server-processing locale.

Figure 1-3
The Server-Processing Locale

The database server obtains the following information from the server-processing locale:

Tip: The database server uses the server locale for read and write operations on its own operating-system files. For information about operating-system files, see "Using the Server Locale" for Universal Server, page 5-3 for OnLine, and page 6-3 for SE.

Locale Information for the Database
The database server must know how to interpret the data in any columns with the locale-specific data types, NCHAR and NVARCHAR. To handle this locale-specific data correctly, the database server must know the localized order for the collation of the data and the code set of the data. In addition, the database server uses the code set of the database locale as the code set of the server-processing locale. The database server might have to perform code-set conversion between the code sets of the server-processing locale and the server locale. For more information, see "Performing Code-Set Conversion".

The database server uses the following precedence to determine this database information:

    1. The locale that the database server uses to determine the database information for the server-processing locale depends on the state of the database to which the client application requests a connection, as follows: a. For a connection to an existing database, the database server uses the database information from the database locale that it obtains when it verifies the database locale (see page 1-33). If the client application does not send DB_LOCALE, the database server uses the DB_LOCALE that is set on the server computer.

    b. For a new database, the database server uses the DB_LOCALE, which the client application has sent (see page 1-32).

    NLS
    2. LC_COLLATE and LC_CTYPE environment variables that the client application passes (if DBNLS is set on the client computer)

    3. The locale that the DB_LOCALE environment variable on the server computer indicates

    NLS
    4. LC_COLLATE and LC_CTYPE environment variables on the server computer (if DBNLS is set on the client computer)

    5. LANG environment variable on the server computer (if DBNLS is set on the client)

    ALS
    6. DBCODESET environment variable that the client application passes

    7. DBCODESET environment variable on the server computer (if DBCODESET is not set on the client computer)

    8. The default locale (U.S. English)

Informix Version 9.1 database servers use the precedence of steps , 3, and 8 in the preceding list to obtain the database information for the server-processing locale. You are not required to set the other environment variables.

NLS
Support for LANG and the LC_* environment variables provides backward compatibility for client applications that are based on Informix NLS products. These applications use the precedence of steps
2, 4, 5, and 8 in the preceding list. You are not required to set CLIENT_LOCALE for NLS-based applications. However, CLIENT_LOCALE does provide certain advantages to your application. For more information, see the Informix Migration Guide.

ALS
Support for the DBCODESET environment variable provides backward compatibility for client applications that are based on Informix Version 5.x ALS products. These applications use the precedence of steps
, 3, 6, 7, and 8 in the preceding list. For more information about how to run ALS-based applications, see the Informix Migration Guide.

Tip: The precedence rules apply to how the database server determines both the COLLATION category and the CTYPE category of the server-processing locale. For more information on these locale categories, see page A-4.
For more information on how the database server obtains these environment variables, see "Sending the Client Locale".

If the client application makes another request to open a database, the database server must reestablish the database information for the server-processing locale, as follows:

    1. Reverify the database locale by comparing the database locale in the database to be opened with the value of the DB_LOCALE environment variable from the client application (see page 1-33).

    2. Reestablish the server-processing locale with the newly verified database locale (from the preceding step).

For example, suppose that your client application has DB_LOCALE set to en_us.8859-1 (U.S. English with the ISO8859-1 code set). The client application then opens a database with the U.S. English (en_us.8859-1) locale, and the database server establishes a server-processing locale with en_us.8859-1 as the locale that defines the database information.

If the client application now closes the U.S. English database and opens another database, one with the French (fr_fr.8859-1) locale, the database server must reestablish the server-processing locale. The database server sets the SQLWARN7 flag to indicate that the two locales are different. However, your client application might choose to use this connection because both these locales support the ISO8859-1 code set. If the client application opens a database with the Japanese SJIS (ja_jp.sjis) locale instead of one with a French locale, your client application would probably not continue with this connection because the locales are too different.

Locale Information For the Client Application
The database server must know how to interpret the end-user formats when they appear in monetary, date, or time data that the client application sends. It must also convert data from the database to any appropriate end-user format before it sends this data to the client application. (For more information about end-user formats, see page 1-12.)

The database server uses the following precedence to determine this client-application information:

    1. DBDATE and DBTIME environment variables for the date and time end-user formats and DBMONEY for the monetary end-user formats (if one of these is set on the client)

    2. GL_DATE and GL_DATETIME environment variables (if one of these is set on the client) for the date and time end-user formats

    3. The locale that the CLIENT_LOCALE environment variable from the client application indicates (see page 1-32)

    NLS
    4. If DBNLS is set on the client computer (for an NLS-based application):
    a. LC_MONETARY, LC_NUMERIC, and LC_TIME environment variables that the client application passes to define end-user formats of monetary, numeric, and date/time data, respectively

    b. LC_MONETARY, LC_NUMERIC, and LC_TIME environment variables on the server computer for the end-user formats of monetary, numeric, and date/time data, respectively

    c. LANG environment variable on the server computer

    ALS
    5. DBCODESET environment variable that the client passes

    6. The default locale (U.S. English)

Informix Version 9.1 database servers use the precedence of steps 2, 3, and 6 in the preceding list to set the end-user formats for the server-processing locale. You are not required to set the other environment variables. Support for DBDATE and DBTIME provides backward compatibility for client applications that are based on earlier versions of Informix products. Informix recommends that you use GL_DATE and GL_DATETIME for new applications.

NLS
Support for LANG and the LC_* environment variables provides backward compatibility for client applications that are based on Informix NLS products. If DBNLS is set on the client, these applications use the precedence of steps
, 4, and 6 in the preceding list to set the end-user formats for the server- processing locale. You are not required to set CLIENT_LOCALE for NLS-based applications. However, CLIENT_LOCALE does provide certain advantages to your application. For more information, see the Informix Migration Guide.

ALS
Support for the DBCODESET environment variable provides backward compatibility for client applications that are based on Informix Version 5.x ALS products. These applications use the precedence of steps
, 3, 5, and 6 in the preceding list. For more information about how to run ALS-based applications, see the Informix Migration Guide.

Tip: The precedence rules apply to how the database server determines the NUMERIC MONETARY, TIME, and the MESSAGES categories of the server-processing locale. For more information on these locale categories, see page A-4.
The client application passes the DBCODESET, DBDATE, DBMONEY, DBTIME, GL_DATE, GL_DATETIME, and LC_* environment variables (if they are set) to the database server. It also passes the CLIENT_LOCALE and DB_LOCALE environment variables. For more information, see "Sending the Client Locale".

Performing Code-Set Conversion

Informix products use GLS locales to perform code-set conversion. Both an Informix client application and a database server might perform code-set conversion. This section provides the following information about how Informix products support code-set conversion:

What Is Code-Set Conversion?

You specify a code set as part of the GLS locale (see page 1-20). At runtime, Informix products adhere to the following rules to determine which code sets to use:

In a client/server environment, character data might need to be converted from one code set to another if the client or server computer uses different code sets to represent the same characters. The conversion of character data from one code set (the source code set) to another (the target code set) is called code-set conversion. Without code-set conversion, one computer cannot correctly process or display character data that originates on the other (when the two computers use different code sets).

Code-set conversion does not provide either of the following capabilities:

    It does not convert between words in different languages. For example, it does not convert from the English word yes to the French word oui. It only ensures that each character retains its meaning when it is processed or printed, regardless of how it is encoded.

    For example, if the character â is passed to a target computer whose code set does not contain that character, the target computer can never process or print the character exactly.

For each character in the source code set, a corresponding character in the target code set should exist. However, if the source code set contains characters that are not in the target code set, the conversion must then define how to map these mismatched characters to the target code set. (Absence of a mapping between a character in the source and target code sets is often called a lossy error.) If all characters in the source code set exist in the target code set, mismatch handling does not apply.

A code-set conversion uses one of the following four methods to handle mismatched characters:

    This method maps each mismatched character to a unique character in the target code set so that the return mapping maps the original character back to itself. This method guarantees that a two-way conversion results in no loss of information; however, data that is converted just one way might prevent correct processing or printing on the target computer.

    This method maps all mismatched characters to one character in the target code set that highlights mismatched characters. This method guarantees that a one-way conversion clearly shows the mismatched characters; however, a two-way conversion results in loss of information if mismatched characters are present.

    This method maps each mismatched character to a character in the target code set that looks similar to the source character. (This method includes the mapping of one-character ligatures to their two-character equivalents and vice versa.) This method tries to make printing of mismatched data more accurate on the target computer, but it most likely confuses the processing of this data on the target computer.

Tip: Each code-set-conversion source file (.cv) indicates how the associated conversion handles mismatched characters. For information on code-set-conversion files, see Appendix A, "Managing GLS Files."

When Is Code-Set Conversion Performed?

An application needs to use code-set conversion only when the two code sets (client and server-processing locale, or server-processing locale and server) are different. The following situations are possible causes of code sets that differ:

    For example, the code for the character â (a-circumflex) in Windows Code Page 1252 (a common Microsoft code set) is hexadecimal 0xE2. In IBM Coded Character Set Identifier (CCSID) 437 (a common IBM UNIX code set), the code is hexadecimal 0x83. If the code for â on the client is sent unchanged to the IBM UNIX computer, it prints as the Greek character (gamma). This action occurs because the code for is hexadecimal 0xE2 on the IBM UNIX computer.

    For example, the code sets ccdc and big5 are both internal representations of a subset of the Chinese language. However, these subsets consist of different numbers of Chinese characters.

Tip: The IBM CCSID code-set numbers are a system of 16-bit numbers that uniquely identify the coded graphic character representations. Informix products support the CCSID numbering system. For more information, see Appendix A, "Managing GLS Files."
If a code-set conversion is required when data goes from computer A to computer B, it is also required when the data goes from computer B to computer A.

In the client/server environment, the following situations might require code-set conversion:

In Figure 1-4, the black dots indicate the two points in a client/server environment at which code-set conversion might occur.

Figure 1-4
Points of GLS Code-Set Conversion

In the sample connection that Figure 1-4 shows, the ESQL/C client application performs code-set conversion on the data that it sends to and receives from the database server if the client and database code sets are convertible. The Informix database server also performs code-set conversion when it writes to a message-log file if the code sets of the server locale and server-processing locale are convertible.

NLS
Informix products provide operating-system locales for backward compatibility with NLS databases. (For information on how to list operating-system locales, see
Appendix A, "Managing GLS Files.") If your NLS-based client application (DBNLS is set) uses an operating-system locale for either the client or the database locale, your NLS-based application does not automatically perform code-set conversion. For code-set conversion to occur, you must set the DBAPICODE environment variable. For more information, see the Informix Migration Guide.

Client Application Code-Set Conversion
An Informix client application automatically performs code-set conversion between the client and database code sets when the following conditions are true:

When the client application begins execution, it compares the names of the client and database locales to determine whether to perform code-set conversion. If the CLIENT_LOCALE and DB_LOCALE environment variables are set, the client application uses these locale names to determine the client and database code sets, respectively. If CLIENT_LOCALE is not set (and DBNLS is not set), the client application assumes that the client locale is the default locale. If DB_LOCALE is not set (and DBNLS is not set), the client application assumes that the database locale is the same as the client locale (the value of CLIENT_LOCALE).

NLS
If DBNLS is set on the client application, the client application is to connect to an NLS database server. This client application still performs code-set conversion between the code sets that the CLIENT_LOCALE and DB_LOCALE environment variables indicate. However, if you set DB_LOCALE and not CLIENT_LOCALE, the client application performs code-set conversion between the client code set, which the LC_CTYPE environment variable indicates (or LANG, if LC_CTYPE is not set), and the database code set, which DB_LOCALE indicates.

ALS
If the Version 9.1 client application is to connect to a Version 6.0 ALS database server, it sets CLIENT_LOCALE and DB_LOCALE to indicate the client and database locales. This client application still performs code-set conversion between the code sets that the CLIENT_LOCALE and DB_LOCALE environment variables indicate. If the Version 9.1 client application is to connect to a Version 5.x ALS database server, you must set CLIENT_LOCALE and DB_LOCALE to indicate the client and database code sets. In this case, the Version 9.1 client application performs code-set conversion between these two code sets.

If the client and database code sets are the same, then no code-set conversion is needed. However, if the code sets do not match, the client application must determine whether the two code sets are convertible. Two code sets are convertible if the client can locate the associated code-set-conversion files. These code-set-conversion files must exist on the client computer.

UNIX
You can use the glfiles utility to obtain a list of code-set conversions that your Informix product supports. For more information, see
"The glfiles Utility".

Windows
You can examine the %INFORMIXDIR%\gls\cvY directory to determine the GLS code-set conversions that your Informix product supports. For more information on this directory, see
Appendix A.

If no code-set-conversion files exist, the client application generates a run-time error when it starts up to indicate that the code sets are incompatible. If these code-set-conversion files exist, the client application automatically performs code-set conversion when it sends data to or receives data from the database server.

When a client application performs code-set conversion, it makes the following assumptions:

Warning: Check for the SQLWARN7 warning flag after each request for a connection. If the two database locales do not match, the client application might be performing code-set conversion incorrectly. The client application continues to perform any code-set conversion based on the code set that DB_LOCALE supports. If you proceed with such a connection, it is your responsibility to understand the format of the data that is being exchanged.
For example, suppose your client application has CLIENT_LOCALE set to en_us.1252 and DB_LOCALE set to en_us.8859-1. The client application determines that it must perform code-set conversion between the Microsoft 1252 code set (in the client locale) and the ISO8859-1 code set (in the database locale). The client application then opens a database with the French fr_fr.8859-1 locale. The database server sets SQLWARN7 and uses the locale of the database (fr_fr.8859-1) for the localized order of the data. However, your application might choose to use this connection. The code-set conversion that the client application performs would still be valid because both database locales support the ISO8859-1 code set.

Instead, if the application opens a database with the Japanese SJIS (ja_jp.sjis) locale, the database server sets the SQLWARN7 flag and uses the ja_jp.sjis locale for the localized order of the data.Your application would probably not continue with this connection. When the client application started, it determined that code-set conversion was required between the Microsoft 1252 and ISO8859-1 code sets. The client application performs this code-set conversion until it terminates. When you open a database with the ja_jp.sjis, the client application would perform code-set conversion incorrectly. It would continue to convert between Microsoft 1252 and ISO8859-1 instead of between Microsoft 1252 and Japanese SJIS. This situation could lead to serious corruption of data.

Database Server Code-Set Conversion
An Informix database server automatically performs code-set conversion between the code sets of the server-processing locale and the server when the following conditions are true:

For a list of files for which Informix database servers perform code-set conversion, see "Using the Server Locale" for the Universal Server database server, page 5-3 for the OnLine database server, and page 6-3 for the SE database server. For information on GLS code-set conversion files, see page A-14.

Which Data Is Converted?

When the code sets of two locales differ, an Informix product must use code-set conversion to prevent data corruption of character data. Code-set conversion converts the following types of character data:

Tip: If your ESQL/C client application uses code-set conversion, you might need to take special programming steps. For more information, see "Handling Code-Set Conversion".

Locating Message Files

Informix products use GLS locales to locate product-specific message files. By default, Informix products automatically search a subdirectory that is associated with the client locale for the product-specific message files.

UNIX
Informix products search the $INFORMIXDIR/msg/lg_tr/code_set directory.

Windows
Informix products search the %INFORMIXDIR%\msg\lg_tr\code_set directory.

In this path, lg and tr are the language and territory, respectively, from the name of the client locale, and code_set is the condensed form of the code-set name. For more information about condensed code-set names, see "Locale-File Subdirectories".

Informix products use a precedence of environment variables to locate product-specific message files. The DBLANG environment variable lets you override the client locale, as the location of message files that Informix products use. You might use DBLANG to specify a directory where the message files reside for each locale that your environment supports. For more information, see the entry for DBLANG in Chapter 2, "GLS Environment Variables."




Informix Guide to GLS Functionality, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.