Duration, Date and Time¶

SysTimeGetMs¶

VAR
    tDelta, tStart, tEnd : TIME;
END_VAR

tStart := TO_TIME(SysTimeGetMs());
(* ... lengthy operation ... *)
tEnd := TO_TIME(SysTimeGetMs());
tDelta := tEnd - tStart (* ms *);

The code example in the last section has the same effect as the code example in the next section.

tStart := TIME();
(* ... lengthy operation ... *)
tDelta := TIME() - tStart (* ms *);

SysTimeGetUs¶

VAR
    stDelta, stStart, stEnd : SysTime;
END_VAR

SysTimeGetUs(stStart);
(* ... lengthy operation ... *)
SysTimeGetUs(stEnd);
stDelta := stEnd - stStart (* µs *);

SysTimeGetNs¶

VAR
    ltDelta : LTIME;
    stStart, stEnd : SysTime;
END_VAR

SysTimeGetNs(stStart);
(* ... lengthy operation ... *)
SysTimeGetNs(stEnd);
ltDelta := TO_LTIME(stEnd - stStart) (* ns *);

The code example in the last section has the same effect as the code example in the next section.

VAR
    ltDelta, ltStart : LTIME;
END_VAR

ltStart := LTIME();
(* lengthy operation *)
ltDelta := LTIME() - ltStart (* ns *);

Timer¶

The handling of a time duration at the basis of the data types TIME and LTIME are also the kernel of the timer function blocks in the libraries standard (for TIME) and standard64 (for LTIME).

Example

PROGRAM TIMER
VAR
    tDelta : TIME := T#2s;
    T1 : TON;
    T2 : TP;
    T3 : TOF;
END_VAR

Problems with Localtime¶

The major problem dealing with the localtime is that certain times of a day may occur twice in a year. For example, in the US/Eastern timezone on the last Sunday morning in October, the following sequence happens:

• 01:00 EDT occurs

• 1 hour later, instead of 2:00am the clock is turned back 1 hour and 01:00 happens again (this time 01:00 EST)

In fact, every instant between 01:00 and 02:00 occurs twice. This means that if a variable of type “TIME” is written in the “US/Eastern” time zone, it can no longer be decided whether it was written shortly before or after the transition from summer time to winter time.

The best and simplest solution is to stick with using UTC. Note that some other timezones are commonly thought of as the same (GMT, Greenwich, Universal, etc.). The definition of UTC is distinct from these other timezones, and they are not equivalent.

“UTC” is Coordinated Universal Time. It is a successor to, but distinct from, Greenwich Mean Time (GMT) and the various definitions of Universal Time. UTC is currently the worldwide standard for regulating clocks and time measurement.

All other timezones are defined relative to UTC, and include offsets like UTC+0800 - hours to add or subtract from UTC to derive the local time. No daylight saving time occurs in UTC, making it a useful timezone to perform date arithmetic without worrying about the confusion and ambiguities caused by daylight saving time transitions, your country changing its timezone, or mobile applications that roam through multiple timezones.

The SysTimeRTC Library provides a set of functions to deal with this issues and helps to handle variables of the types (L)DATE, (L)TIME_OF_DAY and (L)DATE_AND_TIME correctly.

The Data Types¶

CODESYS is following the IEC 61131-3 standard and implements therefore some data types:

• DATE: Seconds since Thursday, 1.1.1970 00:00:00, managed in a 32 Bit data type like UDINT

• TIME_OF_DAY or TOD: Milliseconds since 00:00:00.000, managed in a 32 Bit data type like UDINT (Modulo TIME#1d)

• DATE_AND_TIME or DT: Seconds since Thursday, 1.1.1970 00:00:00, managed in a 32 Bit data type like UDINT

Starting with data type DATE_AND_TIME, variables of the other data types can be assigned accordingly. A variable of type DATE_AND_TIME can be initialized with a current value with the help of the CODESYS runtime system’s functions SysTimeRtcGet.

See: Naming Conventions for variables of type UDINT, DATE, TIME_OF_DAY and DATE_AND_TIME.

VAR
    udiUTC_DateAndTime : UDINT;

    Result : RTS_IEC_RESULT;

    dtNow : DATE_AND_TIME;
    todNow : TIME_OF_DAY;
    datNow : DATE;
END_VAR

udiUTC_DateAndTime := TO_UDINT(SysTimeRtcGet(Result)); // UDINT#1528268918

dtNow := TO_DT(udiUTC_DateAndTime); // DT#2018-6-6-7:8:38
todNow := TO_TOD(dtNow); // TOD#7:8:38
datNow := TO_DATE(dtNow); // D#2018-6-6

A further edition of IEC 61131-3 has added some additional data types. This is also the case in CODESYS.

• LDATE: Nanoseconds since Thursday, 1.1.1970 00:00:00, managed in a 64 Bit data type like LINT

• LTIME_OF_DAY or LTOD: Nanoseconds since 00:00:00, managed in a 64 Bit data type like ULINT (Modulo LTIME#1d)

• LDATE_AND_TIME or LDT: Nanoseconds since Thursday, 1.1.1970 00:00:00, managed in a 64 Bit data type like LINT

Starting with data type LDATE_AND_TIME, variables of the other data types can be assigned accordingly. A variable of type LDATE_AND_TIME can be initialized with a current value with the help of the CODESYS runtime system’s functions SysTimeRtcHighResGet.

See: Naming Conventions for variables of type ULINT, LDATE, LTIME_OF_DAY and LDATE_AND_TIME.

VAR
    stUTC_DateAndTime : SYSTIME;

    Result : RTS_IEC_RESULT;

    ldtNow : LDATE_AND_TIME;
    ltodNow : LTIME_OF_DAY;
    ldatNow : LDATE;
END_VAR

Result := SysTimeRtcHighResGet(stUTC_DateAndTime); // UlINT#1738934115369

ldtNow := TO_LDT(stUTC_DateAndTime * LTIME#1ms); // LDT#2025-2-7-13:15:15.369000000
ltodNow := TO_LTOD(ldtNow); // LTOD#13:15:15.369000000
ldatNow := TO_LDATE(ldtNow); // LD#2025-2-7

The CODESYS runtime system specifies some additional data types:

• Standard udiTimeStamp (UDINT) Seconds since Thursday, 1.1.1970 00:00:00

• High Resolution uliTimeStamp (ULINT) Milliseconds since Thursday, 1.1.1970 00:00:00.000

• SysTimeDate (STRUCT)

  wYear : UINT; // Year (e.g. 2006)
  wMonth : UINT; // Month (1..12: January = 1, December = 12)
  wDay : UINT; // Day of month (1..31)
  wHour : UINT; // Hours after midnight (0..23)
  wMinute : UINT; // Minutes after hour (0..59)
  wSecond : UINT; // Seconds after minute (0..59)
  wMilliseconds : UINT; // Milliseconds after second (0..999). Optional!
  wDayOfWeek : UINT; // Day of week (1..7: Monday = 1, Sunday = 7
  wYday : UINT; // Day of year (1..365): January 1 = 1, December 31 = 364/365
  

  See: SYSTEMTIME structure

Getting Date and Time (UTC)¶

The CODESYS runtime system provides the following functions for getting the current date and time in the UTC timezone:

• SysTimeRtcGet: Returns the date and time in seconds since Thursday, 1.1.1970 00:00:00, managed in a 32 Bit data type like UDINT

• SysTimeRtcHighResGet: Returns the date and time in milliseconds since Thursday, 1.1.1970 00:00:00.000, managed in a 64 Bit data type like SysTime

Converting from UTC to Localtime¶

The CODESYS runtime system provides the following functions for converting the current date and time from the UTC timezone to the local timezone:

• SysTimeRtcConvertHighResToLocal: Converts a high resolution Time format SysTime to Localtime in the SysTimeDate format.

• SysTimeRtcConvertDateToHighRes: Converts the time given by time in the SysTimeDate format into a High Resolution Time of format SysTime.

VAR
    stUTC_Timestamp : SysTime;
    stLocal_TimeStamp : SysTime;
    stdNow : SysTimeDate;

    Result : RTS_IEC_RESULT;

    dtNow : DATE_AND_TIME;
    todNow : TIME_OF_DAY;
    datNow : DATE;
END_VAR

Result := SysTimeRtcHighResGet(stUTC_Timestamp); // ULINT#1528273494913
Result := SysTimeRtcConvertHighResToLocal(stUTC_Timestamp, stdNow);

// stdNow.wYear = UINT#2018
// stdNow.wMonth = UINT#6
// stdNowy.wDay = UINT#6
// stdNow.wHour = UINT#10
// stdNow.wMinute = UINT#24
// stdNow.wSecond = UINT#54
// stdNow.wMilliseconds = UINT#913
// stdNow.wDayOfWeek = UINT#3
// stdNow.wYday = UINT#157

Result := SysTimeRtcConvertDateToHighRes(stdNow, stLocal_TimeStamp); // ULINT#1528280694913

dtNow := TO_DT(stLocal_TimeStamp / TIME#1ms); // DT#2018-6-6-10:24:54
todNow := TO_TOD(stLocal_TimeStamp MOD TO_ULINT(T#1D)); // TOD#10:24:54.913
datToday := TO_DATE(dtNow); // D#2018-6-6

Converting from Localtime to UTC¶

The CODESYS runtime system provides the following function for converting the current date and time from the local timezone to the UTC timezone:

• SysTimeRtcConvertLocalToHighRes: Converts the date and time given by SysTimeDate structure (localtime) into a high resolution time of type SysTime (UTC)

VAR
    stdNew : SysTimeDate;
    stUTC_Timestamp : SysTime;
END_VAR

// stdNew.wYear = UINT#2018
// stdNew.wMonth = UINT#6
// stdNew.wDay = UINT#6
// stdNew.wHour = UINT#10
// stdNew.wMinute = UINT#24
// stdNew.wSecond = UINT#54
// stdNew.wMilliseconds = UINT#913

Result := SysTimeRtcConvertLocalToHighRes(stdNew, stUTC_Timestamp); // ULINT#1528273494913

Support from the Util.library¶

To handle the local time, it is necessary to always specify the time and date and the time zone that is currently valid. This makes it possible to convert the local time to Coordinated Universal Time and vice versa. UTC is Coordinated Universal Time. It is a successor to, but distinct from, Greenwich Mean Time (GMT) and the various definitions of Universal Time. UTC is now the worldwide standard for regulating clocks and time measurement.

All other timezones are defined relative to UTC, and include offsets like UTC+0800 - hours to add or subtract from UTC to derive the local time. No daylight saving time occurs in UTC, making it a useful timezone to perform date arithmetic without worrying about the confusion and ambiguities caused by daylight saving time transitions, your country changing its timezone, or mobile computers that roam through multiple timezones.

The following snippet exposes the definition of UTC and CentralEuropeTime/CentralEuropeSommerTime.

VAR_GLOBAL CONSTANT
    /// Coordinated Universal Time
    gc_tzTimeZoneUTC : TimeZone := (asgPeriod := [(sName:='UTC')]);

    /// Central Europe Time
    gc_tzTimeZoneCET : TimeZone :=
    (
        iBias := 60 (* T#1M => minutes *),
        asgPeriod := [
        ( (* (CEST -> CET) - Last Sunday in Oktober at 03:00:00.000 (CEST) *)
            sName:='CET',
            dtDate := (uiMonth := 10, eWeekday := WEEKDAY.SUNDAY, uiDay := 5, uiHour := 3)
        ),( (* (CET -> CEST) - Last Sunday in March at 02:00:00.000 (CET) *)
            sName := 'CEST',
            dtDate := (uiMonth := 3, eWeekday := WEEKDAY.SUNDAY, uiDay := 5, uiHour := 2),
            iBias := 60 (* T#1M => minutes *)
        )]
    );
END_VAR

Note

The Bias element represents the offset from the Coordinated Universal Time (UTC). This value is in minutes.

• The offset growing positive in eastern direction starting from the prime meridian.

• The offset is growing negative in western direction starting from the prime meridian.

See: List of UTC time offsets

With the data structure TimeZone it is possible to specify every timezone of the world and so the functions below can handle the local time conversion and the switching from standard to day light saving period’s if necessary.

iBiasUTC_Standard := gc_tzTimeZoneCET.iBias;
iBiasUTC_Daylight := gc_tzTimeZoneCET.iBias + gc_tzTimeZoneCET.asgPeriod[PERIOD.DAYLIGHT].iBias;

In version 3.5.14.0 and higher, the Util library provides the following functions:

Conversion from UTC timestamp (e.g. from SysTimeRtcHighResGet) to the current period and the local date and time related to the TimeZone parameter.

FUNCTION PUBLIC LocalDateTime : ULINT
VAR_IN_OUT CONSTANT
    tzTimeZone : TimeZone;
END_VAR
VAR_INPUT
    uliDateTime : ULINT;
END_VAR
VAR_OUTPUT
    eErrorID : ERROR;
    ePeriod : PERIOD; (* 1 = ``PERIOD.STANDARD``, 2 = ``PERIOD.DAYLIGHT`` *)
END_VAR

FUNCTION PUBLIC SplitDateTime : ERROR
VAR_INPUT
    uliDateTime : ULINT;
END_VAR
VAR_OUTPUT
    uiYear : YEAR; (* 1970..2106 *)
    uiMonth : MONTH;
    uiDay : DAY;
    uiHour : HOUR;
    uiMinute : MINUTE;
    uiSecond : SECOND;
    uiMilliseconds : MILLISECOND;
    eWeekday : WEEKDAY;
END_VAR

FUNCTION PUBLIC JoinDateTime : ULINT
VAR_INPUT
    uiYear : YEAR; (* 1970..2106 *)
    uiMonth : MONTH;
    uiDay : DAY;
    uiHour : HOUR;
    uiMinute : MINUTE;
    uiSecond : SECOND;
    uiMilliseconds : MILLISECOND;
END_VAR
VAR_OUTPUT
    eErrorID : ERROR := ERROR.NO_ERROR;
END_VAR

FUNCTION PUBLIC SeparateDateTime : ERROR
VAR_INPUT
    uliDateTime : ULINT;
END_VAR
VAR_OUTPUT
    eWeekDay : WEEKDAY;
    datDate : DATE;
    todTime : TIME_OF_DAY;
END_VAR

FUNCTION PUBLIC CombineDateTime : ULINT
VAR_INPUT
    datDate : DATE;
    todTime : TIME_OF_DAY;
END_VAR
VAR_OUTPUT
    eErrorID : ERROR;
END_VAR

FUNCTION PUBLIC WeekOfYear : ERROR
VAR_INPUT
    uliDateTime : ULINT;
END_VAR
VAR_OUTPUT
    uiYear : YEAR;
    uiWeek: WEEK;
    eWeekday : WEEKDAY;
END_VAR

FUNCTION DateTimeFromWeek : ULINT
VAR_INPUT
    uiYear : YEAR;
    uiWeek : WEEK;
    eWeekday : WEEKDAY;
END_VAR
VAR_OUTPUT
    eErrorID : ERROR;
END_VAR

Calculates the appropriate value of the WEEKDAY enum that matches the parameter datDate.

FUNCTION PUBLIC DayOfWeek : WEEKDAY
VAR_INPUT
    datDate : DATE;
END_VAR
VAR_OUTPUT
    eErrorID : ERROR;
END_VAR

Checks whether the year (uiYear) passed represents a leap year.

FUNCTION PUBLIC IsLeapYear : BOOL
VAR_INPUT
    uiYear : YEAR; (* 1970..2106 *)
END_VAR
VAR_OUTPUT
    eErrorID : ERROR;
END_VAR