timestamp Function

Format

d = timestamp();
d = timestamp(rfc3339_string);
d = timestamp(year, month, dayʃ, hour, minute, second, utcOffset := offsetʅ);

Description

The timestamp function returns the UNIX time, which is the number of seconds that have elapsed since January 1, 1970 in Coordinated Universal Time (UTC). This value is used by many computer programs and is thus useful for storing times as well as calculating timespans. Because the time is in UTC, it eliminates the need to worry about time zones when working with times.

The first version of the function returns a timestamp for the current time according to a device's clock. The value is as accurate as the device's clock.

The second version of the function takes a string expression, rfc3339_string, that represents a date in RFC 3339 format. Dates specified in ISO 8601 format can also be used by this version. The string is parsed with the timestamp representing the string returned.

The third version returns the timestamp for a date specified using numeric expressions for the year, month, and day. The hour, minute, and second can also be specified. Using named arguments, you can specify a time zone offset. If not specified, the time zone of the device is used, so to calculate a timestamp in UTC, you must specify: utcOffset := 0.

Return Value

The function returns the UNIX time as a decimal value. The integer part of this value is the number of elapsed seconds, while the decimal part contains the milliseconds. If there was an error parsing the RFC 3339 string, or the date values provided, the function returns default.

If you wish to store a timestamp in a fixed-width numeric variable, the variable should have an integer length of 10 and a decimal length of 3 (for a total length of 13 without a decimal character, or 14 with one).

Example 1

PROC GLOBAL

numeric surveyStartTime;

PROC CROPS_QUEST

preproc

surveyStartTime = timestamp();

// if the survey began at 10:58pm on 12/28/2021 EST,
// the UTC time (in seconds) would be 1640750243

errmsg("Survey Start Time = %d", surveyStartTime);

postproc

SURVEY_DURATION = timestamp() - surveyStartTime;

Example 2

// the Olympics 2008 opening ceremony was held on:
// - August, 8, 2008, at 8:00 pm (China Standard Time)
numeric timestamp_from_rfc3339 = timestamp("2008-08-08T12:00:00+00:00");
numeric timestamp_from_date = timestamp(2008, 8, 8, 20, utcOffset := 8);