Converts a date, time, and time zone value, or a character string, into a DATETIME-TZ value.

Note: If any argument is the Unknown value (?), the result is the Unknown value (?).

Syntax

DATETIME-TZ ( date-exp[ , mtime-exp [ , timezone-exp]] )
 
DATETIME-TZ ( datetime-exp [ , timezone-exp] )
 
DATETIME-TZ ( datetime-tz-exp [ , timezone-exp] )
 
DATETIME-TZ ( month , day , year , hours , minutes 
            [ , seconds[ , milliseconds[ , timezone-exp]]] )
 
DATETIME-TZ ( string )
date-exp
An expression whose value is a DATE.
mtime-exp
An expression whose value is an integer representing the number of milliseconds since midnight.
timezone-exp
An expression whose value is an integer representing the time zone offset from Coordinated Universal Time (UTC) in minutes. If not specified, the function uses the session's time zone.
datetime-exp
An expression whose value is a DATETIME.
datetime-tz-exp
An expression whose value is a DATETIME-TZ. Use this option to convert a DATETIME-TZ from one time zone to another.
month
An expression whose value is an integer from 1 to 12, inclusive.
day
An expression whose value is an integer from 1 to the highest valid day of the month.
year
An expression that evaluates to a year.
hours
An expression whose value is an integer from 0 to 23, inclusive.
minutes
An expression whose value is an integer from 0 to 59, inclusive.
seconds
An expression whose value is an integer from 0 to 61, inclusive. The upper limit is 61 for leap seconds.
milliseconds
An expression whose value is an integer from 0 to 999, inclusive.
string
A character expression whose value is a string containing a DATETIME-TZ. The date portion of the string must have the format specified by the DATE-FORMAT attribute. The time portion must be in a valid time format (HH:MM:SS, and so on). If the string contains a time zone, it must be in +HH:MM format. If the string does not contain a time zone, the DATETIME-TZ inherits the session's time zone.

Example

Following is an example of using the DATETIME-TZ function:

DEFINE VARIABLE my-datetime-tz AS DATETIME-TZ NO-UNDO.

/* This statement is equivalent to "my-datetime-tz = NOW". */
my-datetime-tz = DATETIME-TZ(TODAY, MTIME, TIMEZONE).

The following statements result in the same DATETIME-TZ value (when SESSION:DATE-FORMAT is mdy):

my-datetime-tz = DATETIME-TZ(5, 5, 2002, 7, 15, 3, 0, -300).
my-datetime-tz = DATETIME-TZ("05-05-2002 07:15:03-05:00").

Notes

  • The DATETIME and DATETIME-TZ data types are not locale-aware. For DATETIME-TZ, the time zone is represented only as an offset from UTC. When converting a DATETIME value to DATETIME-TZ, the AVM checks whether the local date and time fall within daylight saving time on the system and applies the appropriate UTC offset. Because of this, conversions between DATETIME and DATETIME-TZ may be unreliable during daylight saving transition periods.

See also

ADD-INTERVAL function, DATE function, DATE-FORMAT attribute, DATETIME function, DAY function, ETIME function, INTERVAL function, ISO-DATE function, MONTH function, MTIME function, NOW function, TIME function, TIMEZONE function, TODAY function, WEEKDAY function, YEAR function, YEAR-OFFSET attribute