TIME ZONE (Firebird 4.0)
<< TIMESTAMP | IBExpert Glossary | TIP (Transaction Inventory Page) >>
Initial support in IBExpert since version 2018.12.15.
Source: Time Zone support (FB 4.0)
Time Zone support (FB 4.0)
Time zone support consists of TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE data types, expressions and statements to work with time zones and conversion between data types without/with time zones.
The first important thing to understand is that TIME WITHOUT TIME ZONE, TIMESTAMP WITHOUT TIME ZONE and DATE data types are defined to use the session time zone when converting from or to a TIME WITH TIME ZONE or TIMESTAMP WITH TIME ZONE. TIME and TIMESTAMP are synonymous to theirs respectively WITHOUT TIME ZONE data types.
The session time zone, as the name implies, can be a different one for each database attachment. It can be set with the isc_dpb_session_time_zone DPB, and if not, it starts by default defined to be the firebird.conf parameter DefaultTimeZone or the same time zone used by the Firebird OS process when the parameter is not defined. A change in DefaultTimeZone configuration or the OS time zone does not changes the default of a running Firebird process.
It can then be changed with SET TIME ZONE statement to a given time zone or reset to its original value with SET TIME ZONE LOCAL.
A time zone may be a string with a time zone region (for example, America/Sao_Paulo) or a hours:minutes displacement (for example, -03:00) from GMT.
A time/timestamp with time zone is considered equal to another time/timestamp with time zone if their conversion to UTC are equal, for example, time '10:00 -02' = time '09:00 -03', since both are the same as time '12:00 GMT'. This is also valid in the context of UNIQUE constraints and for sorting purposes.
Data types
TIME [ { WITH | WITHOUT } TIME ZONE ]
TIMESTAMP [ { WITH | WITHOUT } TIME ZONE ]
Storage
TIME/TIMESTAMP WITH TIME ZONE has respectively the same storage of TIME/TIMESTAMP WITHOUT TIME ZONE plus 2 bytes for the time zone identifier or displacement.
The time/timestamp parts are stored in UTC (translated from the informed time zone).
Time zone identifiers (from regions) are put directly in the time_zone field. They start from 65535 (which is the GMT code) and are decreasing as new time zones were/are added.
Time zone displacements (+/- HH:MM) are encoded with (sign * (HH * 60 + MM)) + 1439. For example, a 00:00 displacement is encoded as (1 * (0 * 60 + 0)) + 1439 = 1439 and -02:00 as (-1 * (2 * 60 + 0)) + 1439 = 1319.
API structs
struct ISC_TIME_TZ
{
ISC_TIME utc_time;
ISC_USHORT time_zone;
};
struct ISC_TIMESTAMP_TZ
{
ISC_TIMESTAMP utc_timestamp;
ISC_USHORT time_zone;
};
API functions (FirebirdInterface.idl - IUtil interface)
void decodeTimeTz(
Status status,
const ISC_TIME_TZ* timeTz,
uint* hours,
uint* minutes,
uint* seconds,
uint* fractions,
uint timeZoneBufferLength,
string timeZoneBuffer
);
void decodeTimeStampTz(
Status status,
const ISC_TIMESTAMP_TZ* timeStampTz,
uint* year,
uint* month,
uint* day,
uint* hours,
uint* minutes,
uint* seconds,
uint* fractions,
uint timeZoneBufferLength,
string timeZoneBuffer
);
void encodeTimeTz(
Status status,
ISC_TIME_TZ* timeTz,
uint hours,
uint minutes,
uint seconds,
uint fractions,
const string timeZone
);
void encodeTimeStampTz(
Status status,
ISC_TIMESTAMP_TZ* timeStampTz,
uint year,
uint month,
uint day,
uint hours,
uint minutes,
uint seconds,
uint fractions,
const string timeZone
);
Time zone string syntax
<time zone string> ::=
'<time zone>'
<time zone> ::=
<time zone region> |
[+/-] <hour displacement> [: <minute displacement>]
Examples
'America/Sao_Paulo'
'-02:00'
'+04'
'04:00'
'04:30'
TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE literals
<time with time zone literal> ::=
time '<time> <time zone>'
<timestamp with time zone literal> ::=
timestamp '<timestamp> <time zone>'
Examples
time '10:00 America/Los_Angeles'
time '10:00:00.5 +08'
timestamp '2018-01-01 10:00 America/Los_Angeles'
timestamp '2018-01-01 10:00:00.5 +08'
Statements and expressions
SET TIME ZONE statement
Changes the session time zone.
Syntax
SET TIME ZONE { <time zone string> | LOCAL }
Examples
set time zone '-02:00'; set time zone 'America/Sao_Paulo'; set time zone local;
SET TIME ZONE BIND statement
Changes the session time zone bind for compatibility with old clients.
The default is NATIVE, which means that TIME WITH TIME ZONE and TIMESTAMP WITH TIME ZONE expressions are returned with they new data types to the client.
Old clients may not understand the new data types, so it's possible to define the bind to LEGACY and the expressions will be returned as TIME WITHOUT TIME ZONE and TIMESTAMP WITHOUT TIME ZONE, with appropriate conversion.
The bind configuration is also applicable to input parameters.
Syntax
SET TIME ZONE BIND { NATIVE | LEGACY }
Examples
set time zone bind native; set time zone bind legacy;
AT expression
Translates a time/timestamp value to its correspondent value in another time zone.
If LOCAL is used, the value is converted to the session time zone.
Syntax
<at expr> ::=
<expr> AT { TIME ZONE <time zone string> | LOCAL }
Examples
select time '12:00 GMT' at time zone '-03' from rdb$database; select current_timestamp at time zone 'America/Sao_Paulo' from rdb$database; select timestamp '2018-01-01 12:00 GMT' at local from rdb$database;
EXTRACT expressions
Two new EXTRACT expressions has been added:
- TIMEZONE_HOUR: extracts the time zone hours displacement
- TIMEZONE_MINUTE: extracts the time zone minutes displacement
Examples
select extract(timezone_hour from current_time) from rdb$database; select extract(timezone_minute from current_timestamp) from rdb$database;
LOCALTIME expression
Returns the current time as a TIME WITHOUT TIME ZONE, i.e., in the session time zone.
Example
select localtime from rdb$database;
LOCALTIMESTAMP expression
Returns the current timestamp as a TIMESTAMP WITHOUT TIME ZONE, i.e., in the session time zone.
Example
select localtimestamp from rdb$database;
See also:
TIME
TIMESTAMP
CURRENT_TIMESTAMP
