INFORMIX
Informix Guide to GLS Functionality
Chapter 2: GLS Environment Variables
Home Contents Index Master Index New Book

GLS-Related Environment Variables

 Figure 2-1 shows an alphabetical list of the GLS-related environment variables that you can set for Informix database servers and SQL API products. These environment variables are described in this chapter on the pages that are listed in the last column set.
Environment Variable Restrictions Page

Figure 2-1
GLS-Related Environment Variables

CC8BITLEVEL

ESQL/C only

2-5

CLIENT_LOCALE

2-6

DBDATE

2-7

DBLANG

2-15

DB_LOCALE

2-17

DBMONEY

2-19

DBTIME

SQL APIs only

2-20

ESQLMF

ESQL/C only

2-22

GLS8BITFSYS

2-23

GL_DATE

2-25

GL_DATETIME

2-34

SERVER_LOCALE

2-41

Informix products support many other non-GLS environment variables. For a complete description of these environment variables, refer to Chapter 4 of the Informix Guide to SQL: Reference.

CC8BITLEVEL

The CC8BITLEVEL environment variable indicates the ability of your C-language compiler to process non-ASCII (8-bit and multibyte) characters.

The value of the CC8BITLEVEL environment variable determines the type of processing that the ESQL/C filter, esqlmf, performs on non-ASCII characters. The following values are possible:

0

tells the esqlmf filter to convert 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

tells the esqlmf filter to convert non-ASCII characters in literal strings to octal constants but allow them in comments (some C compilers do support non-ASCII characters in comments).

2

tells the esqlmf filter to allow non-ASCII characters in literal strings and ensure that all the bytes in the non-ASCII characters have the eighth bit set (for C compilers with this requirement).

3

indicates that the esqlmf filter does not need to 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 (see page 2-22). 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.
For more information on the actions that esqlmf takes, see "The esqlmf Filter".

CLIENT_LOCALE

The CLIENT_LOCALE environment variable specifies the client locale, which the client application uses to perform read and write operations on the client computer. (For information about the client locale, see page 1-23.)

Informix products use the CLIENT_LOCALE environment variable for the following purposes:

If you do not set CLIENT_LOCALE (and DBNLS is also not set), the client application uses the default locale, U.S. English, as the client locale.

DBDATE

The DBDATE environment variable specifies the end-user formats of values in DATE columns.For more information on end-user formats, see page 1-12.

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

ALS
Informix products support the era-based extensions in DBDATE for backward compatibility with Informix ALS products. Informix recommends that you use the GL_DATE environment variable (see page 2-25) for date end-user formats in new client applications.

For a description of the standard DBDATE formats and general information about this environment variable, refer to Chapter 4 of the Informix Guide to SQL: Reference. This section describes the era-based (Asian) formats that DBDATE supports. For more information on era-based dates, see "Era-Based Date and Time Formats".

Era-Based DBDATE Formats

The DBDATE environment variable supports special extensions that format values in DATE columns as era-based date strings. The following diagram shows the syntax of the era-based date DBDATE formats.

For DBDATE to format era-based dates, you must have a client locale that supports eras. The CLIENT_LOCALE environment variable must specify the name of a locale that defines era information. If the client locale does not support eras, Informix products ignore these era-based formats.

Tip: Era-based date formats can also appear in the date-format strings of certain ESQL library functions. For more information, see "Extended DATE-Format Strings".
ALS
ALS 6.0 Era-Based Format

The ALS 6.0 Era-Based Format syntax for DBDATE provides backward compatibility with Informix ALS Version 6.0 products.

The G and E era-year modifiers appear as a prefix to the year specifier to indicate how to format an era, as follows:

The following table shows some sample era-based DBDATE formats that are compatible with Informix ALS Version 6.0 products. In this table, the sample outputs for these formats assume that the client locale is Japanese SJIS (ja_jp.sjis).
Description DBDATE Setting October 5, 1990 appears as:

Format with abbreviated era name

GY2MD/

MDGY2.

GY2MD0

GY4DM/

H02/10/05

10.05.H02

H021005

H0002/05/10

Format with full era name

EY2MD/

MDEY20

EY2DM.

EY4MD/

EY4DM-

A1A202/10/05

1002A1A202

A1A202.05.10

A1A20002/10/05

A1A20002-05-10

In the preceding table, A1A2 is a multibyte character in the Japanese SJIS code set that represents the full era name. The H is an ASCII character that represents the abbreviated era name. The Japanese SJIS locale (ja_jp.sjis) defines these era names.

ALS 5.0 Era-Based Format

The ALS 5.0 Era-Based Format syntax for DBDATE provides backward compatibility with Informix ALS Version 5.0 products.

The C1, J1, and J2 era-year modifiers appear as an extension, at the end of the DBDATE format. They indicate how to format an era, as follows:

The following table shows some sample era-based DBDATE formats that are compatible with Informix ALS Version 5.0 products. In this table, the sample outputs for the Japanese Imperial era assume that the locale is ja_jp.sjis (Japanese SJIS). The Taiwanese Ming Guo dates assume a zh_tw.big5 locale.
Description DBDATE Setting October 5, 1990 appears as:

Japanese Imperial era

Y2MD-J1

Y4MD/J1

Y2MD/J2

Y4MD/J2

DMY4J2

H02-10-05

H0002/10/05

A1A202/10/05

A1A20002/10/05

05/10/A1A20002

Taiwanese Ming Guo date

Y2MD/C1

Y4MD/C1

DMY4.C1

79/10/05

0079/10/05

05.10.0079

ALS 4.0 Era-Based Format

The ALS 4.0 Era-Based Format syntax for DBDATE provides backward compatibility with Ascii Corporation Version 4.0 Asian products.

The following table shows some sample era-based DBDATE formats that are compatible with Ascii Corporation 4.0 products. In this table, the sample outputs for these formats assume that the locale is Japanese (ja_jp.sjis).
Description DBDATE Setting October 5, 1990 appears as:

Japanese Imperial era

NYMD/

NYYMD/

MDNYY/

NY2MD/

NY2DM-

H02/10/05

H02/10/05

10/05/H02

H02/10/05

H02-05-10

Scanning and Printing Era-Based Formats

For an Informix product to scan a date string that contains an era-based date, it expects the DBDATE environment variable to specify the era-based format of the value to scan. Suppose that you set DBDATE to the following end-user format:

An Informix product uses this era-based DBDATE format to interpret a date string that it must convert to an internal DATE value as follows:

For an Informix product to print a date string that contains an era-based date, it expects DBDATE to indicate the era-based format of the value to print. With DBDATE set as in the previous example, an Informix product uses this end-user format to convert an internal DATE value to an era-based date string as follows:

Tip: The DBDATE environment variable supports only the slash (/), period (.), and minus (-) as date separators. To specify some other character, including non-ASCII characters, as a date separator, use the GL_DATE environment variable.
For more information on the scan and print operations, see "End-User Formats".

DBLANG

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

relative_path

is the subdirectory of the Informix installation directory (that INFORMIXDIR specifies).

full_path

 is the full pathname of the directory that contains the compiled message files.
locale_name

 is the 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.

Tip: For a detailed description of the syntax of DBLANG, see the "Informix Guide to SQL: Reference."
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: a. In $INFORMIXDIR/msg/$DBLANG

    b. In $INFORMIXDIR/$DBLANG

    3. If DBLANG is set to a locale_name: the msg subdirectory for the locale in $INFORMIXDIR/msg/lg_tr/code_set, where lg, tr, and code_set are the language, territory, and code set, respectively, in locale_name.

    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.

    4. If DBLANG is not set: the msg subdirectory for the locale in $INFORMIXDIR/msg/lg_tr/code_set, 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:

    NLS
    5. If LANG and DBNLS are set (the client uses NLS), but DBLANG is not set:     a. In $INFORMIXDIR/msg/$LANG

    b. In $INFORMIXDIR/$LANG

    6. If DBLANG, CLIENT_LOCALE, and LANG are not set: a. In $INFORMIXDIR/msg/en_us/0333, an internal message directory for the default locale

    ALS
    b. In $INFORMIXDIR/msg/en_us.8859-1, the message directory of the default locale (for backward compatibility with Version 6.0 ALS products)

    c. In $INFORMIXDIR/msg, the default Informix message directories

    ALS
    d. In $INFORMIXDIR/msg/english, the message directory for the default locale of the operating system

Windows
This precedence specifies pathnames in UNIX syntax. In Windows environments, replace the syntax for the evaluation of an environment variable ($INFORMIXDIR) with the corresponding Windows syntax (%INFORMIXDIR%). Also replace the slash (/) between directories with the backslash (\). For example, the UNIX $INFORMIXDIR/msg/$DBLANG pathname would be %INFORMIXDIR%\msg\%DBLANG% in a Windows environment.

The compiled message files have the .iem file extension. For more information on DBLANG, see Chapter 4 of the Informix Guide to SQL: Reference.

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

Informix products use the DB_LOCALE environment variable for the following purposes:

    The database server uses the value of the DB_LOCALE environment variable that the client application sends. However, if you do not set DB_LOCALE on the client computer, the database server uses the value of DB_LOCALE on the server computer as the database locale.

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.

DBMONEY

The DBMONEY environment variable specifies the end-user formats for values in MONEY columns. For more information about end-user formats, see page 1-12.

Tip: For a detailed description of the syntax for DBMONEY, see Chapter 4 of the "Informix Guide to SQL: Reference."
With this environment variable, you can set the following currency notation:

    The front value specifies a currency symbol before the monetary value and the back value specifies a currency symbol after the value. The currency symbol can be non-ASCII character(s) if your client locale supports a code set that defines the non-ASCII character(s) that you use.

    You can specify a comma (,) or a period (.) as the monetary decimal separator. When you use one of these symbols in the DBMONEY value, you implicitly assign the other symbol to the thousands separator.

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

The DBTIME environment variable specifies the end-user formats of values in DATETIME columns for SQL API routines. For more information on end-user formats, see page 1-12.

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

ALS
Informix products support the era-based extension in DBTIME for backward compatibility with Informix ALS products. Informix recommends that you use the GL_DATETIME environment variable (see page 2-34) for date and time end-user formats in Version 9.1 client applications.

For a description of the standard DBTIME formats and general information about this environment variable, refer to the Informix Guide to SQL: Reference. This section describes the era-based (Asian) formats that DBTIME supports. For more information on era-based dates and times, see "Era-Based Date and Time Formats".

Era-Based DBTIME Formats

The DBTIME environment variable supports special extensions to format values in DATETIME columns as era-based dates and times. The following diagram shows the syntax for the era-based formatting directives that DBTIME supports.

string

 The formatting directives that specify the end-user format for the DATETIME values. You can use any formatting directive that formats non-era-based dates and times. For a list of these formatting directives, see the entry for DBTIME in Chapter 4 of the Informix Guide to SQL: Reference.

You can also use the era-based formatting directives that are described in the following list:

%EC

 accepts either the full or the abbreviated era name during a scan; during a print, %EC is replaced by the full name of the base year 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 during a scan; during a print, %Eg is replaced by the abbreviated name of the base year of the era that the locale defines (same as %C if locale does not define an era).

%Ey

 is replaced by the offset from the start of the era that %EC or %Eg specifies. This date is the era year only (same as %y if locale does not define an era).

Because DATETIME values must be compliant with ANSI-SQL standards, you cannot specify a literal DATETIME string that does not comply with these standards in an SQL statement.

The following examples show valid DATETIME input values for the given DBTIME formats.
DBTIME Format December 27, 1991 appears as:

%b %d, %Y

Dec 27, 1991

%y %m %dc1

80 12 27

%Y %m %dc1

0080 12 27

%Eg%Ey %m %d %H:%M:%S

H03 12 27 22:12:10

You can include non-ASCII characters in an era-based DBTIME format if the client locale supports a code set that contains these characters. For example, suppose you set CLIENT_LOCALE to the Japanese SJIS locale (ja_jp.sjis). To specify the multibyte SJIS character A1A2 as the separator between hours, minutes, and seconds, you might set DBTIME to the following string:

With this DBTIME value and a Japanese client locale of ja_jp.sjis, a DATETIME value of "December 27, 1991 22:12:10" would be formatted as follows:

In the preceding example, the multibyte character B1B2 is the full era name, which the client locale must define.

ESQLMF

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

When you set ESQLMF to 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 (see page 2-5) determines the type of filtering that esqlmf performs. For more information on the actions that esqlmf takes, see "The esqlmf Filter".

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

The GLS8BITFSYS environment variable tells an Informix product whether the operating-system can support non-ASCII characters in filenames.

When you set GLS8BITFSYS to 1 (or do not set it), Informix products can use non-ASCII characters (8-bit or multibyte characters) in a filename of an operating-system file that it generates. When you set GLS8BITFSYS to 0, Informix products generate filenames with 7-bit ASCII characters only.

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

Setting the GLS8BITFSYS Environment Variable
Use the GLS8BITFSYS environment variable to tell Informix products whether the operating system is 8-bit clean. This environment variable determines whether an Informix product can use non-ASCII characters in a filename of an operating-system file that it generates:

    An Informix product can use non-ASCII characters in a filename. 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.

    An Informix product does not allow non-ASCII characters in filenames. If you include non-ASCII characters in a filename from within a client application, 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.

Operating-System Files That Informix Products Generate

The value of the GLS8BITFSYS environment variable affects the filenames of the following types of files that Informix products generate:

Once an Informix product has generated an operating-system file, 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. For more information, refer to the section for your Informix product that the preceding list names.

GL_DATE

The GL_DATE environment variable specifies end-user formats of values for DATE columns. For more information on end-user formats, see page 1-12.

Important: The GL_DATE variable is evaluated when it is used. If it is invalid, the operations that called it will fail.
The extended functionality of the GL_DATE environment variable replaces the functionality of the DBDATE environment variable (see page 2-7). Informix recommends that applications use GL_DATE instead of DBDATE. An end-user format in GL_DATE can contain the following characters:

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/1996 to 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.

Tip: The GL_DATETIME environment variable accepts these date-formatting directive in addition to those that the section on page 2-34 lists.
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:

    For example, when you set GL_DATE to '%y %m %d' or '%iy %m %d', an internal date for March 6, 1996 formats to '96 03 06'.

    For example, when you set GL_DATE to '%Y %m %d' or '%iY %m %d', the internal date for March 6, 1996 formats to '1996 03 06'.

When an Informix product uses an end-user format to scan 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 scan date strings.
GL_DATE Format Date String to Scan:
'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 scan of a date string, the %iy and %y formatting directives both assume the current century for a 2-digit year. However, you can set the DBCENTURY environment variable to change this assumption.

For more information on how Informix products use end-user formats to scan and print strings, 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 scanning; 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 scanning; 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). For more information on the TIME and NUMERIC categories of a locale, see page A-4.

For a description of the era-based formats for DATETIME values, see "Alternative Time Formats".

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 scans or prints. The following sections describe what a field specification means for the scan and print operations. (For more information on the scan and print operations, 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 Scan
When an Informix product uses an end-user format to scan a date string, the field specification defines the number of characters to expect as input. This field specification has the following syntax.

max_width

 A decimal number that indicates the maximum number of characters to scan
min_width

 A decimal number that indicates the minimum number of characters to scan

The first character of the field specification indicates whether to assume that the field value is justified or padded, as follows:

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

Field Specification for a Print
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. This field specification has the following syntax.

width

 A decimal number that indicates a minimum field width for the printed value
precision

 A decimal number that indicates the precision to use for the field value. The meaning of the precision value depends on the particular formatting directive with which it is used, as the following table shows.

(1 of 2)

Formatting Directives Description

%C, %d, %e, %Ey, %iy, %iY,%m, %w, %y, %Y

Value of precision specifies the minimum number of digits to print. If a value supplies fewer digits than precision specifies, an Informix product pads the value with leading zeros. The %d, %Ey, %iy, %m, %w, and %y formatting directives have a default precision of 2. The %Y directive has no precision default; year 0001 would be formatted as 1 rather than as 0001.

%a, %A, %b, %B, %EC, %Eg, %h

Value of precision specifies the maximum number of characters to print. If a value supplies more characters than precision specifies, an Informix product truncates the value.

%D

Values of width and precision affect each element of these formatting directives. For example, %6.4D prints as follows:

%6.4m/%6.4d/%6.4y

%Ox

For formatting directives that include the O modifier (alternative digits), the value of precision is still the minimum number of digits to print. The width value defines the format width rather than the actual number of digits.

%Ex, %EY, %n, %t, %x, %%

The values of width and precision have no effect on these formatting directives.

For example, the following formatting directive displays the month as a decimal number with a maximum field width of 4:

The following formatting directive displays the day of the month as a decimal number with a minimum field width of 3 and a maximum field width of 4:

The first character of the field specification indicates whether to justify or pad the field value, as follows:

GL_DATETIME

 The GL_DATETIME environment variable specifies the end-user formats of values in DATETIME columns. For more information on end-user formats, see page 1-12.

Important: The GL_DATETIME environment variable supports a superset of the formatting directives of the DBTIME environment variable (see page 2-20). Informix recommends that applications use GL_DATETIME instead of DBTIME.
A GL_DATETIME format can contain the following characters:

White-space or other nonalphanumeric characters must appear between any two formatting directives. If a GL_DATETIME format does not correspond to any of the valid formatting directives, the behavior of the Informix product when it tries to format is undefined.

In addition to the formatting directives that are listed in the preceding table, you can include the following date-formatting directives in the end-user format of GL_DATETIME:

For more information on these date-formatting directives, see the GL_DATE environment variable on page 2-25.

For example, if you use an U.S. English locale, you might want to format an internal DATETIME YEAR TO SECOND value to the ASCII string format that the following example shows:

To do so, set the GL_DATETIME environment variable as the following line shows:

Important: The value of GL_DATETIME affects the behavior of certain ESQL library functions if the DBTIME environment variable (page 2-20) is not set. (For information about how these library functions are affected, refer to "DATETIME-Format Functions".) The value of DBTIME takes precedence over that of GL_DATETIME.
Alternative Time Formats

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

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

(1 of 2)

Alternative Time Format Description

%Ec

is replaced by a special date/time representation for the era that the locale defines (same as %c if locale does not define an era).

%EX

is replaced by a special time representation for the era that the locale defines (same as %X if locale does not define an era).

%OH

is replaced by the hour in the alternative digits that the locale defines (24-hour clock) (same as %H if locale does not define alternative digits).

%OI

is replaced by the hour in the alternative digits that the locale defines (12-hour clock) (same as %I if locale does not define alternative digits).

%OM

is replaced by the minute with the alternative digits that the locale defines (same as %M if locale does not define alternative digits).

%OS

is replaced by the second with the alternative digits that the locale defines (same as %S 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). For more information on the TIME and NUMERIC categories of a locale, see page A-4.

GL_DATETIME also supports the era-based date-formatting directives in an end-user format. For more information, see "Alternative Date Formats".

Optional Time Format Qualifiers

You can specify the following optional format qualifiers immediately after the % symbol of the formatting directive. A time format qualifier defines a field specification for the time (or date and time) that the Informix product scans or prints. This section describes what a field specification means for the print operation. For a description of what a field specification means for the scan operation, see page 2-32. For general information on the scan and print operations, see "End-User Formats".

When an Informix product uses an end-user format to print a string from an internal format, the field specification defines the number of characters to print as output. This field specification has the following syntax.

width

 A decimal number that indicates a minimum field width for the printed value
precision

 A decimal number that indicates the precision to use for the field value. The meaning of the precision value depends on the particular formatting directive with which it is used, as the following table shows.

Formatting Directives Description

%F, %H, %I, %M, %S

Value of precision specifies the minimum number of digits to print. If a value supplies fewer digits than the precision specifies, an Informix product pads the value with leading zeros. The %H, %M, and %S formatting directives have a default precision of 2.

%p

Value of precision specifies the maximum number of characters to print. If a value supplies more characters than the precision specifies, an Informix product truncates the value.

%R, %T

Values of width and precision affect each element of these formatting directives. For example, %6.4R prints as follows:

%6.4H:%6.4M

%F

Value of precision can follow this directive as an optional precision specification. This value must be between 1 and 5. Otherwise, an Informix product generates an error. This precision value overrides any precision value that you specify between the % symbol and the formatting directive.

%Ox

For formatting directives that include the O modifier, value of precision is still the minimum number of digits to print. The width value defines the format width rather than the actual number of digits.

%c, %Ec, %EX, %X

The values of width and precision have no effect on these formatting directives.

For example, the following formatting directive displays the minute as a decimal number with a maximum field width of 4:

The following formatting directive displays the hour as a decimal number with a minimum field width of 3 and a maximum field width of 6:

The first character of the field specification indicates whether to justify or pad the field value, as follows:

SERVER_LOCALE

 The SERVER_LOCALE environment variable specifies the server locale, which the database server uses to perform read and write operations that involve operating-system files on the server computer. (For information about the server locale, see "The Server Locale".)

The database server uses the SERVER_LOCALE environment variable for the following purposes:

For Informix database servers, if you do not set SERVER_LOCALE, these database servers use the default locale, U.S. English, as the server locale.



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