You are here:

util.Datetime.toUTC()

util.Datetime.toUTC() converts a local time zone DATETIME value to UTC.

Syntax

util.Datetime.toUTC(local)

Parameters

local

a DATETIME value in the local time zone that must be converted to UTC

Usage and examples

util.Datetime.toUTC() takes a DATETIME value in the local time zone passed as the parameter and converts it to UTC (i.e., Coordinated Universal Time, also known as GMT, Greenwich Mean Time):

LET utc = util.Datetime.toUTC(DATETIME(2017-02-23 15:34:56) YEAR TO SECOND)

example code	MAIN DEFINE utc DATETIME YEAR TO SECOND DISPLAY "Local: 2017-02-23 12:34:56" LET utc = util.Datetime.toUTC(DATETIME(2017-02-23 12:34:56) YEAR TO SECOND) DISPLAY "UTC: ", utc CALL fgl_getkey() END MAIN
obtained results

The DATETIME value passed as the parameter to util.Datetime.toUTC() does not the GMT offset indicator or daylight saving time information.

It is no problem for countries that live with standard time. However, for countries that practice daylight saving and adjust their clocks twice a year, there are such periods of time when util.Datetime.toUTC() will fail to convert the local time to UTC properly.

In most cases, util.Datetime.toUTC() can interpret the local time as summer time or as winter time based on the OS settings. But within the daylight saving time transition period, the local time zone DATETIME value might be misinterpreted because util.Datetime.toUTC() does not know if this local time is the time before or after the daylight saving time change.

For example, there is a country in the UTC+02:00 time zone that advances clocks by one hour at 03:00 AM on October 30, 2017. The ambiguous time is between 02:00 AM and 03:00 AM. If util.Datetime.toUTC() gets 2016-10-30 02:35:35 as the parameter, the method will not be able to tell whether it is before or after the clocks advanced and will convert it to 2016-10-30 01:35:35.

example code

MAIN

DISPLAY " Original UTC Local time toUTC(local-time) (toUTC() - Original UTC)"

CALL test_to_utc("2016-10-30 02:35:35")

CALL test_to_utc("2016-10-30 03:35:35")

CALL test_to_utc("2016-10-30 04:35:35")

CALL test_to_utc("2016-10-30 05:35:35")

CALL fgl_getkey()

END MAIN

FUNCTION test_to_utc(utc)

DEFINE utc, local, utc_upd DATETIME YEAR TO SECOND

LET local = util.Datetime.toLocalTime(utc)

LET utc_upd = util.Datetime.toUTC(local)

DISPLAY SFMT("%1 %2 %3 %4", utc, local, utc_upd, utc_upd-utc)

END FUNCTION

obtained results