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 CI
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 which does not
correspond to an actual geographic time zone. For instance, a
system time zone offset of 8 hours and 2 minutes is not acceptable.
Therefore, when you boot the system, a rounding function is used to
make the system time zone 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. Until the next time the system is
booted, the hardware clock will not be used as a time reference; any
system timestamp will be 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 system manager or operator 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 resumes 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 gradually losing one hour.
:SETCLOCK DATE=1/27/1994;TIME=14:00
Correction Form.
The system manager or operator 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 resumes its
normal pace.
Example.
The following command has an 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 be adjusted.
Time-Zone Form.
The system manager or operator provides a time zone. The result is to
change local time to match that of the new time zone, 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 you 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 you 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 has 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 does 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 appears 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 appears to run at half its normal pace. Thus, a
one-hour negative time correction takes 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 appears to run at
approximately twice its normal pace. Thus a one-hour positive time
correction takes 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, which are described in the
examples below.
* 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 is
the easiest 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 the SETCLOCK command:|
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 that 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, a gradual time change does not accurately reset an
incorrect hardware clock. You would notice this at the next boot, when
the operator is presented with an incorrect date and time.
Therefore, you must 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 form of the SETCLOCK command:|
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
You 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 moves from 0 to 8 hours in the Western Hemisphere,
local time does not jump backwards. Rather, the system clock is slower,
causing a gradual change. In this case, it is necessary to issue the
following command to stop this correction:
:SETCLOCK; CANCEL
As in the previous example, you must now use the date-time form of the
SETCLOCK command and use the NOW option to set the hardware clock
accurately, even though local time seems to be set correctly.
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.