Table of Contents

DateTimeImpl

Namespace
ZPlatform
Extends
Inherited Properties
Inherited Methods
Implements
FUNCTION_BLOCK DateTimeImpl EXTENDS ZPlatform.PlatformAdapterManagedObject IMPLEMENTS ZCore.IManagedObject, ZCore.IObject, ZCore.IBootable, ZCore.IError (
 [output] State : ObjectState)

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, if executed cyclically by calling Cyclic performs the following actions.

  • 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
  • The time can be synced either locally or to a remote target.
    • If the remote target is not available at booting, the function block transitions to BootingError and fallback to local target synchronization. It will automatically retry to establish a connection to the selected remote target by a timer that triggers with the configured timeout. The State=BootingError and Synchronized=FALSE as long as the function block can not connect the remote target.
    • If the remote target is changed during operation and is no longer available or time sync is no longer possible, the function block transitions into State=Error and Synchronized returns FALSE. The function block will automatically retry to establish a connection to the selected remote target by a timer that triggers with the configured [timeout](xref:ZPlatform.DateTimeImpl#SetTimeout. Since at this time the clock drift with respect to the (remote) clock is known due to prior synchronization, there is no fallback to local target synchronization.

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

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

SystemTime 

PROPERTY PROTECTED SystemTime : ULINT

Property Value

ULINT

UtcOffset 

PROPERTY UtcOffset : LINT

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

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.

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

offset LINT

Returns

IDateTimeCalendarInfo

Cyclic 

METHOD Cyclic ()

Cyclic method which is responsible for the calculation of the timestamp delta between operating system time and plc time. initially this methods read the actual configured timezone from the operating system and from that time on the returned time values are corrected according to this timezone value.

DeltaSecondsOs 

METHOD DeltaSecondsOs (
 [input] timestamp : 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

timestamp 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
Note

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

Inputs

offset LINT

Returns

REFERENCE TO DateTimeRecord

SetSynchronizationPeriod 

METHOD SetSynchronizationPeriod (
 [input] timeout : LREAL)

Set the timeout when realtime clock should be synchronised with the OS (Windows) clock. Use timeout = 0 to disable synchronization, but keep in mind that disabling time synchronization will cause the timestamps that are returned by UnixTimestamp to drift apart the actual OS time. It is recommended to set the synchronization timeout in the range of several seconds and it defaults to 10 seconds.

Inputs

timeout LREAL

in seconds

SetTarget 

METHOD SetTarget (
 [input] target : 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

target ZString

SetTimeout 

METHOD 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)

StoreTargetUtc 

METHOD PROTECTED StoreTargetUtc (
 [input] systemTime : ULINT)

Helper method that stores the target timetamp in UTC

Inputs

systemTime ULINT

Timetamp from SystemTime() -> Tc2_System.F_GetSystemTime()

Timeout 

METHOD Timeout () : LREAL

Returns the timeout for unresponsive target detection, which is set by SetTimeout and defaults to 3s.

Returns

LREAL

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, one of the methods should be used that are returning timestamps that are synchronized to OS time. UnixTimestamp

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