Adding Support for Altering the Time-of-Day Clock to z/VM

Disclaimer

This is not an official IBM site.  The author is not an employee, officer, or director of IBM, and never has been.  The author is not a contractor for IBM, and never has been.  All opinions expressed are those of the author and do not necessarily represent the opinions or the official positions of the staff or management of IBM, or of any other organization or individual.  This information is presented in the hope that it will be useful, but without any warranty or guarantee of any kind.  This information is presented free of charge, free of support, free of service, and free of liability.  Take this information with as many grains of salt as you think it's worth; and use it, if you choose to do so, entirely at your own risk.  The author hereby explicitly places this material in the public domain.  All trademarks, registered trademarks, service marks, etc. are the property of their respective owners.

Maintenance Log

Purpose

The purpose of this document is to provide information and some computer code which will allow you to alter the Time-of-Day (TOD) Clock on a live running z/VM system, which, under certain very limited conditions, may be useful. 

Warning: altering the TOD clock on a live running system is inherently dangerous!  Don't even think about doing this unless you really know what you're doing!  Doing this improperly or under the wrong conditions can cause all sorts of harm, including data loss, data corruption, and ABENDs of CP!  You have been warned!  I'm giving you enough rope to hang yourself with.  Make sure you don't use it for that purpose!  Please read this entire web page, as well as all the comments in the source code, before you even think about trying this!  If you do proceed, you do so at your own risk!  In no case shall the author be liable for any type of damages whatsover!

Why Would I Want to Do This?

There are basically two officially supported ways to change the Time-of-Day (TOD) clock on a z/VM system.  (I'm not talking about changing the time zone, which is what one would normally do when switching from standard time to daylight saving time, or vice versa.  That is completely different.  I'm talking about changing the TOD clock itself, which is normally set to Greenwich Mean Time (GMT).) 

The best way is to change the clock on the Support Element (SE) and then perform a power-on reset.  The TOD clock will be initialized from the SE clock during the power-on reset.  Of course, this requires that your z/VM system be down while you're doing it.  In fact, all systems on all LPARs on the box must be shut down prior to doing this.  This represents a level of outage that some customers would rather avoid, if possible.

The second way is to shutdown the z/VM system (by means of the SHUTDOWN command without the REIPL option), then do a true hardware-level IPL (i.e. a "LOAD" function) from the Hardware Management Console (HMC) or the Support Element (SE).  On the Stand-Alone Program Loader (SAPL) screen, add the "PROMPT" option to the IPL parameters field, then press the PF10 key to load the CP nucleus.  During CP initialization, you will be prompted whether or not you want to change the TOD clock.  Reply "yes", then follow the subsequent prompts appropriately.  This will change the TOD clock for the LPAR only: other LPARs will not be affected. 

(Since there is only one TOD clock for the whole box, PR/SM virtualizes this by keeping a TOD clock offset for each LPAR, just as CP does for each virtual machine.  At activation of each LPAR, the TOD clock offset for the LPAR is initialized to zero.  When the TOD clock is set by a first-level operating system running in an LPAR, PR/SM alters the TOD clock offset for the LPAR accordingly.)

Both methods have one thing in common: you need access to the HMC or SE in order to do this.  What if you don't have such access?  Perhaps you do under normal circumstances, but maybe sometimes you don't.  (For example, you're at a DR hot site, or the system programmer is logged on from home trying to do this.)  The unsupported method documented in this web page allows you to alter the TOD clock without needing access to the HMC or the SE.  This may come in handy for some customers under certain very limited circumstances.

OK, How Do I Do This?

The code you need is provided here.  Download this package in binary to a z/VM system with fixed-length, 80-byte records, then use VMARC to unpack the file.  (If you don't have a copy of VMARC, it can be obtained from the VM Download Page.)  The package contains two components: a utility to set the clock (HCPTOD ASSEMBLE) and a local modification to HCPSCK (HCPSCK UPL0008 and HCPSCK AUXLCL) to prevent an ABEND of CP if the clock is set backward.  The first thing you do is to apply the local modification to CP via the local modification procedures described in the Service Guide.  Then shutdown and re-ipl to put this change into production.  Don't even think about using this utility to set the clock backward unless this local modification is in production.  If this local modification is not on, CP will ABEND for sure if you set the clock backward.

The utility itself is installed via the CP Exit Facility.  Both the CP local modification and the TODCLOCK utility itself require IBM's High Level Assembler (or an equivalent program) to assemble.  Read the comments in the source code (HCPTOD ASSEMBLE) for information on how to install it and for information on the syntax of the TODCLOCK command.

Caveats

This utility should only be used just prior to a SHUTDOWN REIPL, and as much of the system should be taken down as possible first.  Ideally, only OPERATOR should be logged on.  In addition, on configurations with more than one processor, all processors except the master processor must be varied offline.  Once the TOD clock has been set, the additional processors may be varied online again.

Just prior to the SHUTDOWN REIPL, the TODCLOCK command should be issued to adjust the clock.  If the clock is set backward, then an appropriate amount of time should be allowed to elapse after the TODCLOCK command and before the SHUTDOWN command to allow the TOD clock to reach its former value prior to the SHUTDOWN.  For example, if the TOD clock is set backward 30 seconds, then wait 30 seconds (no cheating!) after the TODCLOCK command is issued before issuing SHUTDOWN REIPL.  I prefer to issue

     CP SEND OPERATOR SHUTDOWN REIPL

when doing this from my own id; so that the OPERATOR id actually issues the SHUTDOWN command.  (In fact, on my system, this is required, since my own id does not have the proper privilege class to issue the SHUTDOWN command!)  You can do the same thing for the TODCLOCK command if you want to.  (You generally need class C to do this.)

You should never issue the TODCLOCK command under any other conditions than just prior to a SHUTDOWN REIPL, and only with as much of the system taken down as possible first.  Don't do it!  You have been warned!  Read the comments in the source code for HCPTOD ASSEMBLE for a list of some of the things that can (and probably will) go wrong if you do this.  If you shoot yourself in the foot, I am not responsible for your pain!  It's your gun, your bullet, and your foot!  I told you not to do it, you idiot!  I suggest that you test this utility on a second-level test system before using it on a first-level production system.

Note: when using this utility on a second-level test system, the first-level CP directory entry for the virtual machine must contain

     OPTION TODENABLE

in order for TODCLOCK to work.  If the directory does not contain this option, TODCLOCK invoked with operands will give return code 1, which means that the TOD clock is secured, and the TOD clock will not be altered.  The same directory option must also be present in order for the PROMPT parameter in the IPL parameters field on the SAPL screen to allow the TOD clock to be changed.

You should avoid very large changes in the value of the Time-of-Day clock in a single step.  CP calculates some performance statistics, such as the page rate, which is used in monitor data.  The page rate is the number of page faults per second.  Obviously, this is calculated by dividing the number of page faults by the number of elapsed seconds.  The number of elapsed seconds is calculated by taking the TOD clock difference between the start and the end of the time period, shifting down 12 bits (to get the microsecond bit in the low-order bit position), then dividing by one million (to convert microseconds to seconds).  It is this division by one million which is problematic.  Although the dividend (the number of microseconds) is a 64-bit signed binary integer, the quotient (the number of elapsed seconds) must be expressable as a 32-bit signed binary integer, which means that the number of elapsed seconds cannot be greater than 2,147,483,647, which works out to about 68 years. 

Thus, if the TOD clock starts out as 1900-01-01, for example, and you want to set it to 2011-01-01, that's a jump forward of more than 68 years, and CP will ABEND with a PRG009.  If you need to set the TOD clock that far forward, do it in more than one step to avoid going more than 68 years forward at once.  That will avoid a CP ABEND.  Note that this effect can also be caused by a wrap.  For example, if the current date is 1900-01-02 and you issue "TODCLOCK -172800" (back up 2 days), that is equivalent to going forward by about 142 years.  This type of thing is not checked for.  Be careful.

In order to avoid timing-facility-damage machine check interruptions from occurring when an External Time Reference (ETR) is used, bits 32-63 of the TOD clock will be forced to zero prior to issuing SET CLOCK.  This will result in the date/time value being up to 1.048572 seconds off from the requested value.  If an ETR is actually being used, there may be up to 1.048572 seconds of additional delay before the clock transitions from the stopped state to the set state.  Thus, when an ETR is being used, the clock may be more than two seconds off from the value you intended.  You may have to issue TODCLOCK several times with small adjustments each time before you get it the way you want it.

The Server Time Protocol (STP) facility does not provide a signal that will cause the clock to transition from the stopped state to the set state.  If SET CLOCK (SCK) is executed when the configuration is in STP-timing mode and bit 34 of control register 0 is one, the clock remains in the stopped state until the bit is set to zero on that CPU or until another CPU executes a SET CLOCK instruction affecting the clock.  If only one CPU is online, this will cause CP to go into an infinite loop.  One would hope that CP is smart enough to set bit 34 of control register 0 to zero when running in STP-timing mode, but I have no means to verify this.

UTC vs. TAI

I said earlier that IBM recommends that the TOD clock be set to Greenwich Mean Time, but that is not strictly true.  Greenwich Mean Time is, strictly speaking, an obsolete term.  There are two types of time that need to be discussed: International Atomic Time (TAI) and Universal Coordinated Time (UTC).  Historically, one of the principal uses for standard time was navigation.  Before the days of Global Positioning Satellites, a ship at sea determined its longitude by, for example, noting when a bright star first appeared on the horizon when it rose at night.  The ship carried a very accurate clock that kept the standard time of its home port.  By comparing the time the star first rose (according to the home port clock) with the known time that the star rises at the home port, the longitude can be determined.  For example, if the star rises at the home port at midnight, but rises for the ship's observer at 1 AM (according to the home port clock), then that is 1/24*360 = 15 degrees of longitude difference between the ship's longitude and the home port's longitude.  Since the star rose later than in the home port, the ship is west of its home port.  If the home port's longitude is, say, 30 degrees West Longitude, then the ship's current longitude must be 45 degrees West Longitude.

This is an oversimplification of the calculations involved, since latitude and day of the year also come into play, but it gets the idea across: an accurate determination of position depends on very accurate clocks and very accurate tables of when easy-to-identify astronomical objects rise and set in the home port.  (For more information, see Celestial Navigation.)  Global Positioning Systems which obtain location information from satellites have made this form of navigation less important than it once was.  However, the old method is still used as a backup means of navigation, especially in the military.  For example, an active GPS system sends a radio signal to a satellite, which responds with the sender's position.  This broadcast signal may be detected by an enemy.  Therefore, during periods of strict radio silence, active GPS systems cannot be used.  Communication with the satellites may also be prevented by jamming the satellite signals or destruction of the satellites.  Celestial navigation

That is why, in the United States of America, the U. S. Naval Observatory has been charged with keeping standard time.  (And that is also why the Navy has an Observatory.  Accurate observation of the stars is critical to navigation.)  The trouble is, the earth's rotation rate is slowing down, ever so slightly, due to tidal friction, etc.  Universal Coordinated Time (UTC), since it is used for celestial navigation, tries to keep the time synchronized with the rotation of the earth, so that the astronomical tables of when stars rise and set remain accurate.  To make this happen, the powers that be add a "leap second" to one of the days of the year every so often.  A standard day is 86,400 seconds long, but some days are made 86,401 seconds long every so often to keep UTC synchronized with the rotation of the earth.  A negative leap second (i.e. a day of only 86,399 seconds) is theoretically possible, but so far none have been needed.

International Atomic Time (TAI), however, is not concerned with navigation.  It is interested in measuring time intervals as accurately as possible.  International Atomic Time treats every day as being exactly 86,400 seconds long.  In 1972, when UTC and its rules took over from the older Greenwich Mean Time (GMT), UTC was 10 seconds behind TAI.  That is, if TAI said it was midnight, UTC said it was 10 seconds before midnight.  As of 2009, UTC is now 34 seconds behind TAI due to various "leap seconds" being added to the time scale.  (The table of leap second adjustments can be found here.)  Unlike leap days (February 29), leap seconds do not follow a predictable rule, as you can see from the table.  Leap seconds are added as needed, based on actual astronomical observations of the earth's rotation.  Things like earthquakes, volcanic eruptions, the movement of magma beneath the earth's crust, etc., all affect the earth's rotation rate due to the principle of conservation of angular momentum.  Leap seconds are usually announced a few months in advance, but conversion of UTC time to TAI time, and vice versa, can only be made in the past, and for up to about six months into the future.  Beyond a few months into the future, it's anybody's guess.

As of z/VM 5.4.0, CP basically assumes that UTC is synonymous with TAI.  It isn't.  The TOD clock itself simply counts seconds.  It is up to the programming support to convert this to TAI or UTC.  CP's algorithm is essentially a TAI algorithm: it assumes that every day is exactly 86,400 seconds long.  TODCLOCK mimics the same algorithm in converting a raw TOD clock value into a date and time value, and vice versa.  Over time, with a perfectly accurate clock, the time of day reported by CP will continue to drift further and further ahead of UTC due to not taking leap seconds into account.  So even if the TOD clock is perfect, if you want your TOD clock to reflect UTC time instead of TAI time, you will need to make occasional small adjustments to the time.  And if your TOD clock is not perfect, the amount or frequency of the adjustments will be greater.

Conclusion

That's all folks!  Have fun!  If anyone has any suggestions, comments, advice, tips, or any other form of feedback, please drop me a line at zlinuxman (at) fastmail (dot) com.

Return to my homepage