GL_DATE

Home | Previous Page | Next Page GLS Environment Variables > GLS-Related Environment Variables >

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, rather than when it is set. If it is invalid, the operation that called it fails.

>>-GL_DATE--'string'--+-----------------------------------------------------------------------------+-><
                      |                                 (1)                                    (2)  |
                      '-| Format Qualifiers for Reads |-------| Format Qualifiers for Prints |------'

Notes:

Element: Description
string: Formatting directives that specify the end-user format for GL_DATE values. You can use any formatting directive that formats dates.

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

One or more whitespace characters, which the CTYPE category of the locale specifies
An ordinary character (other than the % symbol or a white-space character)
A formatting directive, which is composed of the % symbol followed by a conversion character that specifies the required replacement.

The next 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:

Mar 05, 1997 (Wednesday)

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

%b %d, %Y (%A)

If a GL_DATE format does not correspond to any of the valid formatting directives, the behavior of the IBM 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.

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

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

The %iy and %y formatting directives both print the year of an internal date value as a 2-digit decade.
For example, when you set GL_DATE to '%y %m %d' or '%iy %m %d', an internal date for March 5, 1997 formats to '97 03 05'.
The %iY and %Y formatting directives both print the year of an internal date value as a 4-digit year.
For example, when you set GL_DATE to '%Y %m %d' or '%iY %m %d', the internal date for March 5, 1997 formats to '1997 03 05'.

When an IBM 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 IBM Informix product uses them to read date strings.

GL_DATE Format	Date String to Read
GL_DATE Format	'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. You can set the DBCENTURY environment variable to change this default.

Alternative Date Formats

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

E indicates use of an alternative era format, which the locale defines.
O (the letter O) indicates use of locale-defined alternative digits.

These date-formatting directives can support conversion modifiers.

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 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 (or %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 (or %Y if locale does not define alternative digits).

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

The full and abbreviated names for an era
A representation for the era (which the %Ex directive uses)

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 optional format qualifiers immediately after the % symbol of the formatting directive. A date format qualifier defines a field specification for the date in read or print operations. 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 Reading a DATE Value

When an IBM 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.

Format Qualifiers for Reads
 
>>-+----+--+-------------------------------------+-------------><
   +- --+  '-+-----------+--+---+--+-----------+-'
   '-0--'    '-max_width-'  '-.-'  '-min_width-'

Element: Description
- (minus sign): Field value is left justified and begins with a digit; this value can include trailing spaces
0 (zero): Field value is right justified; any zeros on the left are pad characters that 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 IBM Informix product assumes that the field value is right justified and any spaces on the left are pad characters.

If the field value begins with a zero, however, it cannot include pad characters.

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

Field Specification for Displaying a DATE Value

When an IBM 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.

Format Qualifiers for Output
 
>>-+----+--+---------------------------------+-----------------><
   +- --+  '-+-------+--+---+--+-----------+-'
   '-0--'    '-width-'  '-.-'  '-precision-'

Element: Description
- (minus sign): Field value is left justified and begins with a digit; value can include trailing blank spaces
0 (zero): Field value is right justified; 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 formatting directive with which it is used, as the following table shows.

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 IBM 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 IBM Informix product truncates the value.
%D	Values of width and precision affect each element of these formatting directives. For example, the field specification %6.4D causes a DATE value to be displayed as if the format were: %6.4m/%6.4d/%6.4y where no fewer than four (but no more than six) characters represented the month, day, and year values, in that order, with "/" as the separator.
%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, %%	Values of width and precision have no effect on these formatting directives.

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

%4m

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

%4.3d