Table of Contents

DateTime

Namespace
ZAux
Implements
FUNCTION_BLOCK DateTime IMPLEMENTS ZCore.IDateTime

Time-related operations in PLCs are uniquely implemented from every PLC-manufacturer. In IT it is standard to use the Unix time format beginning with 1.1.1970 and based on this, this class is giving this same time handling to Automation Engineers independently of its platform.

This function block should be used in every PLC-Runtime context where no Zeugwerk Framework is used. For usage inside this standardized framework one can use the DateTime class where running of the object is done by the framework automatically. Both classes are based on the DateTimeImpl class and offer various time-related operations, some of which are.

  • Synchronisation of PLC time with the Operation System (e.g. Windows). Desynchronisation of these two clocks occurs because the windows RTC is cyclically synced with internet time servers and the plc clock gets only updated (incremented) with the CPU time, which is not that precise. This task is performed cyclically with a parameterizeable period. Therefore, even though clocks are synchronized there may be a slight offset between calling UnixTimestamp and TimestampLocalPlc between a synchronization cycle. If the runtime would cyclically sync the PLC-Runtime-clock with the operating system clock this could cause problems in the realtime context.
  • Converting the timestamp value in one that is compatible to the standard unix timestamp. (e.g. for Beckhoff Twincat systems their timestamp starts on 1.1.1602)
  • Timezone correction
Note

Usually there is only one DateTime or DateTimeUM instance needed per PLC-Runtime-Instance.

For time measurement during one PLC-Cycle it is better to use the StopWatch Class in ZPlatform library which has a precision down to 100ns (CPU cycle tick)

Constructor

FB_init 

METHOD FB_init (
 [input] bInitRetains : BOOL,
 [input] bInCopyCode : BOOL,
 [input] parent : ZCore.IManagedObject) : BOOL

DateTime uses the usual parent initializer as it is common with most object that are used within the framework. For details refer to ManagedObject.

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

parent IManagedObject

Interface to the ManagedObject that is the parent of this object

Returns

BOOL

Properties

Bias 

PROPERTY Bias : LINT

Property Value

LINT

State 

PROPERTY State : ZCore.ObjectState

When starting the PLC, the DateTime object initializes its regional settings and syncs to the operating-system time. During this period, the object is in its booting state, only when initialization is finished, the object will obtain ObjectState.Idle. Everytime time object does a (re-)sync of the systemclock if the PLC clock, the object enters ObjectState.Busy.

IF _datetime.State() = ZCore.ObjectState.Idle OR_ELSE _datetime.State() = ZCore.ObjectState.Busy
THEN
 ; // _datetime object is ready to use
END_IF

Property Value

ObjectState

SynchronizationPeriod 

PROPERTY SynchronizationPeriod : LREAL

Controls the period (in seconds) in which the current time is synchronized with reported by the operating system.

Here, the operation system of the target is considered. Synchronization period defaults to 10 seconds and if the property is set to 0, synchronization is disabled.

Property Value

LREAL

Synchronized 

PROPERTY Synchronized : BOOL

This property returns TRUE if the object has a valid connection to a time syncing service, and the sync process has been successfully completed at least once. This usually occurs in the booting process and/or automatically after a period of time.

Property Value

BOOL

UtcOffset 

PROPERTY UtcOffset : LINT

Returns the actual Utc Offset which gets retrieved from the local OS Timezone information

Note

This property only returns valid information if the booting process of the object is finished, which can be checked with the State method.

Property Value

LINT

Methods

CalendarInfo 

METHOD CalendarInfo (
 [input] offset : LINT) : ZCore.IDateTimeCalendarInfo

Returns an interface to a Calendar info data object represented by IDateTimeCalendarInfo based on the actual date shifted by a given utc-offset.

Inputs

offset LINT

Returns

IDateTimeCalendarInfo

DeltaSecondsOs 

METHOD DeltaSecondsOs (
 [input] unixTimestamp : ULINT) : LREAL

Returns the time difference now - unixTimestamp in seconds. The parameter unixTimestamp is usually previously stored from a call to UnixTimestamp. This method should be prefered to calls to DeltaSecondsPlc that uses FILETIME timestamps in the local PLC context in contrast to this method.

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

Inputs

unixTimestamp ULINT

unix timestamp

Returns

LREAL

DeltaSecondsPlc 

METHOD DeltaSecondsPlc (
 [input] filetime : ULINT) : LREAL

see DeltaSecondsOs

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

Inputs

filetime ULINT

unix timestamp

Returns

LREAL

Now 

METHOD Now (
 [input] offset : LINT) : REFERENCE TO ZCore.DateTimeRecord

Returns a DateTime Record from now shifted by the given utc offset

Inputs

offset LINT

utc offset in milliseconds

Returns

REFERENCE TO DateTimeRecord

SetTarget 

METHOD SetTarget (
 [input] netid : ZCore.ZString)

Targetsystem where time information is retrieved from. If an empty string is used, the local target is used. For machines that are using several PLCs that are running on multiple computers, it is recommended to use the same DateTime target for all of them, because it facilitates in some cases, e.g. timestamp information in different logfiles are more precisely comparable to each other.

This method automatically causes DateTime to start (re-)initalization, which fill in turn fetch localization informations from the (new) target. During (re-)initalization the methods of the object should not be used. The current state of DateTime can be externally retrieved by the State method.

For Beckhoff Twincat specific PLC-Runtimes this should be given as a AMS-Net-Id string (e.g. 200.200.210.4.1.1).

Inputs

netid ZString

AMS-Net-Id, e.g. 200.200.210.4.1.1

SetTimeout 

METHOD FINAL SetTimeout (
 [input] timeout : LREAL)

Set timeout for unresponsive targets. This is usually only relevant if the target is not the local PLC.

Inputs

timeout LREAL

in seconds (defaults to 3s)

TimestampLocalPlc 

METHOD TimestampLocalPlc () : ULINT

Returns the current timestamp in the filetime format with 100ns resolution. This time may differ vastly from the time information that the operation system shows, because over time PLC time and OS time may drift appart. If the actual time information is more important that tick counts, the method UnixTimestamp should be used that is returning timestamps that are synchronized to OS time.

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

Returns

ULINT

UnixTimestamp 

METHOD UnixTimestamp () : ULINT

Returns the actual timestamp in unix time format (beginning on 1.1.1970) cyclically corrected with the generated time lag between OS-time (which gets cyclically synced with the internet time) and the plc-runtime-time which gets just incremented over the CPU-Tick-Counter. The returned timestamp has a resolution of 1ms.

If the UnixTimestamp needs to be corrected via UTC-Offset, just add the value of UtcOffset to the return of this method.

Note

This method only returns valid information if the booting process of the object is finished, which can be checked with the State method.

Returns

ULINT