Date and time

Date and time functions create datetime values (a point in time) and timespan values (a duration). They work in every script — smart rules, notifications, Modbus and Packet parser — and use the time zone of the control unit. All functions on this page need Core 2022.2 or newer.

NOW#

NOW returns the current date and time of the control unit as a datetime value — local time by default, UTC with NOW(Utc).

1
2

NOW()
NOW(kind)

Remarks — A property cannot be read directly from a function call: NOW().HOUR is rejected when you save the script. Store the value in a variable first.

Example

VAR now := NOW();
now.HOUR;
# Result: the current hour, 0 to 23

See also — DATETIME, Properties of datetime values.

DATETIME#

DATETIME creates a datetime value from its parts, from text or from a number of milliseconds; called without arguments it returns 1.1.0001 00:00, not the current time — use NOW for that.

1
2
3
4
5

DATETIME(year, month, day [, hour [, minute [, second [, millisecond [, kind]]]]])
DATETIME(text [, format])
DATETIME(text, kind)
DATETIME(milliseconds [, kind])
DATETIME()

Remarks

• Text without a format is read according to the language settings of the control unit. Use ISO 8601 ("2026-01-15T08:30:00") or pass a format so the result does not depend on them.
• Text with an offset or Z ("2026-01-15T08:30:00Z") is kept as a UTC value. With kind set to Utc, text without zone information is read as UTC.
• For Unix time, set the UNIXTIME property.

Example

VAR start := DATETIME(2026, 1, 15, 8, 30, 0);
VAR iso := DATETIME("2026-01-15T08:30:00");
VAR custom := DATETIME("15.01.2026 08:30", "dd.MM.yyyy HH:mm");
VAR utc := DATETIME(2026, 1, 15, 8, 30, 0, 0, DateTimeKind.Utc);
custom.MINUTE;
# Result: 30

DATETIMEADD#

DATETIMEADD returns a new datetime moved by the given number of years, months, days, hours, minutes, seconds and milliseconds; negative numbers move it back.

1

DATETIMEADD(datetime, years [, months [, days [, hours [, minutes [, seconds [, milliseconds]]]]]])

Remarks — The original value does not change. Adding a month to 31 January gives the last day of February. To add an interval, you can also use + with a timespan or with a number of milliseconds.

Example

VAR now := NOW();
VAR tomorrow := DATETIMEADD(now, 0, 0, 1);
VAR twoHoursAgo := DATETIMEADD(now, 0, 0, 0, -2);
VAR endOfFebruary := DATETIMEADD(DATETIME(2026, 1, 31), 0, 1);
endOfFebruary.DAY;
# Result: 28

TIMESPAN#

TIMESPAN creates a timespan value — a duration — either from milliseconds or from days, hours, minutes, seconds and milliseconds.

1
2

TIMESPAN(milliseconds)
TIMESPAN(days, hours, minutes, seconds, milliseconds)

Properties (read-only)

Remarks

• Only the 1- and 5-argument forms exist; 2 to 4 arguments stop the script.
• timespan ± timespan gives a timespan, datetime ± timespan a datetime.
• Subtracting two datetime values is not defined. For the time between two dates, subtract their TICKS (milliseconds).
• Declaring a variable with the timespan type keyword needs Core 2023.2 or newer.

Example

VAR t := TIMESPAN(1, 2, 3, 4, 0);
t.TOTALSECONDS;
# Result: 93784

VAR start := DATETIME(2026, 1, 15, 8, 0, 0);
VAR stop := DATETIME(2026, 1, 15, 9, 30, 0);
(stop.TICKS - start.TICKS) / 60000;
# Result: 90 (minutes)

Errors — TIMESPAN Unsupported number of parameters; Operator ‘-’ not defined for ‘DateTime’ and ‘DateTime’.

LOCALTIMEZONE#

LOCALTIMEZONE returns the current offset of the control unit’s time zone from UTC in milliseconds, daylight saving time included.

1

LOCALTIMEZONE()

Example

LOCALTIMEZONE() / 3600000;
# Result: 1 in Central European winter time, 2 in summer time

Properties of datetime values#

A datetime value has these properties. Read them from a variable, not from a function call.

Remarks

• Outside a function argument an enum value is written with its type: DayOfWeek.Saturday. A bare Saturday is an unknown variable.
• <, > and = compare two datetime values as moments in time, so values of different KIND compare correctly.
• Writing a value outside the range stops the script, for example Value must between 0-23.
• Without a format, TOSTRING prints a datetime as yyyy/MM/dd hh:mm:ss.fff — a 12-hour clock without AM or PM. Pass a format such as "yyyy-MM-dd HH:mm".

Example — no action at the weekend

VAR now := NOW();
IF now.DAYOFWEEK = DayOfWeek.Saturday OR now.DAYOFWEEK = DayOfWeek.Sunday
    RETURN(0);
END
1;

Example — date from a Unix timestamp

datetime d;
d.UNIXTIME := 1767225600;
d.YEAR;
# Result: 2026 (1 January 2026, 00:00 UTC)

See also — Format strings, Data types.