$NOW

Time Functions Compared

The various ways to return the current date and time are compared, as follows:

• $NOW returns the local date and time for the current process. $NOW returns the date and time in Caché storage format. It includes fractional seconds; the number of fractional digits is the maximum precision supported by the current operating system.

  • $NOW() determines the local time zone from the value of the $ZTIMEZONE special variable. The local time is not adjusted for local time variants, such as Daylight Saving Time. It therefore may not correspond to local clock time.

  • $NOW(tzmins) returns the time and date that correspond to the specified tzmins time zone parameter. The value of $ZTIMEZONE is ignored.

• $HOROLOG contains the local, variant-adjusted date and time in Caché storage format. The local time zone is determined from the current value of the $ZTIMEZONE special variable, and then adjusted for local time variants, such as Daylight Saving Time. It returns whole seconds only; fractions of a second are truncated.

• $ZTIMESTAMP contains the UTC (Coordinated Universal Time) date and time, with fractional seconds, in Caché storage format. Fractional seconds are expressed in three digits of precision (on Windows systems), or six digits of precision (on UNIX® systems). For this reason, $NOW(0) may return UTC time with greater fractional second precision than $ZTIMESTAMP.

None of these ways to return the current date and time are an exact replacement for the obsolete $ZUTIL(188) function, which provided local date and time with both adjustment for local time variants and fractional seconds.

Microseconds on Windows

The precision of microseconds on Windows systems is generally less accurate than other platforms. This is due to the limitations of the QueryPerformanceCounter() Windows library routine. Caché determines microseconds by comparing the result computed by QueryPerformanceCounter() with the system clock used for other date/time functions, which has at best 1 millisecond precision (and usually between 1 and 20 milliseconds of accuracy depending on the hardware running Windows.) When the $NOW microsecond precision clock differs from the millisecond precision clock by more than 50 milliseconds, Caché adjusts the microsecond precision clock forward or backwards to agree with the more accurate (but less precise) millisecond precision clock.

Because of this, on Windows, the $NOW function (and legacy $ZUTIL(188) function) is suitable for measuring microsecond precision time intervals only over a very short duration, lasting no longer than a small number of seconds. On systems with multiple CPU cores, the Caché Windows process for each core will make microsecond adjustments that are local to the individual process. This means that $NOW values returned on different Caché CPU processes can disagree with each other. This discrepancy among CPU processes is more pronounced when Windows is running on a virtual machine that is hosted on a multi-core CPU chip.

Separating Date and Time

To get just the date portion or just the time portion of $NOW, you can use the $PIECE function, specifying the comma as the delimiter character:

   SET dateval=$PIECE($NOW(),",",1)
   SET timeval=$PIECE($NOW(),",",2)
   WRITE !,"Date and time: ",$NOW()
   WRITE !,"Date only: ",dateval
   WRITE !,"Time only: ",timeval

Setting the Date

The value returned by $NOW and $ZTIMESTAMP cannot be set using the FixedDate() method of the %SYSTEM.ProcessOpens in a new tab class.

The value contained in $HOROLOG can be set to a user-specified date for the current process using the FixedDate()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.