DT_TOUTC: Converting Local Time to Universal Coordinated Time

How to:

Coordinated Universal Time (UTC) is the time standard commonly used around the world. To convert UTC time to a local time, a certain number of hours must be added to or subtracted from the UTC time, depending on the number of time zones between the locality and Greenwich, England (GMT).

DT_TOUTC converts local time to UTC time.

Converting timestamp values from different localities to a common standard time enables you to sort events into the actual event sequence.

This function requires an IANA (Internet Assigned Numbers Authority) time zone database names (expressed as 'Area/Location') as a parameter. You can find a table of IANA TZ database names on Wikipedia at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, as shown in the following image.

If you do not know what Area and Location corresponds to your time zone, but you do know your offset from GMT, or your legacy time zone name (such as EST), scroll down in the table. There are TZ database names that correspond to these time zone identifiers, as shown in the following image.

Note: If you use a standard IANA time zone database name in the form 'Area/Location' (for example, 'America/New_York'), automatic adjustments are made for Daylight Savings Time. If you use a name that corresponds to an offset from GMT or to a legacy time zone name, it is your responsibility to account for Daylight Savings Time.

Syntax: How to Convert Local Time to UTC Time 

DT_TOUTC(datetime, timezone)

where:

datetime

Date-time

Is a date-time expression representing local time, containing date and time components.

timezone

Alphanumeric

Is a character expression containing the IANA time zone name of the local time, in the form 'Area/Location' (for example, 'America/New_York').

Example: Converting Local Time to UTC Time

The following request converts the current local date-time value for time zone America/New_York to UTC time.

TABLE FILE GGSALES
SUM DOLLARS NOPRINT
COMPUTE LOCAL1/HYYMDS  = DT_CURRENT_DATETIME(SECOND);
COMPUTE UTC1/HYYMDS = DT_TOUTC(LOCAL1, 'America/New_York');
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
GRID=OFF,$
ENDSTYLE
END

The output is shown in the following image.

Example: Sorting by UTC Time

The following request retrieves the current date and time into the field LOCALT1 and sets the field TIMEZONE to IANA time zone database names. It then uses DT_TOUTC to convert the same local time, with different time zones, to the UTC time that corresponds to the given time zone, and sorts the output by the generated UTC time. 

DEFINE FILE GGSALES
LOCALT1/HYYMDS=DT_CURRENT_DATETIME(SECOND);
TIMEZONE/A30=IF LAST TIMEZONE EQ ' ' THEN 'AMERICA/NEW_YORK' 
 ELSE IF LAST TIMEZONE EQ 'AMERICA/NEW_YORK' THEN 'AMERICA/CHICAGO' 
 ELSE IF LAST TIMEZONE EQ 'AMERICA/CHICAGO' THEN  'AMERICA/DENVER'
 ELSE IF LAST TIMEZONE EQ 'AMERICA/DENVER' THEN 'ASIA/TOKYO'
 ELSE IF LAST TIMEZONE EQ 'ASIA/TOKYO' THEN 'EUROPE/LONDON'
 ELSE IF LAST TIMEZONE EQ 'EUROPE/LONDON' THEN 'AMERICA/NEW_YORK';
UTCTIME/HYYMDS=DT_TOUTC(LOCALT1,TIMEZONE);
END
TABLE FILE GGSALES
PRINT TIMEZONE LOCALT1 DOLLARS NOPRINT
BY UTCTIME
WHERE PRODUCT EQ 'Thermos'
IF RECORDLIMIT EQ 20
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
GRID=OFF,$
ENDSTYLE
END

The output is shown in the following image.