z/VM, does anyone really know what time it is?

Time Standards on Parade

Every day people look at the Sun and know in their hearts that it will be directly overhead at 12:00:00. It's how we can navigate the skies and the oceans. It's the basis for time zones. It's how a sundial functions. This notion of time where the Sun is at its highest point at the same time every day is called solar time. As a practical matter, we don't really care how long it takes for the Sun to reach that point, we just know that there are 24 hours in a day, 60 minutes in an hour, and 60 seconds in each minute. So by definition there are 86 400 seconds in a mean solar day, and they are as long as they need to be. We officially refer to this interpretation of time as UT1, but its how people have been setting their brains, their bodies, and their timekeeping devices for millennia.

While solar time feels natural to us, it's not always a good fit for the problem at hand. Not only does each solar day vary in length, the mean solar day gets a little bit longer with each passing century. This means that the further in the future you project an event, the more significant that difference becomes. When calculating astronomical events that occur over vast distances and long periods of time, it's important to have time intervals that are constant. A new definition of the second was needed, one that never stops and never varies.

To that end, atomic clocks were built in the 1950s that could measure precise changes in the behavior of the cesium atom, and from that the international standard (SI) second was born. International Atomic Time (TAI) was established, measuring the number of SI seconds that have occurred since midnight, January 1, 1958. (All time standards have a defined starting point called the epoch.)

It's important to note that TAI does not tell you what time it is. It's simply a metronome that steadily measures the passage of Time, ticking a rate agreed to by the world's scientists. To help the rest of the people in the world agree on the answer to the simple question, What time is it?, Coordinated Universal Time (UTC) was created. UTC ticks at the same rate as TAI, but is adjusted as needed to be within less than one second of solar time. Where the world formerly set its clocks using solar time, it now sets them using UTC. Local time or civil time is obtained by applying an officially defined offset called a time zone to UTC.

As it turns out, one SI second is slightly shorter than one second of solar time. Consequently, a clock based on UTC runs slightly faster than a clock based on solar time. Eventually that difference accumulates to the point where UTC time will be a full second ahead of solar time, then two seconds, and so on, making it seem as though noon were occurring later and later each day.

To counter that behavior, the leap second was introduced to UTC in 1972. By international agreement, the International Earth Rotation and Reference Systems Service (IERS) in Paris measures the difference between the length of mean solar day and the length of a UTC day and decides whether or not a leap second needs to be added to a single chosen UTC day. If the leap second is added, it effectively delays the start of the the following UTC day by one SI second, keeping UTC within 0.9 seconds of UT1. Technically, a leap second can also shorten a UTC day, but the physics make that highly unlikely to occur. The IERS publishes its decision about the leap second in its biannual Bulletin C. You can subscribe to the bulletin by visiting iers.org.

As of this writing (October 2017), a total of 27 leap seconds have been inserted into UTC since 1972, the most recent being added December 31, 2016.

For many people and machines, the exact time is not as important as the order of events, since order doesn't require an accurate clock, only one that's guaranteed never to go backward or give the same answer twice. But for others, accurate time is needed to meet engineering, scientific, or regulatory requirements, such as account settlements or stock trades, where even fractions of a second may be important.

Despite its name, the IBM z/Architecture Time of Day (TOD) clock does not provide the time of day. Rather, it counts the number of microseconds (and fractions thereof) since midnight, January 1, 1900, the standard epoch. Like UTC, the TOD clock is based on SI seconds, but unlike UTC it does not pause for leap seconds. So when properly set on January 1, 2017, the TOD clock will have a value equivalent to UTC plus 27 seconds.

To accurately convert between any TOD clock value and its civil time equivalent, the operating system or application must know when each leap second was inserted. If only the total number of leap seconds is known, then the OS or application can convert only the current TOD clock value to civil time.

So, when accurate time references are needed for historical purposes, it is recommended that all timestamps be recorded in their civil time equivalents with an indication of time zone, not as raw TOD clock values. Time stamps generated during a designated leap second should be recorded using the ISO recommendation of "hh:59:60". Raw TOD clock values should be compared to each other only when they originate on the same system, and then only to determine relative order.

If "hh:59:60" cannot or may not be used, then the operating system should pause operations for one second to ensure that "hh:00" is not used for two consecutive seconds. While time stamps with binary TOD values are not affected by the leap second when it's recorded, it will show up when the TOD value is later formatted.

In summary, a leap second does not affect the TOD clock. What IS affected is the calculation to convert the TOD clock to civil time.

Server Time Protocol (STP)

The Server Time Protocol (STP) facility of IBM Z enables the installation to configure the CPC with both the number of leap seconds that have been inserted into UTC, and the date of the next leap second insertion. This action is performed using the System (Sysplex) Time task on the HMC.

STP also improves the accuracy of the TOD clock by "steering" it to match an external time source. Specifically, it steers the TOD to UTC plus the number of configured leap seconds. Because the TOD clock does not pause for leap seconds, the configured number of leap seconds are added to UTC before the TOD clock is set so that the TOD clock measures time from the start of the z/Architecture standard epoch, 00:00:00.0000, January 1, 1900.

If STP is unaware of the time and date of the next leap second, introduction of a leap second into the external time reference will be seen by STP as clock drift and and the TOD clock will be steered to a matching value. At that point the TOD clock and civil time differ by one second.

So what?

Without recognition of leap seconds, either the TOD clock or the civil time calculations will be wrong. Is that a bad thing? It depends.

Not all operating systems or applications are (or need to be) aware of leap seconds and it isn't necessary for their TOD clocks to be on the standard epoch. If the host is used in isolation or its time stamps are compared only with those of other leap second-unaware hosts, and the humans reading them don't care, then perhaps this is ok. Simply set the number of leap seconds to zero and the CPC time to UTC.

But it is NOT ok if the system or application records could be used in court procedings, forensic operations, or in financial or other legal transactions.

While ignoring leap seconds might be ok for z/VM itself, you must consider the effects on guest operating systems that are fully aware of leap seconds. Such guests will expect the virtual TOD to be on the standard epoch.

It's important to note that z/VM does not virtualize the STP facility and so it cannot be used by guests. A guest's virtual TOD clock will remain in sync with the z/VM TOD clock as it is steered by the STP facility. If a guest modifies its TOD clock, it will remain at a fixed offset from the z/VM TOD clock, even as the steering occurs.

The Effect of Leap Seconds on z/VM

You can't have your cake and eat it, too.

The components of z/VM that provide civil time and calendar information do not recognize leap seconds. If leap seconds are properly configured into the CPC, z/VM will produce civil time values that are ahead of local time by that same number of seconds. These interfaces include, but are not limited to

  • CP DIAGNOSE 0x0C (Pseudo Timer)
  • CP DIAGNOSE 0x270 (Pseudo Timer Extended)
  • CP terminal timestamps
  • CMS DateTimeSubtract() and DateTimeGet() functions
  • REXX date() and time() functions
  • CMS TIME macro
  • CMS file timestamps

If leap seconds are not configured in the CPC, then the TOD clock will be steered away from the standard epoch, but the civil time values will be correct, with one major exception: When a leap second occurs, it will take approximately seven hours until the above interfaces return the correct time. More on that in a moment.

It is recommended that when the STP feature is installed on CPCs where z/VM will run, that STP be configured with zero leap seconds and no scheduled leap second, and z/VM be configured with Feature Enable STP_Timezone and/or STP_Timestamping in SYSTEM CONFIG. In this configuration:

  • The above interfaces will all report the correct local time.
  • z/VM will synchronize its partition's TOD clock to the CPC TOD clock during IPL so that deactivation/reactivation of the z/VM partition is not necessary.
  • If STP_Timezone is enabled, the local standard and daylight savings time (if any) time zone definitions will be obtained from the CPC, and TIMEZONE_BOUNDARY definitions will be created to match that information. As the CPC enters and exits DST, CP will automatically issue the CP SET TIMEZONE command.
  • If STP_Timestamping is enabled, the current TOD clock will be placed in all I/Os. If any TOD clock synchronization alerts (sync checks) occur, the value placed in the I/O timestamp will be adjusted by the indicated delta.
  • When a leap second occurs, the local time will be one second ahead of UTC. Over the next seven (7) hours, STP will appear to slow down the CPC TOD clock until it is again in agreement with UTC and z/VM again reports the correct local time. Leap seconds do not affect the TOD clock and so have no effect on I/O timestamps.
  • The z/VM TOD clock will not be on the standard epoch. If z/VM TOD clock values are being used or compared with TOD clock values from other systems, they must all be using the same epoch.

If the STP feature is configured with a non-zero leap second count, the above interfaces will report time values that are ahead of UTC by the configured number of leap seconds. Each time a scheduled leap second occurs, those interfaces will immediately begin to report time values that are ahead of UTC by one additional second.

If you want a z/VM time zone that is different than the CPC time zone, enable STP_Timestamping instead of STP_Timezone in SYSTEM CONFIG. Note that STP_Timestamping is required when using Global Mirror for z Systems (XRC).

If the STP facility is not installed or enabled, or its use by z/VM is not desired, do not enable the STP_Timezone or STP_Timestamping options in SYSTEM CONFIG. The system will prompt for the correct local time at IPL. The time zone boundary definitions from SYSTEM CONFIG will be used to determine the local time offset from UTC and the z/VM TOD clock will be set to UTC.

If STP hardware facility is enabled, but neither STP option is enabled in SYSTEM CONFIG, the CPC TOD will be steered to the correct time, but the z/VM TOD clock is synchronized to it only when the z/VM partition is deactivated and then reactivated.

If the STP feature is not present or is not operating, the CPC TOD clock is not synchronized with other CPCs or with an external time source, and TOD clock steering is not performed. During Power-on-Reset (POR), the CPC will obtain the current time from its battery-operated backup clock. If the time is incorrect when z/VM is IPLed, enter the local time. As above, the time zone boundary definitions will be used to determine UTC.

When entering local time at the z/VM IPL prompt, ignore any reference to the TOD enable key. IBM Z systems operate as though the TOD Enable key is always engaged, such that the time will be set as soon as the ENTER key is pressed.

To recap:

STP sets the TOD to UTC plus the number of leap seconds configured on the HMC, properly placing the TOD on the standard epoch (midnight 1/1/1900). If the number of leap seconds is zero or otherwise incorrect, the the TOD will not be on the standard epoch. To be clear,as long as all systems have the same number of configured leap seconds, it doesn't overly matter. Conversions between TOD and local time will work fine, as will sequencing.

But what about z/OS?

MVS doesn't have to wait 7 hours for the LPAR TOD clock to slow down to make the TOD-local time conversions show the correct local time. Instead, as soon as STP detects the large 1 second difference between UTC and local time, MVS is notified. It then finds out what the new leap second counter is and resets the LPAR TOD clock to match the hardware TOD (which doesn't slow down).

Anomalies arise when VM and MVS are on the same CPC and the leap seconds counter is set to 26. The TOD is set according to the standard epoch and MVS will report the correct local time. While VM is notified of the one-second difference, VM doesn't resync the TOD. Because VM doesn't subtract the leap seconds, it shows a local time that's 26 seconds fast.

Published June 28, 2015. Updated November 17, 2017.