Setting the time in the correlator (&SETTIME event)
A &SETTIME event can have one of the following formats:
It can contain a number of seconds:
&SETTIME(float seconds)
The seconds parameter represents the number of seconds since the epoch, 1st January 1970. For example:
&SETTIME(0) sets the time to "Thu Jan 1 00:00:00.0 BST 1970".
&SETTIME(1185874846.3) sets the time to "Tue Jul 31 09:40:46.3 BST 2007".
Or it can contain a time string:
&SETTIME(string time)
The time is a string in extended ISO8601 form, with fractional seconds. For example:
&SETTIME("2015-04-20T23:32:41.032+01:00")
&SETTIME("2015-04-20T22:32:41.032+00:00")
&SETTIME("2015-04-20T22:32:41.032Z")
&SETTIME("2015-04-20T22:32:41.032")
These all refer to the same time. Note that the first example shows the time in a different timezone with an offset of 1 hour.
Normally, you do not need to send &SETTIME events. You would just send &TIME events. An &SETTIME event is useful only to avoid the problem pattern described above. The only difference between an &SETTIME event and an &TIME event is that the &SETTIME event causes an intermediate, repeating timer to fire only once while the &TIME event causes intermediate, repeating timers to fire repeatedly. For example, on all wait(0.1) fires ten times for every second in the difference between consecutive &TIME events. However, it fires only once when the correlator receives an &SETTIME event.
If you decide to send an &SETTIME event before an &TIME event, you typically want to send the &SETTIME event only before the first &TIME event. You should not send an &SETTIME event before subsequent &TIME events. Doing so causes a jumpy quality in the behavior of time. There is a warning message in the correlator log if you set a time that moves time backwards.
For information about when you might want to use external time events, see
Determining whether to disconnect slow receivers.
