Date and time functions

These functions operate on the temporal types (TIME, LTIME, DATE, LDATE, TOD, LTOD, DT, LDT). They cover three areas: arithmetic on durations and date/time values, composing/decomposing date/time values, and reading the runtime device clock. To convert between temporal types (e.g. TIME_TO_LTIME), use the conversion functions.

Arithmetic

Function	Parameters	Returns
ADD_TIME	IN1 : TIME, IN2 : TIME	TIME
ADD_LTIME	IN1 : LTIME, IN2 : LTIME	LTIME
ADD_TOD_TIME	IN1 : TOD, IN2 : TIME	TOD
ADD_LTOD_LTIME	IN1 : LTOD, IN2 : LTIME	LTOD
ADD_DT_TIME	IN1 : DT, IN2 : TIME	DT
ADD_LDT_LTIME	IN1 : LDT, IN2 : LTIME	LDT
SUB_TIME	IN1 : TIME, IN2 : TIME	TIME
SUB_LTIME	IN1 : LTIME, IN2 : LTIME	LTIME
SUB_DATE_DATE	IN1 : DATE, IN2 : DATE	TIME
SUB_LDATE_LDATE	IN1 : LDATE, IN2 : LDATE	LTIME
SUB_TOD_TIME	IN1 : TOD, IN2 : TIME	TOD
SUB_LTOD_LTIME	IN1 : LTOD, IN2 : LTIME	LTOD
SUB_TOD_TOD	IN1 : TOD, IN2 : TOD	TIME
SUB_LTOD_LTOD	IN1 : LTOD, IN2 : LTOD	LTIME
SUB_DT_TIME	IN1 : DT, IN2 : TIME	DT
SUB_LDT_LTIME	IN1 : LDT, IN2 : LTIME	LDT
SUB_DT_DT	IN1 : DT, IN2 : DT	TIME
SUB_LDT_LDT	IN1 : LDT, IN2 : LDT	LTIME
MUL_TIME	IN1 : TIME, IN2 : ANY_NUM	TIME
MUL_LTIME	IN1 : LTIME, IN2 : ANY_NUM	LTIME
DIV_TIME	IN1 : TIME, IN2 : ANY_NUM	TIME
DIV_LTIME	IN1 : LTIME, IN2 : ANY_NUM	LTIME

The naming encodes the operand types: ADD_DT_TIME adds a TIME duration to a DT; SUB_DT_DT subtracts two DT values to yield the TIME between them.

deadline  := ADD_DT_TIME(start, T#2h);        // DT + duration -> DT
elapsed   := SUB_DT_DT(finish, start);        // DT - DT -> TIME
total     := ADD_TIME(setup, run);            // TIME + TIME -> TIME
doubled   := MUL_TIME(base, 2);               // TIME * number -> TIME
slice     := DIV_TIME(period, 4);             // TIME / number -> TIME

Composition and decomposition

Function	Parameters	Returns / outputs
CONCAT_DATE_TOD	IN1 : DATE, IN2 : TOD	DT
CONCAT_DATE_LTOD	IN1 : DATE, IN2 : LTOD	LDT
CONCAT_DATE	YEAR, MONTH, DAY : ANY_INT	DATE
CONCAT_TOD	HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT	TOD
CONCAT_LTOD	HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT	LTOD
CONCAT_DT	YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT	DT
CONCAT_LDT	YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT	LDT
SPLIT_DATE	in IN : DATE	out YEAR, MONTH, DAY : ANY_INT
SPLIT_TOD	in IN : TOD	out HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT
SPLIT_LTOD	in IN : LTOD	out HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT
SPLIT_DT	in IN : DT	out YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT
SPLIT_LDT	in IN : LDT	out YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT
DAY_OF_WEEK	IN : DATE	INT

CONCAT_DATE(YEAR : ANY_INT, MONTH : ANY_INT, DAY : ANY_INT) : DATE
CONCAT_DT(YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND : ANY_INT) : DT

today  := CONCAT_DATE(2026, 6, 8);             // DATE#2026-06-08
stamp  := CONCAT_DT(2026, 6, 8, 14, 30, 0, 0); // DT#2026-06-08-14:30:00
joined := CONCAT_DATE_TOD(today, TOD#08:00:00);

DAY_OF_WEEK (a logiccloud extension) returns the weekday of a DATE as an INT where Sunday = 0, Monday = 1, …, Saturday = 6.

DAY_OF_WEEK(IN : DATE) : INT

weekday := DAY_OF_WEEK(D#2026-06-08);   // 1 (Monday)

Note

The SPLIT_* functions have no return value; their results are delivered through output parameters, so they are called with => bindings:

SPLIT_DT(IN := now, YEAR => y, MONTH => mo, DAY => d,
         HOUR => h, MINUTE => mi, SECOND => s, MILLISECOND => ms);

System clock

These are logiccloud extensions that read the runtime device clock. All three return a DT (DATE_AND_TIME).

Function	Parameters	Returns	Description
SYS_UTC_DATE_TIME	(none)	DT	Current date/time in UTC.
SYS_LOCAL_DATE_TIME	(none)	DT	Current date/time in the runtime’s local time zone.
SYS_DATE_TIME	TZ : STRING	DT	Current date/time in the named time zone.

SYS_DATE_TIME takes an IANA time-zone name (e.g. 'Europe/Berlin', 'America/New_York', 'UTC').

SYS_UTC_DATE_TIME() : DT
SYS_LOCAL_DATE_TIME() : DT
SYS_DATE_TIME(TZ : STRING) : DT

nowUtc    := SYS_UTC_DATE_TIME();
nowLocal  := SYS_LOCAL_DATE_TIME();
nowBerlin := SYS_DATE_TIME('Europe/Berlin');

Caution

The TZ argument to SYS_DATE_TIME must be a valid IANA time-zone name. An unknown or malformed zone string cannot be resolved and faults the runtime — validate any operator/HMI-supplied value before passing it in, and prefer a hard-coded literal where the zone is fixed.