SETCLOCK

Alters the system time or system time zone.

SYNTAX

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

{CORRECTION= correction spec}

{TIMEZONE= time zone spec}

{ ;CANCEL}

Parameters

date spec

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 spec

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 the 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 spec

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.

time zone spec

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 completed, 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 the change to be immediate. 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 Notes

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 cause any jobs streamed with a time specification (;AT=, ;DAY=, ;DATE= or ;IN=) to be introduced 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.

Date-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.

Correction: 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.

Time Zone: 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 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 a maximum of 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, and 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:

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.
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.
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.
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.
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 list is only meant to include a few of the dangers associated with an immediate time change; this list does not represent all of the problems likely to be encountered. Therefore, if the ;NOW option must be used, it should be used only with a full knowledge of its effects on the system's workload.

Use

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) capabiltiy is required to use the ;NOW parameter.

Examples of Date-Time and Correction Forms:

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

: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 a SHOWCLOCK command. 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 CANCELLED
 
 :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. Cancelling 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 no SETCLOCK command had been issued.

Examples of the Time Zone Form:

Moving from Standard Time to Daylight Savings Time:

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

Moving from Daylight Savings Time to Standard Time:

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 Univeral 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
Manuals: Performing System Management Tasks