<<< EISNER::DJA1:[NOTES$LIBRARY]SITE_MANAGEMENT.NOTE;1 >>>
                              -< Site Management >-
================================================================================
Note 55.16                  NBS Time Synch "on-line"                    16 of 20
EISNER::KOZAM                                       154 lines  14-JUL-1990 21:56
                                  -< NBS.TXT >-
--------------------------------------------------------------------------------

NBS - Set system time to National Bureau of Standards Clock - Version 2

Author:	Marc L. Kozam
	MLK Software Services
	177 N. Dean Street, Suite 104
	Englewood, NJ  07631
	201-567-9204

Changes since version 1

	The first version had several timing problems for modems that
were connected directly (i.e. no intervening buffering between the system
and the modem).  This manifested itself as an inability to set the time
and numerous "Invalid OTM mark" errors.  This was related to the fact
that at 1200 baud, both transmit and receive must be active at the same
time in order to read and echo the time information within one second.
Modems that are connected via LAT or through other systems, or with buffering
internal to the modem did not suffer from this problem.  This has been
corrected so that all modems work.

	There was also a problem if the <delta> time was specified at
a position other than at the end of the line.  This has been corrected
so that the command line is correctly parsed.
	
Running NBS

	NBS requires a 1200 baud modem to connect to the National
Bureau of Standards located at 303-494-4774.  (The alternate number at
202-653-0351 uses a different, less informative format that is not
compatible with this program.)  NBS assumes that the connection has
already been established before NBS is started.  The connection may be
made using your favorite dialer software or manually with SET/HOST or KERMIT.

Prerequisites

	NBS uses the logical symbol MODEM to identify the communication
line to use.  In most cases, this will be your modem.  Thus, you will need
to use the command such as $ DEFINE MODEM TXA4: before running this program.

	You need to define the command NBS in order to use command line
options.


Command Line Options

-t	Use the system's TOY clock to reset the system clock.
	This helps provide a measure of system clock drift.  NBS
	reports how much adjustment occurred.  No modem is necessary
	to use the -t switch.

-d	Take daylight savings time into account when setting time.
	This DOES NOT mean that daylight savings time is in effect.
	When used, NBS uses the information received over the modem
	to determine whether it is daylight savings time or not.
	For most applications, the -d switch should be used.

-c	Don't actually set the system time, merely compare it to
	the information received over the modem.  Useful to see how
	fast you are drifting.  Non-privleged users can run this too
	since the system time is not changed.

-p	Only set the system time if the time can be set with high
	precision.  When set with high precision, the time delay
	incurred due to modem encoding and ground/satellite links
	is taken into account.  If such precision can not be attained,
	the system time is not set.  Without the -p option, the system
	without regard for high precision.

<delta>	This is the time offset, when daylight savings time is NOT in
	effect.  It is a valid VAX/VMS delta time specification.  If
	you are in the Eastern time zone, then this should be "0 5:00"
	to indicate that you are 5 hours behind UTC.  In the Central
	time zone, it is "0 6:00".  The day field must 	be present,
	although it will, for almost all applications, be 0.

Recommendations

	Most often, the command used will be

	$ NBS -d "0 5:00"

(adjusting the <delta> according to your time zone.)  The offset "0 5:00"
is correct if you are on Eastern time.

	If you're interested in accuracy, but not to compulsion, you can
use the following commands:

	$ NBS -d "0 5:00"
	$ NBS -d -p "0 5:00"

The first line sets the time any way it can.  The second command
attempt to set the time with maximum precision.  If it fails, however,
at least the time has been set.

	If you're compulsive about time, the try:

	$ NBS -t
	$ NBS -d "0 5:00"
	$ NBS -d -p "0 5:00"
	$ NBS -d -c

	The first command updates the system clock from the hardware
clock.  The second command sets the time any way possible.  The third
command sets the time with high precision, and the fourth line checks
how well you did.  If NBS modems are busy, you may be hung up on after
only 15 seconds.  This may not be enough time to do all these things
in one call.

	If everything goes well, NBS sets the DCL symbol $STATUS to
"%X00000001", otherwise $STATUS is set to "%X00038004".  These values
seem rather strange, but they relate to the fact that C isn't too well
coorindated into the VMS environment.

Privileges

	To get the data from the National Bureau of Standards, you
must have privileges necessary to access the modem.  No modem access
is required if the -t switch is used.

	To set the system time, you must have OPER and LOG_IO
privileges.  This is required unless you use the -c option.

Accuracy

	In many ways, the accuracy attainable through this program
far exceeds that which is reasonable for a VAX style processor, with its
relatively inaccurate system clock.  Without using the -p switch, you
can anticipate accuracy in the range of +/- 250ms (if a satellite link
is used) and +/- 50ms (if a ground link is used).  With the -p switch,
accuracy may be +/- 10ms, but some calls may fail because the NBS system
may not be able to figure the round-trip delay time.

	With system clocks that may drift several seconds in a day,
it should be clear that this is more than sufficient for all but the most
unusual applications.  Special applications may want to call the NBS
number directly.

Limitations

	No modem control is used, although it probably should be.  NBS
terminates when:

	1.  The system time has been set (or checked).

	2.  The communication line can not be "cleared" - i.e. we can't
	    interpret what we're receiving.

	3.  The communication line has had to be cleared 10 times and
	    we still haven't set the time (probably due to very bad
	    line noise).

In the case of a disconnection, NBS will be unable to clear the line, and
after attemting to do so for 2 seconds, will terminate.
���������������������������������������������������������������������������������