GL_DATETIME

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

GL_DATETIME

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

A GL_DATETIME format can contain the following characters:

One or more white-space 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

>>-GL_DATETIME--'string'--+------------------------------------------+-><
                          |                                     (1)  |
                          '-| Optional Time Format Qualifiers |------'

Notes:

Pg. Optional Time Format Qualifiers

Element: Description
string: Contains the formatting directives that specify the end-user format for GL_DATETIME values. You can use any formatting directive that formats dates or times. For a list of formatting directives for dates, see GL_DATE.

This list describes the time formatting directives that are not based on era.

Formatting Directives	Description
%c	Is replaced by a special datetime representation that the locale defines.
%Fn	Is replaced by the value of the fraction of a second with precision that is specified by the integer n. The default value of n is `2`; the range of n is `0` ≤ n ≤ `5`. This value overrides any width or precision between the % and `F` character. For more information, see Optional Time Format Qualifiers.
%H	Is replaced by the hour as an integer (00 through 23) (24-hour clock).
%I	Is replaced by the hour as an integer (00 through 12) (12-hour clock).
%M	Is replaced by the minute as an integer (00 through 59).
%p	Is replaced by the A.M. or P.M. equivalent as defined in the locale.
%r	Is replaced by the commonly used time representation for a 12-hour clock format (including the A.M. or P.M. equivalent) as defined in the locale.
%R	Is replaced by the time in 24-hour notation (%H:%M).
%S	Is replaced by the second as an integer (00 through 61). The second can be up to 61 instead of 59 to allow for the occasional leap second and double leap second.
%T	Is replaced by the time in the %H:%M:%S format.
%X	Is replaced by the commonly used time representation as defined in the locale.
%%	Is replaced by % (to allow % in the format string).

White-space or other nonalphanumeric characters must appear between any two formatting directives. Any other characters in the GL_DATETIME setting that were not listed above as formatting directives are interpreted as literal characters. If a GL_DATETIME 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.

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

%a, %A, %b, %B, %C, %d, %D, %e, %h, %iy, %iY, %m, %n, %t, 
%w, %x, %y, %Y, %%

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:

Mar 21, 1997 at 16 h 30 m 28 s

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

%b %d, %Y at %H h %M m %S s

Important:

The value of GL_DATETIME affects the behavior of certain ESQL/C library functions if the DBTIME environment variable is not set. For information about how these library functions are affected, see DATETIME-Format Functions. The value of DBTIME takes precedence over the value of GL_DATETIME.

Alternative Time Formats

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

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

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

Alternative Time Format	Description
%Ec	Is replaced by a special date/time representation for the era that the locale defines. It is the same as %c if the locale does not define an era.
%EX	Is replaced by a special time representation for the era that the locale defines. It is the same as %X if the locale does not define an era.
%OH	Is replaced by the hour in the alternative digits that the locale defines (24-hour clock). It is the same as %H if the locale does not define alternative digits).
%OI	Is replaced by the hour in the alternative digits that the locale defines (12-hour clock). It is the same as %I if the locale does not define alternative digits).
%OM	Is replaced by the minute with the alternative digits that the locale defines. It is the same as %M if the locale does not define alternative digits.
%OS	Is replaced by the second with the alternative digits that the locale defines. It is the same as %S if the 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 special date representation for the era (which the %Ex formatting directive uses)
A special time representation for the era (which the %EX formatting directive uses)
A special date/time representation for the era (which the %Ec formatting directive uses)

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

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 IBM Informix product reads 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 read operation, see Field Specification for Reading a DATE Value. For information about end-user formats, see End-User Formats.

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

Optional Time Format Qualifiers
 
>>-+----+--+---------------------------------+-----------------><
   +- --+  '-+-------+--+---+--+-----------+-'
   '-0--'    '-width-'  '-.-'  '-precision-'

Element: Description
- (minus sign): IBM Informix product prints the field value as left justified and pads this value with spaces on the right.
0 (zero): IBM Informix product prints the field value as right justified and pads this value with zeros on the left.
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 first character of the field specification indicates whether to justify or pad the field value. If the first character is neither a minus sign nor a zero (0), an IBM Informix product prints the field value as right justified and pads this value with spaces on the left.

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 IBM 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 IBM Informix product truncates the value.
%R, %T	Values of width and precision affect each element of these formatting directives. For example, the field specification %6.4R causes a DATETIME value to be displayed a if the format were this: %6.4H:%6.4M Here no fewer than four (but no more than six) characters represented the hour and the minute.
%F	Value of precision can follow this directive as an optional precision specification. This value must be between 1 and 5. Otherwise, an IBM 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	Values of width and precision have no effect on these formatting directives.

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

%4M

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

%6.3H

The specified format is applied to all displayed DATETIME values, regardless of their declared precision. For example, suppose that the setting of GL_DATETIME is '%Y/%m/%d %H:%M:%S' This setting would cause a value from a DATETIME YEAR TO SECOND column to be displayed as follows:

[2000/08/28 14:43:17]

If a program executed on August 28 of the year 2000, the same GL_DATETIME setting would also display a value from a DATETIME HOUR TO SECOND column as follows:

[2000/08/28 14:43:17]

When GL_DATETIME is set, every DATETIME value is displayed in the specified format, even if that format includes time units that were not included in the DATETIME qualifier when the data type was declared. Time units outside the declared precision are obtained from the system clock-calendar. To avoid unexpected results, you might prefer to set GL_DATETIME only for applications where the DATETIME data types that you display have the same precision as the GL_DATETIME setting.

Creation-Time Settings

Like DBCENTURY, DBDATE, and GL_DATE, the GL_DATETIME variable can affect how expressions that include literal time values are evaluated. For some earlier releases, resetting environment variables can produce inconsistent behavior in check constraints, triggers, fragmentation expressions, UDRs, and other database objects whose definitions include time expressions. Objects created in this release use the environment variable settings that were in effect at the time when the object was created, rather than the settings at the time of execution (if these are different) to avoid inconsistency.