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 in which the Sun is at its highest point at the same time (whatever that means) every day is called solar time. As a practical matter, people 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 and it's how people have been setting their brains, their bodies, and their timekeeping devices for millennia.

But as it turns out, 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. That way we will know, without a doubt, the exact time the life-ending asteroid will hit the Earth in the far-flung future!

And if that weren't enough, the length of a solar day varies slightly from day to day, and so then does a length of a solar second.

While that doesn't bother us humans in the slightest, it's not really a good fit for computers or science. Why? Because computers aren't really very good at fuzzy timekeeping and scientists need constants to be, well, constant. So the solar second just won't do. We need a different type of second - one that 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. The starting point of any timing system is called the epoch.

It's important to realize that TAI doesn't tell you what time it is! It's simply a metronome that steadily measures the passage of Time, ticking at a rate agreed to by the world's scientific community. Counting seconds is all well and good, but what we really want to know is the answer to the seemingly simple question, "What time is it?" Aye, there's the rub! So in the 1960s, a new time standard began to emerge. It wasn't quite the Coordinated Universal Time (UTC) that we know today, but it was a beginning.

. To deal with the drift of TAI from civil time since 1958, UTC was eventually defined to be exactly 10 seconds behind TAI. Where the world formerly set its clocks using solar time, it now set them using UTC. Local time (or civil time) is obtained by applying an officially defined offset called a time zone to UTC. As a kid, I used to listen to shortwave radio WWV broadcasts: "tick tick tiiiick tick At the tone, the time will be 14 hours, 23 minutes, Coordinated Universal Time. beeeeeep tick ..."

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. That's how we keep the sun directly overhead at noon on the equator. We can't change astrodynamics, but we can change the clock; just twist the little knob. Technically, a leap second can also shorten a UTC day, but the physics involved make that highly unlikely to occur. It's really there to handle measurement improvements.

The IERS publishes its decision about the leap second in its biannual Bulletin C. You can subscribe to the bulletin by visiting b iers.org . Once you register, update your IERS profile to include Bulletin C.

As of June 2020, a total of 27 leap seconds have been inserted into UTC since 1972, the most recent being 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 z/Architecture 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 July 1, 2020, the TOD clock had 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 the correct 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 or within the same STP timing network, 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 and LinuxONE is not a protocol in the traditional sense of the word. Rather, it is a function within the servers to manage the TOD clock. Specifically, it provides

TOD clock synchronization with UTC,
TOD clock synchronization among multiple IBM Z or LinuxONE machines.

In order to set the TOD clock properly based on UTC, it is necessary to know how many leap seconds are currently in UTC. For that purpose, the HMC allows 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 Manage System Time task on the HMC.

STP 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. STP awareness of leap seconds prevents the TOD clock from drifting away from the epoch and allows it to notify the OS of the change in leap seconds using a timing-parameter-change timing alert.

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. When that steering effort is complete the TOD clock and civil time differ by one second. STP notifies the OS with a sync-check timing alert.

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 QUERY TIME
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 the CPC be part of an STP timing network that is configured with zero leap seconds and no scheduled leap second, and that 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 z/OS Global Mirror (formerly known as Extended Remote Copy, or 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 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 automatic IPL options are not specified in SYSTEM CONFIG, the system will prompt for the correct local time at IPL.

When the 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.

When 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 and LinuxONE 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. (Unless, of course, you're running 2nd level. In that case,you must have OPTION TODENABLE in your directory entry. If you don't, then you will think you have set the time, but you haven't.)

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 civil time will work fine, as will sequencing, though the civil times will be ambiguous with respect to UTC for some hours after a leap second occurs.

But what about z/OS?

Buckle up, Cupcake!

There are two different ways z/OS will deal with a leap second.

Let's first take the case where STP is configured with NO leap seconds. Remember that this will cause the TOD clock to be steered over 7 hours. Well, z/OS doesn't wait. Instead, as soon as STP detects the one-second difference between UTC and the current time, and notifies z/OS via sync-check interrupt, z/OS will pause the system for one second and reset its LPAR TOD immediately to the new value. No ambiguity in its civil time stamps.

When STP is configured WITH leap seconds, z/OS receives the timing-parameter-change interrupt and updates the CVT with the new leap second value. That's all. That value is used by the MVS TIME macro and other callable services to return the correct civil time.

Anomalies arise when z/VM and z/OS are on the same CPC and the leap seconds counter is set to 27. The TOD is set according to the standard epoch and z/OS will report the correct local time. While z/VM is notified of the timing parameter change, z/VM doesn't react to it. Because z/VM doesn't subtract the leap seconds, it generates UTC and local civil time values that are 27 seconds fast.

Published June 28, 2015.
Updated September 28, 2020.

The information provided, and views expressed on this site are my own and do not represent the IBM Corporation.