SETCLOCK



SETCLOCK

     Alters the system time or system time zone.

SYNTAX



SETCLOCK {DATE= date; TIME= time [;GRADUAL | ;NOW]}

{CORRECTION= correction [;GRADUAL | ;NOW]}

{TIMEZONE= timezone}
{;CANCEL}


PARAMETERS


date A specification of local date in the form mm/dd/yy[yy].
The year may be expressed in two or four digits. If a
date is provided, a time must also be provided.

time A specification of local time in the form hh:mm[:ss]
where seconds are optional. This specification uses a
24-hour clock; it is not permissible to specify time
using A.M. or P.M. If a time is provided, a date must
also be provided.

The operating system will experience problems if the
system date and time are too close to the base time of
midnight, January 1, 1970. Therefore, for proper system
operation this command requires the date and time to be
later than ten minutes past midnight on January 1, 1970.

correction An integer specifying the desired change in the system
time. The units are seconds. Thus a positive
correction will cause the system clock to advance by
the specified number of seconds, while a negative
correction will cause the system clock to slow by the
specified number of seconds.

timezone A specification of the time zone in the form hh:mm,
preceded by a required "W" or "E" to specify the Western
or Eastern Hemisphere. Thus a specification of W7:00
represents a seven-hour displacement from Universal Time
(GMT) with the time zone being in the Western
Hemisphere.

Providing a time zone spec is the only way to change the
system time and maintain both local and Universal Time
(GMT) accurately. See the Operation Notes section for details.

GRADUAL This option is meaningful only when the date and time
specifications are provided. GRADUAL causes the system
clock to speed up or slow down until the time change is
complete, at which time the system clock will resume its
normal pace. GRADUAL is the default for the Date-Time
form of the command.

NOW This option is meaningful only when the date and time
specifications are provided. NOW forces an immediate
change. See the warning in the Operation Notes section
about the dangers of changing the system time immediately.

CANCEL Cancels a current time correction. Any correction which
has already taken place before the cancellation will
remain; this option does not undo a correction which has
already been accomplished. See the Operation Notes and
Examples sections for details.

OPERATION


The SETCLOCK command is used to change the system time or to
change the system's time zone.

Changing the system time or time zone does not affect any
interval timers in effect. Thus, a PAUSE for a given time
duration will maintain that same duration regardless of how the
system time is changed.

Changing the system time or time zone will introduce any jobs
streamed with a time specification (;AT=, ;DAY=, ;DATE= or ;IN=)
in accordance with the newly-changed system time. Thus, a job
streamed with ;AT=9:00 will be introduced when the changed
system time is equal to 9:00.

The user may provide SETCLOCK with a date and time, a time
correction, or a time zone. The Date-Time form, the Correction
form, and the Time Zone form are mutually exclusive; for instance,
the user may not provide specifications for both a time correction
and a time zone in a single command.

The Date-Time and Correction forms of the command are intended for
slight adjustments of the system time. For example, these forms
would be used to move the time forward or backward slightly in
order to keep the system time synchronized with an external time
source. Both local and Universal (GMT) time are adjusted.

The Time Zone form of the command is intended for the larger time
changes required to move the system to a new time zone, such as
moving between Standard Time and Daylight Savings Time. This form
of the command alters the local time without changing Universal Time.

If the Date-Time form of the command is used, the system time is
adjusted to the specified date and time. This adjustment is
gradual by default. It may be made immediate if ;NOW is specified
and the user has System Manager (SM) capability.

If the Correction form of the command is used, the system time is
adjusted forward or backward by the amount of the correction.
This adjustment is always gradual.

If the Time Zone form is used, local time is adjusted to match
that of the specified time zone. In addition, the system time
zone offset is changed to reflect the new time zone.

The Use of The Time Zone Offset

On the HP3000, Universal Time (GMT) is calculated by starting
with local time and adding or subtracting a time zone offset.
When changing time zones (such as moving from Standard to Daylight
Savings Time and back) the local time is altered, but this change
must not affect Universal Time. To prevent the alteration of
Universal Time from being altered, both the local time and the
system time zone offset must be adjusted. Therefore, using the
Time Zone form of this command is the only way to accurately
change time zones.

If the Date-Time or Correction form of the command is used,
Universal Time will drift along with local time. Thus, the
Date-Time and Correction forms of this command should only be
used to adjust the clock for drift, not to change time zones.

Results of the Time Zone Form

If the change in time zone is to a later time (a change to Daylight
Savings Time or an "Eastern" geographic movement), both local time
and the time zone offset are changed immediately.

The effect is that users of local system time will see an immediate
jump forward to the new time zone, while users of Universal Time
will see no change.

If the change in time zone is to an earlier time (a change from
Daylight Savings to Standard Time or a "Western" geographic
movement), the time zone offset is changed immediately. Then the
local time slows down until the system time corresponds to the
time in the new time zone.

The effect is that users of local system time will see a gradual
slowdown to match the new time zone, while users of Universal Time
will see an immediate forward jump, then a slowdown until the
system time again matches "real" Universal Time.

This method of changing time zones ensures that no out-of-sequence
time stamps will occur either in local time or in Universal Time.

How a Gradual Time Change Works

Whether the Date-Time or a Correction form is used, the default
method of changing the time is to gradually speed up or slow down
the system clock until the change is achieved. Thus, even when a
previous time is requested, the system clock will still move
forward, although at a slower pace than real time. This slower
pace will continue until the desired time "catches up" with the
system clock. Because of the system clock's forward motion, there
will never be a case where two consecutive timestamps appear to be
out of sequence and where system time appears to run backwards.

This change in clock speed is accomplished by establishing a
system time correction which is gradually consumed. During this
time the system clock speeds up or slows down as necessary.
When the correction reaches zero, the system clock resumes its
normal pace. The rate of the correction depends on the load on
the system. The correction rate will be slowed down by frequent
timestamp requests, file accesses and frequent operating system
activity such as context switches. In general, the correction
will take no longer than twice the requested time difference. For
example, a request to slow down the clock by one hour will take
no longer than two hours to complete.

Results of the ;CANCEL Parameter

Any time during an on-going correction, issuing this command with
the ;CANCEL parameter will immediately set the correction to zero
and cause the system clock to resume its normal pace. Any
previous correction will remain. When this option is used, the
system will report the amount of correction which was cancelled.

How a System Time Change Affects Accounting Information

Changing the system time, even gradually, may cause accounting
CONNECT-MINUTES to be distorted. Anyone logging on before the
change and then logging off after the change is completed will
have their accounting CONNECT-MINUTES data distorted. If the time
change is forward, CONNECT-MINUTES will be increased by the amount
of the time change. If the time change is backward, CONNECT-MINUTES
will be decreased by the amount of the time change.

Dangers in Using the ;NOW Parameter

The ;NOW parameter permits immediate forward or backward time
changes. However, several dangerous situations can occur,
such as those listed below. (Note that this list is NOT
meant to be inclusive. Use the ;NOW parameter only with a
full knowledge of its effect on the system workload.)

o Any applications which rely on the forward progression of time
may give inconsistent results if the time is immediately set
backwards. Such applications include the processing of
timestamped transactions in which the sequence of those
transactions is important.

o In order to recover data in case of an unexpected hardware or
software failure, some applications require that the system
time must never seem to go backwards. For instance, some
applications log transactions to a circular file.

These transactions are timestamped, and if the transactions
must be recovered, the recovery program determines the end of
data by looking for timestamps which are out of sequence. If
the system time is set backwards immediately, transactions
which occur after the time change may not be recovered.
Therefore, do not set the time backwards using the ;NOW option
if there are applications which log their transactions using timestamps.

o Accounting CPU-SECONDS data may be distorted. The user whose
process was active during an immediate forward or backward
change might seem to have a CPU-SECONDS time which is an
extremely large positive or negative number.

o STORE / RESTORE, TurboSTORE/XL, or any other file archive system
based on dates or times may not store or restore the files in
the expected manner, since some files may have creation or
access times in the future or may even have access times which
precede their creation times.

o Some compilation tools like MAKE rely on the relative
modification dates of the files in the compilation unit.
Setting the system time backward and then modifying the main
file in the compilation unit may force an unnecessary full
compilation, since the main file may have an earlier
modification time than the files it depends on. Setting the
system time backward and then changing a file needed by the
main file will cause MAKE to think that the changed file's
modification time precedes that of the main file. Thus, the
changed file will not be included in the recompilation.

This command may be issued from a session, job, program, or in
BREAK. Pressing [[Break]] has no effect on this command.

Diagnostician (DI) and either Operator (OP) or System Manager (SM)
capabilities are required to issue this command. Additionally,
System Manager (SM) capability is required to use the ;NOW parameter.

EXAMPLES


The following example illustrates setting the system time by
providing a date and time:

SETCLOCK DATE=07/04/1993;TIME=15:00

The following example illustrates providing a time correction to
advance the system time by one hour.

SETCLOCK CORRECTION= +3600

or

SETCLOCK CORRECTION= 3600

Both of the above examples cause Universal Time (GMT) to change
as well as local time, and therefore while they are useful in
correcting the system time for drift (time gain or loss), they are
not accurate ways to change time zones.

The following example illustrates setting a time correction,
executing a SHOWCLOCK command, cancelling the correction, then
again executing SHOWCLOCK. Note that by the time of the first
SHOWCLOCK the correction has already begun to be consumed.

SETCLOCK CORRECTION= -3600

SHOWCLOCK

SYSTEM TIME: FRI, JUL 24, 1987, 8:47:35 AM
CURRENT TIME CORRECTION: -3568 SECONDS
TIME ZONE: 7 HOURS 0 MINUTES WESTERN HEMISPHERE

SETCLOCK; CANCEL

CORRECTION OF -3550 SECONDS HAS BEEN CANCELED

SHOWCLOCK

SYSTEM TIME: FRI, JUL 24, 1987, 8:52:53 AM
CURRENT TIME CORRECTION: 0 SECONDS
TIME ZONE: 7 HOURS 0 MINUTES WESTERN HEMISPHERE

Note that in the example above the system clock was slower than
normal for several minutes. Canceling the correction did not
undo that change; it merely prevented any further time change.
Thus after this sequence of commands, the system clock is set to
a slightly earlier time than if SETCLOCK had not been issued.

The following example illustrates changing the system time zone
offset from 8 hours 00 minutes in the Western Hemisphere
(Pacific Standard Time) to 7 hours 00 minutes in the Western
Hemisphere (Pacific Daylight Savings Time). This command will
cause local time to jump forward immediately one hour. Universal
Time will be unchanged.

SETCLOCK TIMEZONE=W7:00

SYSTEM TIME: SUN, APR 4, 1993, 7:12:00 AM
CURRENT TIME CORRECTION: 3600 SECONDS
TIME ZONE: 7 HOURS 0 MINUTES WESTERN HEMISPHERE

The following example illustrates changing the system time zone
offset from 7 hours 00 minutes in the Western Hemisphere (Pacific
Daylight Savings Time) back to 8 hours 00 minutes in the Western
Hemisphere (Pacific Standard Time). This command will cause local
time to slow down until it loses one hour. Users of Universal Time
will see an immediate one-hour jump forward, followed by a slowdown
until system Universal Time again matches real Universal Time.

SETCLOCK TIMEZONE= W8:00

SYSTEM TIME: SUN, OCT 31, 1993, 06:23:14 AM
CURRENT TIME CORRECTION: -3600 SECONDS
TIME ZONE: 8 HOURS 0 MINUTES WESTERN HEMISPHERE

Related Information

Commands: SHOWCLOCK, SHOWTIME