Time and Date

Within VTScada, all logging is done using UTC timestamps. Most other time-related tasks will use the current time of the server running the application. Code that refers to the time of day will typically use either Now or Seconds, both of which return the number of seconds into the current day in the machine's time zone. Code that refers to a date will typically use the Today function, which returns the number of days (also in the current time zone) since the beginning of the standard Unix epoch (January 1, 1970). Formatting functions are available to translate those values into human-friendly time and date displays. The CurrentTime function returns a combination of the two as a timestamp value, defaulting to UTC time, but available for any time zone.

Recorded timestamps and all internal logic should use UTC, with conversion to the current user's timezone happening at display time. Do not use Now, Seconds, or Today for recorded timestamps or for internal logic.

Time Zones, Daylight Savings Time

Universal Coordinated Time (UTC) is indifferent to time zones and daylight savings time. Time proceeds at the rate of one second per second, and each day begins at midnight Greenwich Mean Time. The ConvertTimeStampfunction is available to help you convert from one time zone to another, including to and from UTC.

Units for Time:

Now() returns an even number of seconds, updating according to the provided numeric parameter. Seconds returns a double value slightly more accurate than 1 microsecond, however, when that value is assigned to a float type variable, it is rounded to about 7 significant digits. This can reduce the accuracy, especially later in the day when the seconds count becomes large. To obtain a reasonably accurate time stamp, the expression Seconds % 1 can be used to return fractions of a second since the last second mark.

These date and time numbers may be manipulated to determine elapsed time between two events simply by taking the difference between the time and date of the two events. One of the more effective ways to accomplish this is by using the CurrentTime function. You can use the single date and time number that is returned by this function to easily calculate the elapsed time between events or to calculate the date and time at a fixed offset.

By using UTC, you also avoid errors if the time interval spans the start or end of daylight savings time in the local time zone. Always use UTC timestamps for internal logic, converting to the user's time zone only for display purposes.

The date and time numbers can be converted into text values for display purposes using the Date and Time functions. The values returned from these functions may have a variety of formats and may be displayed on the screen using a GUIText statement. The Now function can be used in a statement to give the time suitable for a Time function, or to display a simple clock.

Numeric values of the day, month, and year may be extracted from a VTScada date value (number of days since January 1, 1970) using the Day, Month, and Yearfunctions. The reverse process of combining the day, month, and year may be done using DateNum.

 

Note that Date() expects days since Jan 1, 1970 and that Time() expects seconds since midnight. Given a UTC timestamp (SomeTimestamp) in seconds since Jan 1, 1970 and the fact that there are 86400 seconds in a day, you can format the timestamp as follows:

If ! Valid(LocalNow);
[
  LocalNow = ConvertTimestamp(SomeTimestamp, Invalid, Invalid, 3);
  DisplayNow = concat(Date(LocalNow / 86400, 4), " - ", 
                           Time(LocalNow % 86400, 2));
]