Time and Date Functions in Expressions

You might use time and date functions for many reasons: as part of a display, to act as a trigger, or to query history. The following is offered as a guide, without listing all the available Time And Date functions.)

In code, VTScada uses numeric timestamps that represent the number of seconds since January 1, 1980 (known as the Unix epoch). For any given time, note that there is both a UTC value and the local time zone value. Any operation that reads from or writes to the Historian must use UTC. You and your operators will probably prefer working with local time, expressed in a form such as "Tuesday, February 11, 2025 at 9:58 am. Tools are available for all formats.

If your expression needs to find the current time or date, use one of:

Now(interval)	Returns the number of seconds elapsed so far today, updated every (interval) seconds.
Time(seconds, format)	Formats the number of seconds since midnight into a form that's easier for a human to read and understand. For example, Time(Now(1), 4) The format codes can be found in the reference section of the documentation.
Today()	Returns the number of days since January 1, 1970.
Date(days, format)	Translates the number of days since Jan 1, 1970 into a human-friendly format. For example, Date(Today(), 4)

 

The function, CurrentTime(), will return the total elapsed time in seconds to three decimal points since January 1, 1970. You can control whether the return value uses the local time or the UTC time with an optional parameter, where the default is to return the local time. Again, all Historian operations must use UTC time exclusively.

But note that CurrentTime() works only in script mode and not in steady state. There are two options for obtaining the current time when working in steady state. The first method is to calculate it to the nearest second:

Today() * 86400 + Now(1) 

The second method is to create a Workstation Status Tag and below that add an I/O and Calculations tag in analog mode, with the address Expression:CurrentTime() The scan interval of the I/O tag will set the frequency at which the expression is refreshed, but note that this will be relative to whenever the tag is restarted, not a even interval of seconds.

When creating expressions for reporting purposes, including work with the HDV, it is common to require start time and end time boundaries. For these you should consider using the TimeUtils library, which works in both script and steady-state.

To create a time-based trigger, consider using any of:

AbsTime(enable, interval, offset)	Becomes TRUE when any repetition of intervals since midnight, plus an offset, is reached.
TimeArrived(timestamp)	Returns TRUE when the specified UTC timestamp is reached.
TimeOut(enable, seconds)	Returns TRUE when the enable parameter has been TRUE for an interrupted number of seconds.
RTimeOut(enable, seconds)	Returns TRUE when the enable parameter has been TRUE for a cumulative number of seconds.

 

More About Formatting

Having the number of elapsed seconds since a given reference point is useful to a computer, but not easy for humans to read. The Time() and the Date() functions are available to turn those seconds into a more friendly form. To use them, you will need to refer to a table of available formats to select the one you want.

In general, the Time() function looks like so: Time( Timestamp, Format Flag)

To obtain the current time, you could use any of the following (examples assume that it's 9:35 p.m.)

Time( Now(1), 2) --->   21:35:00

Time( Now(1), 7) --->   09:35 PM

The formatting codes and formatting strings can be found in the reference section of the documentation.

Examples:

Assuming that today is Monday, Aug 13th, 2012, then:

Date(Today(), 3)

... yields, "08-13-12"

Date(Today(), "dddd MMM dd, yyyy") 

... yields, "Monday Aug 13, 2012"

Turn a timestamp into a human-friendly date and time

An example earlier in this topic showed how to calculate a timestamp with Today() and Now(). To convert in the opposite direction to turn a timestamp into a date and a time, you need to know how many times 86400 goes evenly into the number. Simple division, truncating to the nearest integer will give you that.

Int(SomeTimestamp/86400)

You also need to find out how many seconds remain for the portion of time measured into the day. You can do that with the modulus division operator, %, which returns the remainder. For example...

SomeTimestamp % 86400

...returns the number of seconds into the current day, much like the Now() function.

When was this exercise written?