Informix Guide to GLS Functionality GLS Fundamentals

Informix products use GLS locales for the following tasks:

• When a client application requests a connection, the database server uses the client and database locales to determine if these locales are compatible.
• When a client application first begins execution, it compares the client and database locales to determine if it needs to perform code-set conversion.
• All Informix products that display product-specific messages look in a directory specific to the client locale to locate these messages.

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 Code Sets for Character Data.

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

• The default locale supports the default code set, which contains 8-bit characters for non-English characters such as é, ñ, and ö.

The name of the default code set depends on the platform on which your Informix product is installed. For more information on the default code set, The Default Code Set.

• Many nondefault locales support the default code set.

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

• Other nondefault locales, such as Japanese SJIS (ja_jp.sjis), Korean (ko_kr.ksc), and Chinese (zh_cn.gb), contain multibyte code sets.

For the contexts in which you can use non-ASCII characters, including multibyte characters, see Chapter 3, SQL Features, Chapter 4, Database Server Features, and Chapter 5, 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.

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.

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

• Locale information
• CLIENT_LOCALE

If CLIENT_LOCALE is not set, the client sets it to the default locale.

• DB_LOCALE

If DB_LOCALE is not set, the client does not send a DB_LOCALE value to the database server.

• User-customized end-user formats
• Date and time end-user formats: GL_DATE and GL_DATETIME
• Monetary end-user formats: DBMONEY

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 determine the following information:

• How are numeric and monetary values formatted?
• How are dates and times formatted?
• What database locale does the client expect?

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

To open an existing database, the client application must correctly identify the database locale for that database. To verify the database locale, the database server compares the following two locales:

• The locale specified by DB_LOCALE that the client application sends
• The database locale that is stored in the system catalog of the database that the client application requests

For more information, see The Database Locale.

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

• It sets the eighth character field of the SQLWARN array in the SQL Communications Area (SQLCA structure) to W as a warning flag. Values for W are ASCII 32 (blank) and ASCII 87 (W).
• It uses the database locale that is stored in the system catalog of the requested database as the database locale.

Warning: Check for the SQLWARN warning flag after your 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.

To check for the eighth character field of the SQLWARN array, an ESQL/C client application can check the sqlca.sqlwarn.sqlwarn7 field. If the sqlwarn7 field has a value of W, the database server has ignored the database locale that the client specified and has instead used the locale in the database as the database locale.

For more information on how to handle exceptions within an ESQL program, see the Informix ESQL/C Programmer's Manual.

Important: Array elements in SQLWARN arrays are numbered starting with zero in Informix ESQL/C, but starting with one in other languages. For Informix GLS tools that use 1-based counts on arrays, such as INFORMIX-4GL and Informix Dynamic 4GL, the warning character that Informix ESQL/C calls sqlca.sqlwarn.sqlwarn7 is called SQLCA.SQLAWARN[8].

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

• Locale information for the database

This database information includes the localized order and code set for data in columns with the locale-specific data types (NCHAR and NVARCHAR). The database server obtains this information from the name of the database locale that it has just verified.

• Locale information for client-application data

This client-application information provides the end-user formats for date, time, and monetary data. The database server obtains this information from the client application when the client requests a connection.

Tip: The database server uses the server locale, as specified by the SERVER_LOCAL environment variable, for read and write operations on its own operating-system files. For information about operating-system files, see GLS Support by Informix Database Servers.

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:

1. 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. If the client application does not send DB_LOCALE, the database server uses the DB_LOCALE that is set on the server computer.
2. For a new database, the database server uses the DB_LOCALE, which the client application has sent.

1. The locale that the DB_LOCALE environment variable on the server computer indicates
2. The default locale (U.S. English)

Dynamic Server uses the precedence of steps 1, 2, and 3 in the preceding list to obtain the database information for the server-processing locale. You are not required to set the other environment variables.

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 Locale Categories.

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.
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 locale (en_us.8859-1), 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 locale (fr_fr.8859-1), the database server must reestablish the server-processing locale. The database server sets the eighth character field of the SQLWARN array to W 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 locale (ja_jp.sjis) instead of one with a French locale, your client application would probably not continue with this connection because the locales are too different.

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 End-User Formats.

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)

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.

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

Tip: The precedence rules apply to how the database server determines the NUMERIC, MONETARY, TIME, and MESSAGES categories of the server-processing locale. For more information on these locale categories, see Locale Categories.

The client application passes the DBDATE, DBMONEY, DBTIME, GL_DATE, and GL_DATETIME 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.

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

Informix products use GLS locales to perform code-set conversion. Both an Informix client application and a database server might perform code-set conversion. For specific information, see Database Server Code-Set Conversion and Client Application Code-Set Conversion.

You specify a code set as part of the GLS locale. At runtime, Informix products adhere to the following rules to determine which code sets to use:

• The client application uses the client code set, which the CLIENT_LOCALE environment variable specifies, to write all files on the client computer and to interact with all client I/O devices.
• The database server uses the database code set, which the DB_LOCALE environment variable specifies, to transfer data to and from the database.
• The database server uses the server code set, which the SERVER_LOCALE environment variable specifies, to write files (such as debug and warning files).

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

• Code-set conversion is not a semantic translation.

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 written, regardless of how it is encoded.

• Code-set conversion does not create a character in the target code set if it exists only in the source code set.

For example, if the character â is passed to a target computer whose code set does not contain that character, the target computer cannot 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:

• Round-trip conversion

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.

• Substitution conversion

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.

• Graphical-replacement conversion

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.

• A hybrid of two or three of the preceding conversion methods

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.

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:

• Different operating systems might encode the same characters in different ways.

For example, the code for the character â (a-circumflex) in Windows Code Page 1252 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 g (gamma). This action occurs because the code for g is hexadecimal 0xE2 on the IBM UNIX computer.

• One language can have several code sets. Each might represent a subset of the language.

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:

• If the client locale and database locale specify different code sets, the client application performs code-set conversion so that the server computer is not loaded with this type of processing. For more information, see Client Application Code-Set Conversion.
• If the server locale and server-processing locale specify different code sets, the database server performs code-set conversion when it writes to and reads from operating-system files such as log files. For more information, see Database Server 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.

Informix Gateway products on UNIX use the GL_PATH environment variable to override the default locations for GLS code-set conversion tables. For details, see the Version 7.2 or later Informix Enterprise Gateway documentation.

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. The following table lists the subdirectory for each platform.

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