Guardian Programmer's Guide

Managing Time
Guardian Programmer’s Guide — 421922-014
18 - 27
Setting the System Clock
error codes, see SYSTEMCLOCK_SET_ in the Guardian Procedure Calls Reference
Manual. SETSYSTEMCLOCK has the advantage that it is implemented in all RVUs;
on any RVU that supports both procedures, it accepts all the same parameter values
as SYSTEMCLOCK_SET_, so it can be used with identical effect.
You can set the system clock either programmatically using the SETSYSTEMCLOCK
procedure or interactively from the TACL prompt using the SETTIME command. TACL
also has a built-in function, #SETSYSTEMCLOCK, to call the SETSYSTEMCLOCK
procedure, but it accepts only mode values 0 through 3. A utility program like the
example below can be used to invoke SETSYTEMCLOCK interactively. You must
have an ID in the SUPER.* group (group ID = 255) to use either the
SETSYSTEMCLOCK procedure or the SETTIME command.
Using the SYSTEMCLOCK_SET_ or SETSYSTEMCLOCK
Procedure
You typically use the SETSYSTEMCLOCK procedure to synchronize the system clock
with an external clock. To provide a timestamp with finer tolerance, you can connect
an external clock to your system, typically using the Network Time Protocol (NTP) or
Simple NTP (SNTP). You need to regularly compare the timestamps issued on your
own system with a timestamp issued by the external clock. System action depends on
the value of the mode parameter along with the amount that the call to
SETSYSTEMCLOCK intends to change the time.
All systems support nine modes for SETSYSTEMCLOCK to adjust or set the system
time to an absolute value or by a relative value. As of the J06.14 and H06.25 RVUs,
SYSTEMCLOCK_SET_ and SETSYSTEMCLOCK support two additional modes to
adjust the clock rate (frequency). For details, see the Guardian Procedure Calls
Reference Manual.
The SCLOCK program distributed with your system is an example of a program that
synchronizes your system clock with an external clock connected by an asynchronous
line. This program uses the SETSYSTEMCLOCK procedure to adjust the system
clock.
The following example is a simple utility program to call SETSYSTEMCLOCK
interactively. On J06.14, H06.25, and subsequent RVUs, it reports distinct negative
integers for each error; on earlier RVUs all errors are reported as –1. The most useful
mode for making gradual adjustments to the system time is mode 6. Mode 5 is useful
to correct the time immediately, but should be used only when no software is running
that is sensitive to abrupt or negative changes in successive timestamp values. As of
J06.14 and H06.25, mode 9 can be used to adjust the clock rate.
#include <stdio.h> nolist
#include <stdlib.h> nolist
#include <errno.h>
#include <cextdecs(SETSYSTEMCLOCK)>
int main (int argc, char *argv[])
{
short mode, tuid;