Guardian Procedure Calls Reference Manual

Adjusting the Clock Using Modes 0, 1, 2, 3, and 6
The system adjusts the clock by very small amounts. Small changes are applied at the rate of one
microsecond every 75 milliseconds (J- or H- series) or every 300 milliseconds (G-series). Moderate
changes are applied over a five-minute period. The maximum retard and advance rate is -400
PPM and +4000 PPM on TNS/E, or -100 PPM and +1000 PPM on TNS/R. For example, if the
clock is slow, making a change of two minutes takes about 33 hours on a G-series system or about
8 hours on an H- or J-series system; if the clock is fast, making a change of two minutes takes about
14 days on a G-series system or about 3.5 days on an H- or J-series system.
Stopping Time Adjustment
• Any successful call to SYSTEMCLOCK_SET_ in modes 0 through 7 stops any current time
adjustment before applying the new adjustment or setting.
• If you call SYSTEMCLOCK_SET_ with the mode parameter set to 8, the system stops any
ongoing time adjustment.
Adjusting Clock Rates Using Modes 9 and 10
• In mode 9, the julian-gmt parameter specifies a change in the rate (frequency) of the clock,
specified in units of parts per million million (PPMM), also referred to as parts per trillion. For
example, a value of -10000000 (minus ten million) causes the clock to run slower by 10 parts
per million; that amounts to 10 microseconds per second, or 864 milliseconds per day.
• The limit on an individual adjustment is ±100 PPM (±100 million PPMM); a mode-9 call with
the julian-gmt parameter outside that range is rejected with an error return.
• Successive calls with mode 9 accumulate by addition. The limit on the algebraic sum is ±200
PPM (±200 million PPMM); an attempt to exceed that range is rejected with an error return.
• A call with mode 10 terminates any rate adjustment (resets it to zero). The julian-gmt
parameter is ignored and may be omitted.
• Adjusting the clock rate reduces the need to adjust the time often. For example, consider a
program that periodically reads the time from a reference clock and adjusts the system time.
Assume the uncorrected system clock is running consistently slow by 15 PPM, and the program
updates the time once an hour. In an hour, the clock will have lost 3600*15E-6 sec=54 ms.
The program would issue an adjustment of about +54 ms (mode = 6, julian-gmt =~
54000); the system applies it over about 5 minutes, but after an another hour the time will
again be about 54 ms behind. By instead making a rate adjustment of about +15 PPM (mode
= 9, julian-gmt =~ 15000000), the system clock will proceed at very close to the correct
rate, so time adjustments can be smaller and/or less frequent.
• While rate adjustments can be made manually, by computing the ratio of time gained or lost
to the interval across which the gain or loss occurred, it is preferable to use a program that
adjusts both the time and the rate automatically from multiple readings of an external reference
clock. For example, NTP (the Network Time Protocol) computes both the time (phase) and rate
(frequency) adjustment necessary for the clock; an NTP client tailored to the
SYSTEMCLOCK_SET_ interface can utilize it to keep the system time accurate.
Using TUID
• The operating system maintains a global variable called TUID (Time Update ID). It starts at 0
at cold load, becomes 1 when the system initially sets the time, and is incremented whenever
time is reset. TUID is synchronized in all the processors by the same global update mechanism
that propagates the time change.
• The current value of TUID is optionally reported by the JULIANTIMESTAMP procedure.
SYSTEMCLOCK_SET_ Procedure 1411