Tutorial: D2000 and work with time - part II

From the point of view of Winter Time -> Summer Time -> Winter Time transitions, the periodic actions are interesting. What does „every eight hours“ mean? When going to Summer Time, is it 0:00, 8:00, 16:00 or 0:00, 9:00, 17:00? What is good?

Read previous article to catch this topic

Explanations about time zones and working with time changes in D2000.

Work with time part 1.

Before answering this question, let's take a look at how the time is represented in D2000.

D2000 - time representation

Time in D2000 is represented by the Long_Float type - which is an 8-byte real number with an accuracy of 15 digits. Internal accuracy is limited to 1 [ms] - in all processes.

Its value is the number of seconds that elapsed since "about 1970" - the exact date is not important, and in the future it may be changed (to preserve accuracy to 1 ms). Internally, time in D2000 is increasing monotonically, and it does not jump up/down during winter and summer time transitions. However, the user usually needs time data displayed locally depending on the operating system, application, and startup parameters (details will be given below).

Each value in the D2000 application has an assigned timestamp. You can find it as the value of the attribute of a local variable, a system object, or a structure item (such as _locVar\TIM). Each application has a list of predefined time objects that provide individual components of a system time.

Figure 9: List of predefined time objects in D2000

D2000 - implementation of time zones

Each D2000 process runs in a particular time zone. This is given by the client location (parameter detected from the operating system), which can be explicitly overriden in the HI process using the start parameter /TZ. In addition, it is possible to use the application parameter UseServerTimeZone to globally set the D2000 Server time zone and to ignore the operating system configuration as well as the /TZ parameter.

Figure 10: The value of SysTime object is displayed in two different time zones. ‌‌Purple HI has an explicitly set time zone with a time offset of 3 hours.

D2000 – functions for work with time and time intervals

All D2000 functions that work with local time also have the optional timeZone parameter to change the time offset. If the parameter is not specified, the %GetTimeZone is automatically used (the time zone valid for the process in which the function is being evaluated - i.e., HI, EVENT or CALC).

The %AddIntervalLocal function is used to add a time interval in local time. The function adds a relative time (which may be also a negative number) to absolute time. The result will not be affected by any time transitions during this time interval. For example, adding 3 hours to 1:00 AM will always give the result 4:00 AM.
Note: %AddTime function (old name %AddTimeT) and %SubTime (old name %SubTimeT) are internally implemented the same way as %AddIntervalLocal.

%AddIntervalMono function is used to add a time interval in monotonic time. The function adds a relative time to absolute time. The result will be affected by any time transitions during this time interval. For example, adding 3 hours to 1:00 AM may result in 3:00 AM (transition to Winter Time), 4:00 AM (a normal day) or 5:00 AM (transition to Summer Time).

The %NewTime function (old name %NewTimeT) adds to the absolute time the relative time expressed as the number of years, months, days, seconds. The function works with local time.

The %SubTimesLocal function subtracts two absolute times. The result will not be affected by any time transitions during this time interval. For example, the difference between 4:00 AM and 1:00 AM is always 3 hours.

The %SubTimesMono function subtracts two absolute times. The result will be affected by any time transitions during this time interval. For example, the difference between 4:00 AM and 1:00 AM in Slovakia may be 2 hours (transition to Summer Time), 3 hours (a normal day) or 4 hours (transition to Winter Time).

D2000 – operations with time in expressions

Figure 11: Operators, types of values, and results of operations when working with time

Comparison operators work according to the intuition (new time is bigger than old time).

It is possible to add an integer or real number to absolute time and the result is again absolute time (and it is added in localtime).

Two absolute times can be subtracted (the result is the number of seconds between them - be careful, in monotonic time, i.e. the result depends on whether the time transition was  in given time interval).

From absolute time it is possible to subtract an integer or real number and the result is again an absolute time (subtraction is in local time, so the operation is inverse to addition).

D2000 – time of values in expressions

Calculation of the expression sets the timestamp  of the result value equal to the current time. Take an ESL script:

INT _i

TIME _b, _e
REAL _duration
_b := 1
; ... some activity
_e := 1
_duration := _e\TIM - _b\TIM; duration of "some activity" in [sec]

By remembering the start time (timestamp of the variable _b after assignment of 1) and the end time (timestamp of the variable _e) and subtraction of the timestamps, it is possible to find out (with the precision of the timestamp, i.e. 1 ms) how long the ESL script was performed.

D2000 – work with a period

The %NextTime function (old name %NextTimeT) returns the value of the next timestamp from the current time that is given by the period and offset. Function works with local time.

Beware of periods that can not be divided into a whole day. For example:
Period=16 [h]
Offset = 1 [s]
the function will give the times 00:00:01, 16:00:01, 08:00:01, 00:00:01 as shown in the figure 12.

Figure 12: If the day is not an integer multiple of the period,‌‌the function % NextTime will give different results at different days

If a period is defined in the configuration of a periodic evaluated tag, a statistical archive object or a periodic calculated archive object, it is necessary that the day has to be its integer multiple. Thus the periods 1h, 2h, 3h, 4h, 6h or 30minutes are all right, periods 5h or 35 minutes will not be accepted.

The period configuration also includes the choice of local time or monotonic  time.  It depends on whether the calculation should always be the same time of the local time (e.g. 0,8,16,0 for an 8-hour period) or in the case of monotonic time in the summer one hour later (1,9,17,1 for 8 hour period).

The function %NextMonth returns start time of the next month (from the current time) shifted by the specified offset. The function works with local time.

D2000 – conversions between UTC time and „local time“

The D2000 offers several functions that can be used to convert between UTC and local time. The conversion necessarily needs to be informed about the time zone from/into which the conversion  is performed, so these functions also use the timeZone parameter.

Function %StrToTimeEx converts text to an absolute time. Example:
%StrToTimeEx("17:03:16 18-03-17", "hh:mi:ss dd-mm-rr")

If the time is ambiguous (the time between the second and the third hour during transition to Winter Time), the function returns later time (Winter). To distinguish between "first" and "second" 2nd hour it is possible to write A2 and B2. For example, time A2: 05:30 will be converted as Summer Time.

Figure 13: Strings used in format of function %StrToTimeEx

The function %TimeToStrEx converts time to text. The mask supports syntax according to Figure 13, plus  can be used to convert the name of the day to text by means of a dictionary (tt, ttt, tttt).

Figure 14: Masks to convert a day's name to text using a dictionary

The function %TimeFromItems can be used to convert local component time (year, month, day, hour, minute, second, miliseconds) to absolute time.

The %Year, %Month, %Day, %Hour, %Min, %Sec, %MSec functions can be used to extract the specific component from the absolute time.

D2000 – work with relative time

Relative time is a real number that indicates the duration of the interval (in seconds). Therefore, the relative time does not depend on the time zone or summer time.

The %RelTimeToStr function (old name% RTToStr) is used for conversion to the text form:

TEXT %RelTimeToStr(TIME in _time, TEXT in _mask)
%RelTimeToStr(86400+7200+120+2, "ddd hh:mi:ss.mss")

Reverse text conversion to the relative time is done by the %StrToRelTime function (the text must correspond to the mask "ddd hh: mm: ss") and %StrToRelTimeEx (the mask can be specified):

REAL %StrToRelTimeEx(TEXT in _time, _mask)
%StrToRelTimeEx ("156 14:23:25","ddd hh:mi:ss")

D2000 – other functions for work with time

The %WeekNr function is used for finding the week number (1-53). For January 1st it returns value 1.

The %WeekOfYear function is similar, but it respects the calendar definition (the first week is the one in which there are at least 4 days in this calendar year). For example, the year 2012 started on Sunday, which was in the 52nd week, and ended with week 24th-30th December (which was 52nd) and Monday - New Year's Eve 31st December 2012 was already in the 1st week of the following year.

The %WeekStartTime function returns the start time of the week with the specified week number (see %WeekNr). For example, the first week of 2012 began on 26th December 2011.

Conversions between time and text without taking into account Summer Time is performed by %TimeToStrMono and %StrMonoToTime functions.  Both allow to specify the time offset from UTC  (in seconds).

The %LocalToMonoTime function returns the Absolute Time value. This is the same as the input parameter value for the winter times. For summer times, the entered value is reduced by 1 hour.

The %ModTime function returns the remainder of the absolute time divided by the length of the time interval (relative time). The result is a Relative Time value.

D2000 – time in the databases

The DbManager process communicates with databases via ODBC or OCI interface, using a component time format. The method of conversion to individual components and taking into account time zones and DST can be configured on a object  of Database type:

Figure 15: Setting local or monotonic time‌‌ (with a defined offset in hours) on the object of Database type

D2000 – CSV exports and imports

IMPORT_CSV and EXPORT_CSV actions are designed for import or export of data from/to CSV files. When importing/exporting timestamps or absolute time type values, bMonoTimes parameter specifies whether the conversion takes place in local time (taking into account DST) or local monotonic time. The time offset can not be set – the current time zone is used.

If CSV files are used to transfer between D2000 and other systems, we recommend the use of monotonic time - so problems with ambiguous times don’t occur during the transition to Winter Time.

D2000 – time in communication

If the communication protocol does not support the transfer of timestamps (e.g. Modbus), the timestamps of the values from the communication are assigned by the KOM process automatically.

If the communication protocol supports timestamps, the configuration of the Station type object determines whether the communication time is used, or the timestamp is assigned by KOM (parameter "Use computer time").

If time from communication is used, it can be configured to be interpreted as local (with DST) or monotonic with a defined time offset (parameter "Use monotonic UTC time +"). Similarly, the time of the output I/O tags written by the KOM process is converted to the appropriate type (local or monotonic) according to this configuration.

Some protocols (OPC, IEC104) also allow the transmission of a time validity flag. If time is invalid, the timestamp of values from the communication will be assigned by the KOM process again.

Some protocols also support the transmission of Daylight Saving Time flag (e.g. IEC101, IEC104 - see "SU" - SUmmer in Figure 10 at the end of the first part of the IEC101 blog). If an object of Station type is configured to use local time, the protocol flag will be used to distinguish between Summer and Winter Time in case of an ambiguous 2nd hour, when Summer Time changes to Winter Time. In case of monotonic time configuration, the flag is ignored.

Be careful - we recommend not to rely on these flags but if possible, configure communications in monotonic time - so time-change problems are eliminated. Not every system implements these flags properly - we have experience with the older ABB Microscada system that sent the "SU" flag set in the IEC104 protocol regardless of Summer or Winter Time.

Figure 16: Time parameters in configuration of object of Station type

Figure 16 shows, besides configuration of timestamps and local/monotonic time, also configuration of polling parameters (how often the values  of I/O tags of this station should be read from the communication). Polling can be with the specified period (unlike the periodic calculations, the period may be arbitrary) or with a delay (the delay is defined as the time between the end of one reading of values and the beginning of the next one). Therefore, the longer reading of values does not affect the time of the next reading in the configuration with the specified period, but it will shift the time of the subsequent reading in the configuration with specified delay.

If the communication protocol also supports time synchronization (e.g. IEC104, BACnet, ESC8816), it is also possible to configure this.
The timestamp will be sent in local or monotonic time according to the parameter "Use monotonic UTC time +" to be in the same format as the read and written values.

Logical day configuration in D2000 HI

When a user in the D2000 HI process works with the dialog for choosing time interval, he may want different specialties from the system. For example:

  • When choosing the whole day or several days not to mark time from zero hour (the default value) but e.g. from the sixth hour (so-called gas day).
  • To display the day from the zero second of the first day selected till last second of the last day selected (e.g. 1.1.00.00:00 - 5.1.25:59:59) or till zero second of the next day (e.g. 1.1. 00: 00:00 - 6.1. 00:00:00).

The D2000 Server parameters day_start_hour, day_start_min, day_end_hour, day_end_min can be used to set the beginning and the end of the so-called logical day, and the parameter day_end_strong_ineq can be used to include the first second of the next day.

Figure 17: Dialog for selecting a time interval while a logical day is configured from 6th to 30th hour (i.e. until 6:00 am the next day). When a time interval July 30th 2018 to August 2nd 2018 is selected using the mouse, the input fields in the calendar will be filled as July 30th 2018 6:00 am - August 3rd 2018 6:00 am.

These parameters can be also entered in the user-controlled opening of the dialog window to select the time interval from the picture‘s script using the %HI_SelectTimeDialog function.

Conclusion

The theme of work with time in real-time systems is of course rich. This article attempted to review the D2000 options from a perspective  of user - system configurator. It is always necessary to keep in mind the type of time we work with (local/monotonic) and what kind of time we want to convert it to for the needs of a user, another system, a communication partner or a database. The variety of this theme is given by the fact that the user mostly wants to see the data in the local time, including the time shift due to the Summer Time, but it is more conv enient for the control system to work with monotonic time that is unambiguous and does not jump. Interfaces to the environment (export to text files, databases, communications) must offer both alternatives.