DATETIME-TZ function

Converts a date, time, and time zone value, or a character string, into a DATETIME-TZ 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").

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