HP 3000 Manuals HP 3000 Manuals
Using the SETCLOCK Command
by Doug Perry
Commercial Systems Division
Overview
The overview article "Introducing SETCLOCK and SHOWCLOCK, Two New MPE/iX
Commands," in this Communicator mentions that the ability to change the
system time without rebooting has often been requested. That article
presents several reasons why system time up to now has been considered a
valuable system resource that needs protection. A new CI command,
SETCLOCK, has been provided to change the system time gradually,
eliminating many of the dangers inherent in immediately changing the
system time online.
This article contains an explanation of how system time is maintained on
the HP 3000 and a description of each of the three forms of the SETCLOCK
command and how this command affects system time.
How System Time is Kept on the HP 3000
The native form of system time on the HP 3000 is local time. That is,
the time of the system's geographic location is entered by the operator
at boot time. Once the operator inputs the system time, this local time
is maintained by keeping track of the cycles of the CPU itself.
Universal Time (Greenwich Mean Time) is a derived quantity on the HP
3000. Some language library functions provide access to Universal Time.
To provide this time, a system function is called which obtains local
time and applies a system time zone offset, yielding Universal Time.
How the Time Zone Offset is Obtained.
The time zone offset is first obtained at boot time. There is a
separate, battery backed-up, hardware clock in each system, and this
clock is assumed to be set to Universal Time. In addition, the system's
previous time zone offset is stored in stable storage.
When the system is booted, a local time is displayed on the operator's
console and the operator is given the chance to change this time. This
displayed local time is calculated by reading the hardware clock and
adding the stored time zone offset:
displayed local time =
hardware clock (Universal Time) + time zone offset
The operator's entered time is set into the system as the current local
time, and a new time zone offset is calculated by taking the difference
between the hardware clock's time and the operator's entered time.
new offset = operator-entered time - hardware clock time
NOTE It is unacceptable to have a system time zone offset of 8 hours and
2 minutes. So, in this example a rounding function is applied to
make this new offset a multiple of 15 minutes.
The new offset is stored back into stable storage and is also placed in a
system data structure. This is the offset that is used henceforth to
convert local time to Universal Time. That is, until the next boot there
is never again a reference to the separate hardware clock. Any system
timestamp is local time, obtained by referencing the number of
accumulated cycles of the CPU. Any Universal Time timestamp will be
derived by starting with a local timestamp and applying the time zone
offset.
The only uses for the hardware clock, then, are to display a time on the
console and to calculate a time zone offset during the boot process.
It is possible for the hardware clock to be set incorrectly; it might not
be set to Universal Time. The result would be a meaningless time zone
offset. On systems whose users do not need Universal Time, this
condition would never be detected. However, on systems whose users
require Universal Time, local time would be correct while Universal Time
would be erroneous. See the section "Dealing with an Incorrectly Set
Hardware Clock" later in this article for solutions to this problem.
The Three Forms of the SETCLOCK Command
The SETCLOCK command has the following syntax:
{DATE= date spec; TIME= time spec [;GRADUAL]}
{ [;NOW ]}
SETCLOCK { }
{CORRECTION= correction spec }
{TIMEZONE= time zone spec }
{;CANCEL }
This syntax supports the following three forms of the command.
Date-Time Form.
The user provides both a date and time specification. Both date and time
are required. The command compares the entered date and time with the
current system date and time, and a time correction is calculated. This
correction is used to adjust the system time.
The default is to change the system clock speed so that the change in
time is gradual; the system clock speeds up (in the case of a positive
correction) or slows down (in the case of a negative correction) until
the correction is consumed. At that time the system clock will resume
its normal pace.
\ \ \ Important Details \ Please Read A user with System Manager (SM)
capability can provide the ;NOW
option to force an immediate
change. See the previous article
"Introducing SETCLOCK and
SHOWCLOCK, Two New CI Commands,"
in this Communicator, the online
HELP text, or the SETCLOCK command
description in the MPE/iX Commands
Reference Manual (Volumes I and
II) (32650-60115) for warnings
concerning the dangers of
immediately changing the system
time.
Example.
Assuming that the current system time is 15:00 on January 27, 1994, the
following command causes the system time to slow down, resulting in the
system clock losing one hour in the course of the next several hours:
:SETCLOCK DATE=1/27/1994;TIME=14:00
Correction Form.
The user provides a time correction (in seconds). As in the date-time
form, the system clock speeds up or slows down until the correction is
consumed. At that time the system clock will resume its normal pace.
Example.
The following command has a effect similar to the first example, causing
the system time to slow down, resulting in the system clock losing one
hour:
:SETCLOCK CORRECTION = -3600
NOTE Since Universal Time is derived from local time on the HP 3000,
using the date-time form or the correction form to change local
time also results in a change to Universal Time.
These forms are useful to make small adjustments to system time
because of clock drift. In that case, the desired behavior is that
both local and Universal Time should be adjusted.
Time-Zone Form.
The user provides a time zone. The result is to change local time to
match that of the new time zone, while leaving Universal Time unchanged.
The major use of this form is to change between Standard Time and
Daylight Savings Time.
The behavior of local and Universal Time on the system is quite complex
when this form of the command is used. The reason for the complexity is
to assure that there are no out-of-sequence time stamps in either local
or Universal Time when the change occurs.
The behavior can best be illustrated with two examples, one involving a
change from Standard to Daylight Savings Time and the other involving a
change back from Daylight Savings Time to Standard Time:
Example: Change to Daylight Savings Time.
Assume that the system is located in the Pacific Standard Time Zone,
which is 8 hours offset from Universal Time in the Western Hemisphere.
(In this case local time trails Universal Time by 8 hours.)
The goal is to move the system to Pacific Daylight Savings Time, which is
7 hours offset from Universal Time in the Western Hemisphere.
The following command is issued:
:SETCLOCK TIMEZONE = W7:00
In this case the user would see local time immediately jump forward by
one hour. A user of Universal Time would see no change.
Example: Change from Daylight Savings Time to Standard Time.
Assume that the system is now located in the Pacific Daylight Savings
Time Zone, which is 7 hours offset from Universal Time in the Western
Hemisphere. (Local time trails Universal Time by 7 hours.)
The goal is to move the system back to Pacific Standard Time, which is 8
hours offset from Universal Time in the Western Hemisphere. The
following command is issued:
:SETCLOCK TIMEZONE = W8:00
In this case the user may expect to see no change in Universal Time and
either an immediate jump backward or a slowdown in local time. However,
immediate backward jumps may have dangerous consequences, and are not
permitted.
A gradual slowdown in local time while leaving Universal Time unchanged
would mean a constant recalculation of the time zone offset, since
Universal Time is derived from local time. Such recalculation cannot be
done efficiently; therefore, a more complex strategy must be used.
The strategy of this command is to reset the time zone offset immediately
to eight hours. This causes Universal Time to jump forward immediately
by one hour.
However, now both local and Universal Time are one hour ahead of where
they should be; therefore, the command then establishes a time correction
of -3600 seconds, which causes both local time (and Universal Time since
it is derived from local time) to gradually lose an hour. At the end of
this gradual correction, local time has lost one hour, and Universal Time
is back to where it would have been if no SETCLOCK command had ever been
issued. Thus, the goal of never having out-of-sequence timestamps for
either local or Universal Time has been achieved.
The Cancel Parameter
The ;CANCEL parameter nullifies any remaining (unconsumed) correction.
For instance, assume the following command is issued:
:SETCLOCK CORRECTION = 120
This command causes the system clock to go faster than normal, and at
some indeterminate time in the future, the correction is consumed and the
clock speed returns to normal.
However, any time before the correction is totally consumed, the
remaining correction can be nullified by the following command:
:SETCLOCK; CANCEL
This command does not undo the correction that has already been consumed;
it merely nullifies the remaining correction. Thus, after both of the
commands in this example have been issued, the system clock is still
somewhat ahead of where it would have been if these commands had not been
issued.
In the case of the time-zone form of the command, the CANCEL parameter
has the following effects:
If a change in time zone causes local time to jump forward (as in going
from Standard to Daylight Savings Time), the CANCEL parameter will have
no effect. The reason is that with such an immediate forward jump, there
is no remaining correction to nullify.
If a change in time zone causes local time to slide backward (as in going
from Daylight Savings to Standard Time), Universal Time first jumps
forward immediately, and then a negative time correction is established
to cause both Universal Time and local time to slow down. In this case,
CANCEL nullifies any remaining negative time correction, but it will not
undo the change in time zone offset, which occurred immediately upon
issuance of the command.
How Long a Gradual Correction Takes
The system timestamp procedures have been changed to check for an ongoing
time correction and to modify the rate of the clock based on that
correction.
If a negative time correction is in effect, on a completely idle system
the clock will appear to creep forward at an extremely slow pace. This
pace is so slow that the clock may appear to be almost stopped. On a
busy system the clock will appear to run at half its normal pace. Thus,
a one-hour negative time correction will take between one and two hours
of wall time to complete, depending on how busy the system is.
If a positive time correction is in effect, the clock will appear to run
at approximately twice its normal pace. Thus a one-hour positive time
correction will take approximately one hour of wall time to complete.
Dealing with an Incorrectly Set Hardware Clock
Using the SHOWCLOCK command for the first time on a new system may reveal
that the hardware clock is not set to Universal Time. The indication may
look like this example:
:SHOWCLOCK
SYSTEM TIME: FRI, JUL 24, 1987, 8:00:00 AM
CURRENT TIME CORRECTION: 0 SECONDS
TIME ZONE: 35 HOURS 0 MINUTES WESTERN HEMISPHERE
Since time zones usually range from 0 to 12 hours, we know something is
wrong.
At this point you may do one of three things:
* You may choose to use the CLKUTIL program available at the ISL
prompt before starting the system. At the ISL prompt, instead of
immediately issuing a START command, type CLKUTIL. You will be
given the choice of reading or setting the hardware clock. If you
read the hardware clock, you will probably see that its time does
not match what you know to be correct Universal Time. Reset the
time; Universal Time should be ahead of local time in the Western
Hemisphere and should trail local time in the Eastern Hemisphere.
For instance, if the system is in the Pacific Standard time zone
and it is 9 a.m. in the morning locally, Universal Time should be
17:00 (eight hours ahead of local).
Note that during certain times of the day, Universal Time may be
the next day if you are in the Western Hemisphere or the previous
day if you are in the Eastern Hemisphere.
After leaving CLKUTIL you will again get the ISL prompt and can
issue the normal START command.
* You may not want to reboot the system but instead issue the
time-zone form of the SETCLOCK command, resetting the time zone.
Several complications may arise and these are described in the
following examples.
* You may decide to ignore the problem. This is an acceptable
strategy if nobody on the system uses Universal Time. If this is
the case, you may choose to go from Standard to Daylight Savings
Time by using the date-time or correction form of the SETCLOCK
command, even though they change Universal Time as well as local
time. If nobody on the system uses Universal Time, the result is
acceptable.
Recommendation It is recommended that an incorrect hardware clock be
reset to Universal Time by rebooting the system and using
CLKUTIL. This method is the most straightforward and easy
to understand. However, the following examples are
provided for those who would use the time-zone form of
the SETCLOCK command.
Example: Correcting an erroneous hardware clock by using the time-zone
form of t.
As in the SHOWCLOCK example at the start of this section, you discover
that the system is in the 35-hour time zone in the Western Hemisphere.
You issue the following command:
:SETCLOCK TIMEZONE = W8:00
This change in time zones is in a direction that causes forward motion of
local time.
One minute later you issue the SHOWCLOCK command, with this result:
SYSTEM TIME: SAT, JUL 25, 1987, 11:01:00 AM
CURRENT TIME CORRECTION: 0 SECONDS
TIME ZONE: 8 HOURS 0 MINUTES WESTERN HEMISPHERE
Local time seems to have jumped forward by 27 hours, landing you in the
middle of the next day! The reason for this is the goal of the time-zone
form is to effect a change in time zones by changing local time and time
zone offset, leaving Universal Time unchanged. In this example, the
system jumped from the 35-hour time zone to the 8-hour time zone, a
change forward of 27 hours. At least the time zone offset is now correct
at 8 hours. The question is what to do about the local time.
You could issue either the date-time or correction form of the SETCLOCK
command. However, the 27-hour gradual change may take more than a week
to complete.
You could issue the date-time form of the SETCLOCK command and include
the NOW option, if you have SM capability. In this case, the local time
immediately jumps backward (with all the attendant hazards), the 8-hour
time zone interval is applied to the new local time, and thus Universal
Time is changed. Everything is now correct.
Second Example: Correcting an erroneous hardware clock by using the
time-zone fo.
Assume that an initial SHOWCLOCK command shows the following information:
SYSTEM TIME: FRI, JUL 24, 1987, 8:00:00 AM
CURRENT TIME CORRECTION: 0 SECONDS
TIME ZONE: 0 HOURS 0 MINUTES WESTERN HEMISPHERE
One might run into this example if the hardware clock had erroneously
been set to local time instead of Universal Time.
You issue the following command:
:SETCLOCK TIMEZONE = W8:00
This change in time zones is in a direction that causes a slowdown of
local time.
One minute later you issue the SHOWCLOCK command, with this result:
SYSTEM TIME: FRI, JUL 24, 1987, 8:00:48 AM
CURRENT TIME CORRECTION: -28788 SECONDS
TIME ZONE: 8 HOURS 0 MINUTES WESTERN HEMISPHERE
Since the time zone has moved from 0 to 8 hours in the Western
Hemisphere, local time did not jump backwards. Rather, the system clock
is slower, causing a gradual change. In this case, it is only necessary
to issue the command
:SETCLOCK; CANCEL
to stop this correction. Everything is now correct, except that the
system has lost a few seconds before you could issue the second command.
In both of these examples Universal Time has been reset without having to
reboot the system.
Conclusion
Knowledge of how time is kept on the HP 3000 is extremely valuable in
using the SETCLOCK command effectively. The way SETCLOCK gradually
changes system time is designed to avoid many of the hazards that up to
now have accompanied a system time change and that have caused system
time to be considered a valuable protected system resource.