util.Datetime.toUTC

Converts a datetime value to the UTC datetime.

Syntax

util.Datetime.toUTC(
   local DATETIME q1 TO q2
)
  RETURNING utc DATETIME q1 TO q2

local is the local timezone datetime value.
utc is the datetime value in UTC.

Usage

The util.Datetime.toUTC() method converts the local timezone DATETIME value passed as parameter to the "Coordinated Universal Time" (UTC), also known as "Greenwich Mean Time" (GMT).

The toUTC() method on local timezone information settings.

Fall/Autumn daylight saving time transition period

Important: The toUTC() function cannot determine if the local datetime value represents a time before or after the daylight saving time change, when the value is in the hour of the daylight saving time transition period in the fall (this is for example, the hour 02:00 PM to 03:00 PM on the last Sunday of October in Europe and first Sunday of November in the USA). Depending on the operating system, the toUTC() method can interpret the local time as a Summer time or as a Winter time. In order to get the current system time in UTC, use the util.Datetime.getCurrentAsUTC() method.

The DATETIME value passed as parameter to the toUTC() method is the datetime in the local timezone. However, this value does not contain the GMT offset indicator or daylight saving time information.

When passing local datetime values in the hour of the daylight saving time transition period in the fall (when clocks roll back one hour), the toUTC() function cannot determine if the local datetime value represents a point in time before or after the daylight saving time transition occured. Depending on the operating system, the toUTC() method can interpret the local time as a Summer time or as a Winter time. As a result, the conversion to the UTC time can be mis-interpreted.

For example, in Europe, the fall daylight saving time changes on the 25 of October, at 3:00 PM. The ambigous period is between 2:00 PM and 3:00 PM (local time). If you pass for example, the datetime value 2015-10-25 02:34:11 to the toUTC() method, there is no way for the method to know if this local time is the time before (CEST / UTC+2h) or after (CET / UTC+1h) the daylight saving time change.

This behavior can be illustrated with the following code example:

IMPORT util

MAIN
    DISPLAY "Original UTC         Local time (Paris)   toUTC(local-time)     ( toUTC() - Orig UCT )"
    CALL test( "2015-10-24 23:59:59" )
    CALL test( "2015-10-25 00:59:59" )
    CALL test( "2015-10-25 01:59:59" )
    CALL test( "2015-10-25 02:59:59" )
END MAIN

FUNCTION test(utc)
    DEFINE utc, loc, utc2 DATETIME YEAR TO SECOND
    LET loc = util.Datetime.toLocalTime(utc)
    LET utc2 = util.Datetime.toUTC(loc)
    DISPLAY SFMT("%1  %2  %3  %4", utc,loc,utc2,utc2-utc)
END FUNCTION

The above code will produce the following output on Linux, with with TZ='Europe/Paris':

Original UTC         Local time (Paris)   toUTC(local-time)     ( toUTC() - Orig UCT )
2015-10-24 23:59:59  2015-10-25 01:59:59  2015-10-24 23:59:59          0 00:00:00
2015-10-25 00:59:59  2015-10-25 02:59:59  2015-10-25 00:59:59          0 00:00:00
2015-10-25 01:59:59  2015-10-25 02:59:59  2015-10-25 00:59:59         -0 01:00:00
2015-10-25 02:59:59  2015-10-25 03:59:59  2015-10-25 02:59:59          0 00:00:00

As you can see, the local time 2015-10-25 02:59:59 is always converted to UTC 2015-10-25 00:59:59.

Example

IMPORT util
MAIN
    DEFINE utc DATETIME YEAR TO SECOND
    LET utc = util.Datetime.toUTC( DATETIME(2015-08-22 15:34:56) YEAR TO SECOND )
    DISPLAY "UTC: ", utc
END MAIN