informix
Informix Guide to GLS Functionality
GLS Environment Variables

GLS-Related Environment Variables

This section lists the GLS-related environment variables that you can set for Informix database servers and SQL API products.

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 Enterprise Gateway documentation.

CC8BITLEVEL

The value of the CC8BITLEVEL environment variable determines the type of processing that the ESQL/C filter, esqlmf, performs on non-ASCII (8-bit and multibyte) characters. For information about esqlmf, see Generating Non-ASCII Filenames.
Element Purpose
0 The esqlmf filter converts all non-ASCII characters in literal strings and comments to octal constants (for C compilers that do not support these uses of non-ASCII characters).
1 The esqlmf filter converts non-ASCII characters in literal strings to octal constants but allows them in comments (some C compilers do support non-ASCII characters in comments).
2 The esqlmf filter allows non-ASCII characters in literal strings and ensures that all the bytes in the non-ASCII characters have the eighth bit set (for C compilers with this requirement).
3 The esqlmf filter does not filter non-ASCII characters (for C compilers that support multibyte characters in literal strings and comments).

To invoke esqlmf each time that you process an ESQL/C file with the esql command, set the ESQLMF environment variable to 1. If you do not set CC8BITLEVEL, the esql command assumes a value for CC8BITLEVEL of 0.

Important: For ESQLMF to take effect, do not set CC8BITLEVEL to 3.

CLIENT_LOCALE

The CLIENT_LOCALE environment variable specifies the client locale, which the client application uses to perform read and write operations, as well as for other uses such as determining end-user formats and processing ESQL statements. For information about the client locale, see The Client Locale.
Element Purpose
code_set Name of the code set that the locale supports
language Two-character name that represents the language for a specific locale
modifier Optional locale modifier that has a maximum of four alphanumeric characters. This specification modifies the cultural-convention settings that the language and territory settings imply. The modifier usually indicates a special type of localized order that the locale supports. For example, you can set @modifier to specify dictionary or telephone-book collation order.
territory Two-character name that represents the cultural conventions For example, territory might specify the Swiss version of the French, German, or Italian language.

A sample nondefault client locale for a French-Canadian locale follows:

You can use the glfiles utility to generate a list of the GLS locales that are available on your UNIX system. For more information, see The glfiles Utility.

If you do not set CLIENT_LOCALE, the client application uses the default locale, U.S. English, as the client locale.

Changes to CLIENT_LOCALE also enter in the Windows NT registry database under HKEY_LOCAL_MACHINE.

DBDATE

Informix products support DBDATE for compatibility with earlier products. Informix recommends that you use the GL_DATE environment variable for new applications.

The DBDATE environment variable specifies the end-user formats of values in DATE columns. For information about end-user formats, see End-User Formats.

Important: DBDATE is evaluated at system initialization time. If it is invalid, the system initialization fails.

Important: The setting of the DBDATE variable takes precedence over that of the GL_DATE environment variable, as well as over the default DATE formats that CLIENT_LOCALE specifies.

DBLANG

The DBLANG environment variable specifies the subdirectory of INFORMIXDIR that contains the customized, language-specific message files that an Informix product uses.

Element Purpose
relative_path Subdirectory of the Informix installation directory (which INFORMIXDIR specifies)
full_path Full pathname of the directory that contains the compiled message files
locale_name Name of a GLS locale that has the format lg_tr.code_set, where lg is a two-character name that represents the language for a specific locale, tr is a two-character name that represents the cultural conventions, and code_set is the name of the code set that the locale supports

Informix products locate product-specific message files in the following order:

  1. If DBLANG is set to a full_path: the directory that full_name indicates

  2. If DBLANG is set to a relative_path:

  1. In $INFORMIXDIR/msg/$DBLANG on UNIX or %INFORMIXDIR%\msg\%DBLANG% on Windows NT
    2.
  2. In $INFORMIXDIR/$DBLANG on UNIX or %INFORMIXDIR%\%DBLANG% on Windows NT

  1. If DBLANG is set to a locale_name: the msg subdirectory for the locale in $INFORMIXDIR/msg/lg_tr/code_set on UNIX systems or %INFORMIXDIR%\msg\lg_tr\code_set on Windows NT, where lg, tr, and code_set are the language, territory, and code set, respectively, in locale_name.

    2. The value of DBLANG does not affect the messages that the database server writes to its message log. The database server obtains the locale for these messages from the SERVER_LOCALE environment variable.

  2. If DBLANG is not set: the msg subdirectory for the locale in $INFORMIXDIR/msg/lg_tr/code_set on UNIX systems or %INFORMIXDIR%\msg\lg_tr\code_set on Windows NT, where lg and tr are the language and territory, respectively, from the locale that is associated with the Informix product, and code_set is the condensed name of the code set that the locale supports:

  3. If DBLANG, CLIENT_LOCALE, and LANG are not set:

  1. In $INFORMIXDIR/msg/en_us/0333 on UNIX systems or %INFORMIXDIR%\msg\en_us\0333 on Windows NT, an internal message directory for the default locale
  2. In $INFORMIXDIR/msg on UNIX systems or %INFORMIXDIR%\msg on Windows NT, the default Informix message directories

The compiled message files have the .iem file extension.

DB_LOCALE

The DB_LOCALE environment variable specifies the database locale, which the database server uses to handle locale-sensitive data types (NCHAR, NVARCHAR) of the database. For information about the database locale, see The Database Locale.
Element Purpose
code_set Name of the code set that the locale supports
language Two-character name that represents the language for a specific locale
modifier Optional locale modifier that has a maximum of four alphanumeric characters This specification modifies the cultural-convention settings that the language and territory settings imply. The modifier usually indicates a special type of localized order that the locale supports. For example, you can set @modifier to specify dictionary or telephone-book collation order.
territory Two-character name that represents the cultural conventions For example, territory might specify the Swiss version of the French, German, or Italian language.

A sample nondefault database locale for a French-Canadian locale follows:

You can use the glfiles utility to generate a list of the GLS locales that are available on your UNIX system. For more information, see The glfiles Utility.

For client applications, if you do not set DB_LOCALE on the client computer, the client applications assume that the database locale is the value of the CLIENT_LOCALE environment variable. However, the client application does not send this assumed value to the database server when it requests a connection.

Changes to DB_LOCALE also enter in the Windows NT registry database under HKEY_LOCAL_MACHINE.

DBMONEY

The DBMONEY environment variable specifies the end-user formats for values in MONEY columns. For information about end-user formats, see End-User Formats.

With this environment variable, you can set the following currency notation:

For example, suppose you set DBMONEY as follows:

This value sets the following currency notation:

In the default locale, the currency symbol is the dollar sign ($), and it appears at the front of the monetary values. The period (.) is the decimal separator, and the comma (,) is the thousands separator. The currency notation that you specify with DBMONEY takes precedence over the currency notation that the locale defines. For more information, see Customizing Monetary Values.

DBTIME

Informix products support DBTIME for compatibility with earlier products. Informix recommends that you use the GL_DATETIME environment variable for new applications.

The DBTIME environment variable specifies the end-user formats of values in DATETIME columns for SQL API routines. For information about end-user formats, see End-User Formats.

Tip: The DBTIME environment variable affects only certain DATETIME and INTERVAL formatting routines in the ESQL/C function libraries. For information about how these library functions are affected, refer to DATETIME-Format Functions.

ESQLMF

The ESQLMF environment variable indicates whether the esql command automatically invokes the ESQL/C multibyte filter, esqlmf.

Element Purpose
0 The esql command compiles existing source code whose non-ASCII characters have already been converted.
1 The esql command invokes esqlmf to filter multibyte characters as part of the preprocessing for an ESQL/C source file.

The value of the CC8BITLEVEL environment variable determines the type of filtering that esqlmf performs. For information about esqlmf, see Generating Non-ASCII Filenames.

Important: For ESQLMF to take effect, CC8BITLEVEL must not be set to 3.

If you want to compile existing source code whose non-ASCII characters have already been converted, either set ESQLMF to 0 or do not set it. In either case, esql does not invoke esqlmf.

GLS8BITFSYS

Use the GLS8BITFSYS environment variable to tell Informix products (such as the ESQL/C processor) whether the operating system is 8-bit clean. This environment variable determines whether an Informix product can use non-ASCII characters in the filename of an operating-system file that it generates.

Element Purpose
0 Informix products assume that the operating system is not 8-bit clean and generate filenames with 7-bit ASCII characters only.
1 Informix products assume that the operating system is 8-bit clean and can use non-ASCII characters (8-bit or multibyte characters) in the filename of an operating-system file that it generates.

If you include non-ASCII characters in a filename that you specify from within a client application, you must ensure that the code set of the server-processing locale supports these non-ASCII characters. If you do not set GLS8BITFSYS, Informix database servers behave as if GLS8BITFSYS is set to 1.

For example, create a database that is called A1A2B1B2, where A1A2 and B1B2 are multibyte characters, with the following SQL statement:

If GLS8BITFSYS is 1 (or is not set) on the server computer, the database server assumes that the operating system is 8-bit clean, and it generates a database directory, A1A2B1B2.dbs.

If GLS8BITFSYS is set to 0 on the server computer and you include non-ASCII characters in the filename, the Informix product uses an internal algorithm to convert these non-ASCII characters to ASCII characters. The filenames that result are 7-bit clean.

Filenames with invalid byte sequences generate errors when they are used with GLS-based products.

Only some database utilities, such as dbexport, and the compilers for Informix ESQL/C products use GLS8BITFSYS on the client computer to create and use files. For example, suppose you compile an ESQL/C source file that is called A1A2B1B2.ec, where A1A2 and B1B2 are multibyte characters. If GLS8BITFSYS is set to 1 (or is not set) on the client computer, the ESQL/C processor generates an intermediate C file that is called A1A2B1B2.c. For a list of ESQL/C files that check GLS8BITFSYS, see Handling Non-ASCII Characters.

Restrictions on Non-ASCII Filenames

If your locale supports a code set with non-ASCII characters, restrictions apply to filenames for operating-system files that Informix products generate. Before you or an Informix product creates a file and assigns a filename, consider the following questions:

Making Sure That Your Operating System Is 8-Bit Clean

To support non-ASCII characters in filenames, your operating system must be 8-bit clean. An operating system is 8-bit clean if it reads the eighth bit as part of the code value. In other words, the operating system must not ignore or make its own interpretation of the value of the eighth bit.

Informix recommends that you consult your operating-system manual or system administrator to determine whether your operating system is 8-bit clean before you decide to use a nondefault locale that contains non-ASCII characters in filenames that Informix products use and generate.

Making Sure That Your Product Supports the Same Code Set

Once an Informix product has generated an operating-system file whose filename has non-ASCII characters, it has written that filename and the file contents in a particular code set. Whenever an Informix product or client application needs to access that file, you must ensure that the product uses a server-processing locale that supports that same code set.

The Server Code Set

When the database server creates a file whose filename contains non-ASCII characters, the server locale must support these non-ASCII characters. Before you start a database server, you must set the SERVER_LOCALE environment variable to the name of a locale whose code set contains these non-ASCII characters.

For example, suppose you want a message log with the UNIX path /A1A2B1B2/C1C2D1D2, where A1A2, B1B2, C1C2, and D1D2 are multibyte characters in the Japanese SJIS code set.

To enable the database server to create this message-log file on the server computer:

  1. Modify the MSGPATH configuration parameter in the ONCONFIG file.

    2. For UNIX:

    For Windows NT:

  2. Set the SERVER_LOCALE environment variable on the server computer to the Japanese SJIS locale, ja_jp.sjis.

  3. Start the database server with the oninit utility.

When the database server initializes, it assumes that the operating system is 8-bit clean and creates the /A1A2B1B2/C1C2D1D2 message log on UNIX, or the \A1A2B1B2\C1C2D1D2 file on Windows NT.

The Client Code Set

When an ESQL/C processor creates a file whose filename has non-ASCII characters, the client locale must support these non-ASCII characters. Before you start an Informix database server, you must ensure that the code set of the client locale (the client code set) contains these characters. When you use a nondefault locale, you must set the CLIENT_LOCALE environment variable to the name of a locale whose code set contains these non-ASCII characters.

For example, suppose you want to process an ESQL/C source file with the path /A1A2B1B2/C1C2D1D2 , where A1A2, B1B2, C1C2, and D1D2 are multibyte characters in the Japanese SJIS code set. You must perform the following steps to enable the esql command to create the intermediate C source file on the client computer:

  1. Set the CLIENT_LOCALE environment variable on the client computer to the Japanese SJIS locale, ja_jp.sjis.

  2. Process the ESQL/C source file with the esql command.

If the code sets that are associated with the filename and with the client locale do not match, a valid filename might contain illegal characters with respect to the client locale. The ESQL/C processor rejects any filename that contains illegal characters and displays the following error message:

GL_DATE

The GL_DATE environment variable specifies end-user formats of values for DATE columns. For information about end-user formats, see End-User Formats.

Important: GL_DATE is evaluated when it is used. If it is invalid, the operations that called it fail.

An end-user format in GL_DATE can contain the following characters:

The following list describes the formatting directives that are not based on era.

Formatting Directives Description
%a Is replaced by the abbreviated weekday name as defined in the locale.
%A Is replaced by the full weekday name as defined in the locale.
%b Is replaced by the abbreviated month name as defined in the locale.
%B Is replaced by the full month name as defined in the locale.
%C Is replaced by the century number (the year divided by 100 and truncated to an integer) as an integer (00 through 99).
%d Is replaced by the day of the month as an integer (01 through 31). A single digit is preceded by a zero (0).
%D Is the same as the %m/%d/%y format.
%e Is replaced by the day of the month as a number (1 through 31). A single digit is preceded by a space.
%h Is the same as the %b formatting directive.
%iy Is replaced by the year as a 2-digit number (00 through 99) for both reading and printing. It is the Informix specific formatting directive for %y.
%iY Is replaced by the year as a 4-digit number (0000 through 9999) for both reading and printing. It is the Informix-specific formatting directive for %Y.
%m Is replaced by the month as a number (01 through 12).
%n Is replaced by a newline character.
%t Is replaced by the TAB character.
%w Is replaced by the weekday as a number (0 through 6); 0 represents the locale equivalent of Sunday.
%x Is replaced by a special date representation that the locale defines.
%y Requires that the year be a 2-digit number (00 through 99) for both reading and printing.
%Y Requires that the year be a 4-digit number (0000 through 9999) for both reading and printing.
%% Is replaced by % (to allow % in the format string).

White-space or other nonalphanumeric characters must appear between any two formatting directives. For example, if you use a U.S. English locale, you might want to format an internal DATE value for 03/05/1997 in the ASCII string format that the following example shows:

To do so, set the GL_DATE environment variable as follows:

If a GL_DATE format does not correspond to any of the valid formatting directives, the behavior of the Informix product when it tries to format is undefined.

Important: The setting of the DBDATE variable takes precedence over that of the GL_DATE environment variable, as well as over the default DATE formats that CLIENT_LOCALE specifies.

The Year Formatting Directives

You can use the following formatting directives in the end-user format of the GL_DATE environment variable to format the year of a date string: %y, %iy, %Y, and %iY. The %iy and %iY formatting directives provide compatibility with the Y2 and Y4 year specifiers of the DBDATE environment variable.

When an Informix product uses an end-user format to print an internal date value as a string, the %iy and %iY formatting directives perform the same task as %y and %Y, respectively. To print a year with one of these formatting directives, an Informix product performs the following actions:

When an Informix product uses an end-user format to read a date, the %iy and %iY formatting directives perform differently from %y and %Y, respectively. The following table summarizes how the year formatting directives behave when an Informix product uses them to read date strings.

GL_DATE Format Date String to Read
'1994 03 06' '94 03 06'
%y %m %d Error Internal date for 1994 03 06
%iy %m %d Internal date for 1994 03 06 Internal date for 1994 03 06
%Y %m %d Internal date for 1994 03 06 Internal date for 0094 03 06
%iY %m %d Internal date for 1994 03 06 Internal date for 1994 03 06

In a read of a date string, the %iy and %y formatting directives both prefix the first two digits of the current year to expand any 1-digit or 2-digit year. However, you can set the DBCENTURY environment variable to change this assumption.

For information about end-user formats, see End-User Formats.

Alternative Date Formats

To support alternative date formats in an end-user format, GL_DATE accepts the following conversion modifiers:

The following table shows date-formatting directives that support conversion modifiers.

Alternative Date Format Description
%EC Accepts either the full or the abbreviated era name for reading; for printing, %EC is replaced by the full name of the base year (period) of the era that the locale defines (same as %C if locale does not define an era).
%Eg Accepts either the full or the abbreviated era name for reading; for printing, %Eg is replaced by the abbreviated name of the base year (period) of the era that the locale defines (same as %C if locale does not define an era).
%Ex Is replaced by a special date representation for an era that the locale defines (same as %x if locale does not define an era).
%Ey Is replaced by the offset from %EC of the era that the locale defines. This date is the era year only (same as %y if locale does not define an era).
%EY Is replaced by the full era year, which the locale defines (same as %Y if locale does not define an era).
%Od Is replaced by the day of the month in the alternative digits that the locale defines (same as %d if locale does not define alternative digits).
%Oe Is the same as %Od (same as %e if locale does not define alternative digits).
%Om Is replaced by the month in the alternative digits that the locale defines (same as %m if locale does not define alternative digits).
%Ow Is replaced by the weekday as a single-digit number (0 through 6) in the alternative digits that the locale defines (same as %w if locale does not define alternative digits). The equivalent of zero (0) represents the locale equivalent of Sunday.
%Oy Is replaced by the year as a 2-digit number (00 through 99) in the alternative digits that the locale defines (same as %y if locale does not define alternative digits). For information about how to format a year value, see the description of %y.
%OY Is the same as %EY (same as %Y if locale does not define alternative digits).

The TIME category of the locale defines the following era information:

The NUMERIC category of the locale defines the alternative digits for a locale (which the %Ox formatting directives use).

Optional Date Format Qualifiers

You can specify the following optional format qualifiers immediately after the % symbol of the formatting directive. A date format qualifier defines a field specification for the date that the Informix product reads or prints. The following sections describe what a field specification means for the read and print operations. For information about end-user formats, see End-User Formats.

Tip: The GL_DATETIME environment variable accepts these date format qualifiers in addition to those that Optional Time Format Qualifiers lists. Field Specification for a Reading DATE Values

When an Informix product uses an end-user format to read a date string, the field specification defines the number of characters to expect as input. This field specification has the following syntax.

Element Purpose
- (minus sign) Indicates that the field value is left justified and begins with a digit; this value can include trailing spaces
0 (zero) Indicates that the field value is right justified and any zeros on the left are pad characters; they are not significant.
max_width Integer that indicates the maximum number of characters to read
min_width Integer that indicates the minimum number of characters to read

The first character of the field specification indicates whether to assume that the field value is justified or padded. If the first character is neither a minus sign nor a zero, the Informix product assumes that the field value is right justified and any spaces on the left are pad characters. However, if the field value begins with a zero, it cannot include pad characters.

An Informix product ignores the field specification if the field value is not a numeric value.

Field Specification for Displaying DATE Values

When an Informix product uses an end-user format to print a date string, the field specification defines the number of characters to print as output. The syntax for the field specification is as follows.

Element Purpose
- (minus sign) Indicates that the field value is left justified and begins with a digit; this value can include trailing spaces
0 (zero) Indicates that the field value is right justified and any zeros on the left are pad characters; they are not significant.
width Integer that indicates a minimum field width for the printed value
precision Integer that indicates the precision to use for the field value

The meaning of the precision value depends on the particular formatting