CLKMGR.TXT -- 02-apr-2005
-------------------------

Pieter Bras
Cambridge, MA
pbras@pobox.com


Introduction
------------

CLKMGR is an OS/2 clock-setting software package that provides features
not available in other such software:

 - sets the OS/2 system clock with .01-second or better precision.
 - keeps the clock accurate to within milliseconds by determining the
   hardware clock error and making compensating corrections in real-time.
 - slews the clock to avoid making step changes in the system time.
 - preserves clock monotonicity (does not run clock "backwards").
 - automatically handles Daylight Saving Time transitions and Leap Second
   adjustments in real time.
 - works as both network client and server, using the same protocol.

CLKMGR user SNTP (RFC 2030) as its default protocol; however it also supports
the NIST "Daytime" protocol (RFC 867).  CLKMGR expects to start when you boot
up OS/2 and continues running right until shutdown. You can start it from the
startup folder or from STARTUP.CMD.  As long as it runs (and has access to an
NTP or NIST time server) it will keep the OS/2 system clock accurate. It will
compensate for inaccurate hardware clocks and will also adapt to compensate
temperature-induced oscillator frequency drift.

Please note that CLKMGR is not a port of the Unix ntpd program; it uses the
NTP protocol to talk to NTP time servers, but can alternatively use the NIST
Daytime protocol to provide equally precise timing (to about 0.1 millisecond).
The reason the NTP protocol was chosen as the default for CLKMGR is that
international users will likely be located much closer to an NTP server.


Compatibility
-------------

CLKMGR requires the following:

OS/2 Warp (32-bit) with TCP/IP stack (16- or 32-bit)

I have personally tested CLKMGR successfully on the following configurations:

OS/2 Warp 3 Connect with FP 40, TCP/IP stack 4.02y
OS/2 Warp 4 with FP 10, TCP/IP 4.2
OS/2 Warp 4 with FP 15 with recent (2005) IBM testcase kernels, TCP/IP 4.2
OS/2 Warp 4.5 (MCP 1), TCP/IP 4.3 (*)

These all used the single-processor kernel. However the software is designed
to run properly on SMP systems also, and has been successfully tested on 
OS/2-SMP systems by beta testers. 

(*) WARNING: if you are using a pre-fixpack TCP/IP 4.3 and a PPP dialer such
as InJoy, then you must install fix ic27649 or ic30667 before using ClkMgr:

ftp://ftp.software.ibm.com/ps/products/tcpip/fixes/v4.3os2/ic27649

CLKMGR presents a very low CPU load and can be run on any hardware that will
support OS/2 Warp, including the ancient 80386 and 80486 processors.

The included CLOCK01.SYS driver is a complete rewrite of the IBM clock driver.
It is compatible with the CLOCKSCALE={1|2|4} kernel directive in CONFIG.SYS
when used with the recent IBM OS/2 kernels (2001-10-26 and later).
It's designed to maintain correct time even in the face of lost or blocked
clock hardware interrupts, even at the 512 Hz. interrupt rate.

The driver is 100% backwards compatible with well-behaved OS/2 applications
(i.e. those that don't attempt to write to the computer's clock hardware) and
provides the following additional features:

 - allows OS/2 system clock to be reliably set to the nearest .01-second.
 - allows an application (i.e. CLKMGR) to trim the clock frequency so that
   the OS/2 clock continues to run neither fast nor slow.
 - allows the OS/2 clock to be slewed as well as stepped.
 - allows an application (i.e. CLKMGR) to make the OS/2 clock read-only so that
   (for instance) a network logon won't automatically adjust the OS/2 clock.

The benefits of using the new CLOCK01.SYS driver apply equally well to DOS and
Win-OS/2 applications as they do to OS/2 native applications.

PS/2 hardware is not supported.


Installation
------------
Unzip the distribution archive to a directory of your choice, e.g. \CLKMGR

Back up the existing CLOCK01.SYS, usually found in the \OS2\BOOT directory
of your OS/2 boot partition.

Place the included CLOCK01.SYS driver in the root directory of your boot drive.
This will automatically override the existing clock driver as the OS/2 loader
searches the root directory before looking in \OS2\BOOT.

Reboot to make the driver change effective. You don't need to change anything
in CONFIG.SYS, as the clock driver will be loaded automatically.

NOTE: If you later apply an OS/2 fixpack, the new CLOCK01.SYS driver may be 
overwritten; CLKMGR will then be unable to run until you re-install its driver
as above.

Switch to the \CLKMGR directory and run the MAKELIST utility:
MAKELIST -g

Instructions for using MAKELIST are contained in the file NISTIME.INF.


Running CLKMGR
--------------

At the OS/2 command line, type "CLKMGR ?" for a listing of command-line
options.

Once the program is running, type "?" to see a list of run-time commands.

If you start the program at boot time (for instance from the startup folder)
it is useful to provide a small delay to make sure that the TCP/IP stack is
fully initialized and running. This is done with the -w command-line option.

The default server polling interval is 2 hours. If your computer is subjected
to rapid ambient temperature swings of more than a few degrees, it may be
desirable to poll more often. If you are in a temperature-stable envronment,
you may need to poll only once or twice a day. You can use the -i command-line
option to specify the polling interval, and the interval can also be changed
interactively while CLKMGR is running.

The included CLOCK01.SYS uses the RDTSC instruction available on Intel Pentium
and later (and compatible) processors. However, if your computer's CPU can run
at a variable clock speed, be sure to include the -v1 option on the CLKMGR
command line, as auto-detection of variable-speed CPUs (current and as-yet
unreleased) isn't guaranteed to be reliable.


De-installation
---------------

Delete (or rename) the file CLOCK01.SYS in the boot partition, and make sure
that the prior CLOCK01.SYS can be found in \OS2\BOOT.

Delete the files in the \CLKMGR directory tree.

CLKMGR does not modify CONFIG.SYS or the OS/2 .INI files.


Selecting Servers
-----------------

There is no default time server defined to the program, so it needs a config
file such as the included NIST-SRV.LST file. You can create a customized list
by running the REXX script MAKELIST.CMD.

At startup, CLKMGR will look for a file named MY-NIST-SRV.LST by default.
If this is not found, it will then look for a file named NIST-SRV.LST.
An optional command-line argument can specify a differently-named file.

CLKMGR is not restricted to using only the servers included in the distribution
NIST-SRV.LST.  You can create your own list such as the following example
(suitable for Cambridge, Massachusetts):

$
ntp.harvard.edu
tick.mit.edu
nist1-ny.glassey.com
nist1-dc.glassey.com
192.168.0.50
$

and then run MAKELIST to create a file suitable for input to CLKMGR.
Type MAKELIST -? for help with the MAKELIST program.

CLKMGR's server list can be changed while it is running.  Edit your list of
servers, run MAKELIST, and then type NEWLIST in the CLKMGR window. To display
the current server list, type LIST to CLKMGR.

For best results, you should try to find good NTP servers near you, with
network delays as short as possible.  A catalog of publicly accessible NTP
servers is available at:

http://ntp.isc.org/bin/view/Servers/WebHome

Also, there are often NTP servers available at universities, which may not be
included in the above-mentioned catalog.


Additional Files
----------------

The file ADJUST.DAT contains information about the hardware clock error rate.
This will be written each time that the error rate is recomputed. It normally
takes up to 12 hours for the error to be properly determined after the program
starts up.

If you enable the server, it will declare itself to be "unhealthy" until the
hardware clock error rate (ADJUST.DAT) has been determined. If you can't wait
that long, you can create a one-line ADJUST.DAT with a text editor as follows.
Assuming your PC clock gains 0.5 seconds per day, the file would contain:

-0.5  0  0.0

where the first field is the negative of the daily clock error, in seconds.
Note that this file has the same format as the Unix /etc/adjtime file.
There is a default ADJUST.DAT included with the distribution.

Also included are a number of other executables:

KILLCLKMGR.CMD -- script to terminate ClkMgr from within a batch file.
NISTIME.EXE    -- updated version of the "classic" NISTIME program. By itself,
                  it does not require the new clock driver. Type "nistime ?"
NISTIME2.CMD   -- updated version of script to run NISTIME.EXE with a list of
                  NIST time servers. Type "nistime2 ?"
MAKELIST.CMD   -- Sort the list of NIST servers by increasing network delay.
                  Type "makelist ?"
HOUR.EXE       -- Generate long beep on the hour and short beep on half hour,
                  according to OS/2 clock.  Type "hour ?"
UPDAYS.EXE     -- Writes OS/2 system uptime to standard output; requires the
                  included version of CLOCK01.SYS.  Type "updays ?"

The included version of NISTIME (0.3j) includes an additional option that is
available when CLKMGR is running and has synchronized its UTC clock:

 -p   compare CLKMGR UTC time with remote server's time; also implies NISTIME
      option -s0 (do not try to set the OS/2 clock).


Copyright Notices
-----------------

NISTIME.EXE was originally developed with US Government support and may
not be sold, restricted, or licensed.  The icon for NISTIME was copied
from NISTIME for Windows, which is downloadable from the NIST website.

The included CLOCK01.SYS is based on the IBM DDK code which is subject to an
IBM DDK License Agreement; see the included file ddk-l.txt.

Everything else in this package is Copyright (C) 2002, 2005 Pieter Bras.
All rights reserved.

This software may be freely redistributed provided that no changes are made
to the files. This software may not be sold or included as part of any other
software product or collection, commercial or otherwise, for which money or
other valuable consideration is charged.


NO WARRANTY
-----------

This software is freeware and is provided "AS IS" without warranty of any
kind, either expressed or implied, including, but not limited to, the
implied warranties of merchantability and fitness for a particular purpose.
If problems arise in connection with the installation or use of the software,
your only remedy is to stop using the software, and/or delete the files from
your computer.

<eof>
