GL_USEGLU environment variable

The GL_USEGLU environment variable enables GLS for Unicode (GLU). You must use the GL_USEGLU environment variable if you use NCHAR or NVARCHAR data types that require localized collation.

Read syntax diagramSkip visual syntax diagram
>>-GL_USEGLU--1------------------------------------------------><

A value of 1 enables GLS for Unicode (GLU). The database server and GLS-enabled Informix® client applications will use the Unicode collation with the International Components for Unicode (ICU) libraries instead of the default GLS libraries. The ICU libraries take the locale into account when collating Unicode (UTF-8) characters, the GLS libraries do not.
Note: GL_USEGLU can be set to 1 or 4. On setting the variable, restart the Informix instance. It affects the databases with a locale encoding of either gb18030-2000 or utf8.
  0 or unset. 1 4
CTYPE support Unicode BMP Unicode provided by ICU Unicode provided by ICU
Collation Code set order Unicode collation algorithm provided by ICU Code set order
Compatibility with other server side GL_USEGLU values when databases were created 0, unset or 4 1 4

If you do not enable the GL_USEGLU environment variable, the default GLS libraries are used, and locales are not taken into account when collating Unicode (UTF-8) characters.

Requirements

Within a database instance, all UTF-8 databases must be created with GL_USEGLU set, or they must all be created without GL_USEGLU set. Do not create some UTF-8 databases with GL_USEGLU set and others without it set.

The clients and server must be at the same GLS version and level of libraries. To avoid inconsistencies, follow these guidelines:
  • Install the server in a separate location from the clients. If the server and clients are collocated, even if the GLS version is the same, the libraries might be at a different level and you risk overwriting the latest level with an older one.
  • Do not modify or move the libraries.

The environment must be configured for nondefault locales. You must set the DB_LOCALE, CLIENT_LOCALE, and SERVER_LOCALE environment variables. If you do not set DB_LOCALE, the CLIENT_LOCALE value is used by default when a client tries to connect to the database.

The GL_USEGLU environment variable requires a minimum of 64 KB of virtual shared memory (stack size). The STACKSIZE configuration parameter in the onconfig file is set to 64 KB or higher.

Usage

Important: To prevent server and collation problems, it is crucial to set the GL_USEGLU environment variable correctly. The same Unicode collation must be used for the database, the server, and the client application environment, respectively.
  • Set the GL_USEGLU environment variable before you start the server.
  • Set the GL_USEGLU environment variable before you create a database in which you plan to store UTF-8 character data. Databases that are created before the environment variable is set will use the default GLS libraries, which do not support Unicode collation.
  • After you create the database with the GL_USEGLU environment variable set, always set the environment variable when you start the instance.
  • Set the GL_USEGLU environment variable in the client environment. The variable enables Unicode collation by ESQL/C client applications, and for other client APIs that require compilation. It initializes conversion routines that enable Unicode collation by the server in databases that use UTF-8 character encoding, including the Chinese GB18030-2000 code set. For example, if the GL_USEGLU environment variable was set to 1 when the server was started, the SET COLLATION statement of SQL can enable localized collation for a nondefault Unicode locale, such as sh_hr.utf8, which supports the Serbo-Croatian language. Exceptions:
    • For ESQL/C applications, an alternative to setting the GL_USEGLU environment variable is to compile with the -glu flags of the esql command when linking the ESQL/C program.
    • JDBC applications that support UTF-8 character encoding do not require the GL_USEGLU environment variable to be set. However, setting the variable does not interfere with JDBC operations in Unicode locales. The environment variable has no effect on JDBC client applications, including applications that use the IBM® Informix JSON compatibility wire protocol listener.
  • During migration, ensure that the GL_USEGLU environment variable is set on the source server and on the target server.

You can check the settings in your environment with the following commands or queries.

To identify the environment setting:
  • If the instance is online, run the onstat -g env command to check what locale is used for the server startup environment. Add the session number to the command to check the locale for a particular session: onstat -g env session_number.
  • If the instance is offline, check the startup environment scripts, if they exist.
To determine whether the database is a Unicode database:
Run the following query, where database_name is the actual name of your database. Enter the command as one line.
select * from sysdbslocale where dbs_dbsname = 'database_name'
To determine the exact locale of the database:
Connect to the database, and then run the following query:
SELECT site from systables where tabid=90

Example 1: Create a Unicode database

Assume that you want to create an American English database. You are using KSH and the dbaccess utility. The instance exists, but is offline.

  1. Enable GLS for Unicode in the instance startup environment.
    export GL_USEGLU=1
  2. Start the server.
    oninit 
  3. Verify that the GL_USEGLU environment variable is set.
    onstat -g env
  4. Set the database locale to American English.
    export DB_LOCALE=en_us.utf8
  5. Create a database.
    echo "create database uni_example with log" | dbaccess sysmaster

Example 2: Create a Unicode database that requires International Language Supplement (ILS)

Assume that you want to create a Slovak database. You are using KSH and the dbaccess utility. The instance exists, and is offline.

Important: The following steps require Informix 11.50.xC8 or later versions. If you use an earlier version of Informix, the collation order that is returned does not match what is expected from a database that was created with sk_sk.8859-2.
  1. Enable GLS for Unicode in the instance startup environment.
    export GL_USEGLU=1
  2. Start the instance.
    oninit 
  3. Verify that the following command shows GL_USEGLU enabled in the environment.
    onstat -g env
  4. Set the database locale to sk_sk.utf8.
    export DB_LOCALE=sk_sk.utf8
  5. Set the client locale to sk_sk.utf8.
    export CLIENT_LOCALE=sk_sk.utf8
  6. Install the International Language Support (ILS) package, and choose the files that are necessary to use sk_sk.utf8 as the database locale.
  7. Create a database called sk_example, and in it a table called sk_table that contains NCHAR data types.
    echo "create database sk_example with log" | dbaccess sysmaster
    echo "create table sk_table (cc nchar(5))" | dbaccess sk_example
  8. Load the Slovak character code point.
    echo "insert into sk_table ('Ž')" | dbaccess sk_example
  9. Run the following query to select the data in order:
    echo "select cc from sk_table order by cc" | dbaccess sk_example

Troubleshooting

If Unicode produces index keys that are too long to fit in the default dbspace page size, use a larger, nondefault page size.

Use the following information to troubleshoot and diagnose problems with your GLS for Unicode configuration. This list is not a complete list of potential error messages, and the error messages that are shown might occur due to other reasons.

-103 ISAM error: illegal key descriptor (too many parts or too long)
This error can occur if an application attempts to connect to a Unicode database that was created with the GL_USEGLU environment variable set to 1, but the GL_USEGLU environment variable is not set or is set to 4 at the instance level, or vice versa.
Solution:
  1. Bring the instance offline.
  2. Set the GL_USEGLU environment variable to the appropriate value in the startup environment.
  3. Bring the instance back online.
-23101 Unable to load locale categories
This error can occur when you attempt to start a database.
Solution:
  • Check that INFORMIXDIR is set to the correct installation directory path.
  • Check that CLIENT_LOCALE and DB_LOCALE are set correctly.
  • If CLIENT_LOCALE and DB_LOCALE reference locales that belong to the International Language Supplement (ILS), make sure that appropriate ILS files exist in the correct location: $INFORMIXDIR/gls/lc11.
  • Check that GL_USEGLU is set in the client environment for an application.
-23103 Code-set conversion function failed due to an illegal sequence or invalid value. Illegal or invalid characters occur in the character string. The program could not execute the code-set conversion on the characters that this string contains.
This error can occur when you try to insert data.
Solution:
  1. Examine the input string for illegal or invalid characters.
  2. Rerun the program.
-23104 Error opening required code-set conversion object file. No object code-set conversion (definition) file exists for the two given code sets.
This client error can occur when the client tries to connect to a database.
Solution:
  • Check that the DB_LOCALE and CLIENT_LOCALE environment variables are set to the correct value.
  • Check that the object conversion files (.cvo extension) exist in $INFORMIXDIR/gls/cv9.
-23197 Database locale information mismatch. The code set of the DB_LOCALE is not equal to the database locale.
This client error can occur when the client tries to connect to a database.
Solution:
  • Set the DB_LOCALE environment variable to the same locale for the client and the database. (If you do not set DB_LOCALE, the CLIENT_LOCALE value is used by default.)
  • For distributed queries, ensure that the databases use the same code set. For example, this error occurs if database 1 uses en_us.8859-1 and database 2 uses en_us.cp1252.