RighTime v1.0a, TestTime v1.0a Copyright 1991, GTBecker
March 30, 1991 All rights reserved


Shareware Notice

This file (RIGHTIME.TXT) and evaluation program files RIGHTIME.COM
and TESTTIME.COM should be contained in the shareware distribution file.

Neither evaluation program will run if RIGHTIME.TXT is missing
from the same directory or has been modified in any way.

These files are the copyrighted property of G.T. Becker and Air System
Technologies, Inc. of Dallas, Texas, USA.

You may use these evaluation programs for up to one month, and you
may - and are encouraged to - pass the shareware distribution file along to
others, but you may not modify, rename or sell the files or programs to
anyone under any circumstances. Shareware distributors may charge a
reasonable fee for their services and media.

You are encouraged to register your usage of RighTime. Registered
RighTime users receive a diskette containing the current version of the
registered programs, a printed user manual and usage license, notification
of new releases, and enthusiastic support from the author when you need it.
The registered version of RighTime is functionally identical to this
shareware distributed version, but it lacks registration reminders, the
requirement that all files remain resident, and it is serial numbered.

Beyond the immediate tangible benefits, registration also provides
support for the shareware software distribution concept. Shareware means
quality software that you try before you buy. More happy shareware users
means more happy shareware authors that produce more shareware distributed
program offerings. We all benefit, but only if the users do their ultimate
part of registering. If RighTime is a useful addition to your system,
please register your usage.

To register, fill in the form at the end of this document and send it
and US$25 for a single machine to Air System Technologies, 14232 Marsh
Lane, Suite 339, Dallas, Texas, 75234, USA. Site licensing is available.


What is RighTime?

RIGHTIME.COM is a TSR for MSDOS v3.0 and later which will correct
PC/AT "CMOS"-type clock error up to about 5.5 minutes per day; if RighTime
is automatically and dependably installed via AUTOEXEC.BAT as suggested
below, the system clock will behave as properly and accurately as one
should hope the system clock of a computer would. Written in 80286
assembly language, the resident portion occupies only 3K of system memory.


First, here is what RighTime cannot do:

- RighTime cannot correct clock boards or computer motherboard
clocks that do not emulate the PC/AT hardware clock and its
BIOS support precisely; AT&T PC 6300, AST Six Pack boards and
the like are not supported.

- RighTime cannot properly correct an unstable clock; most clocks
are slow or fast and they are essentially unvarying. If your
clock wanders aimlessly, repair the hardware first.

RighTime exploits the better qualities of each of the two clocks in
your system and improves upon them by doing three fundamental things:

* RighTime slaves the DOS system clock (which has higher
resolution) to the hardware clock (which has higher stability),

* RighTime improves and maintains accuracy by regularly
calculating and applying corrections to both clocks, and

* RighTime monitors time set commands (and the equivalent system
calls from any program) to learn the hardware clock error rate.

RighTime intrinsically sets the hardware clock and solves the
midnight rollover date bug that exists in some DOS versions; this
eliminates the need for other utility programs or drivers that perform
these functions. The hardware clock seconds transition will also be
properly set by RighTime.

Each time you set the time, RighTime will improve the accuracy of the
corrections and will subsequently improve the accuracy of the clocks. It
should be easy to achieve a worst-case error of less than 0.5 second per
day and under good conditions, less than 0.5 second per week; typical
results are ten times better.

Large time changes (larger than approximately 5.5 minutes) will not
affect the corrections, permitting standard time to daylight time and the
converse adjustments.

Some rogue programs apparently change the 8254 timer load constant
resulting in a suddenly fast clock which requires a reboot to correct;
reexecuting RighTime will load the right value (which will restore the
proper rate) and indicate the correct time without resetting the time if it
is done reasonably promptly.


Getting Started

To use RighTime, first decide where to store the corrections. There
are three options: unused CMOS RAM, disk file, or neither. If you have
only floppies the disk file option is impractical, so try the CMOS RAM
option. If you have a hard disk, you can probably use either the CMOS RAM
or the disk file option.

The CMOS RAM option involves some initial bravado: not all BIOS ROMs
use CMOS RAM similarly, so before attempting to use the CMOS RAM option, be
forewarned that CMOS RAM contains system setup data that RighTime might
inadvertently disturb; be prepared to reset the setup data if the CMOS RAM
option is unsuccessful on your system. See the Hardware Compatibility
List, below. If this dissuades you or if you are otherwise reluctant, use
the disk file option until you gain some confidence.

If you chose the disk file option, RighTime will attempt to write to
its own program file from time to time, so write access must be allowed.

RighTime can also be configured with no correction storage, with
consequential loss of some of its utility (see No Correction Storage
Option, below).

If you know how fast or slow your clock appears to run per day, you
can optionally speed the learning process of RighTime by suggesting a
correction to the program as a signed number in hundredths of a second,
positive for a slow clock, negative for a fast clock. For example, if your
clock runs about two minutes fast per day, the suggested correction should
be -12000 (120 seconds times 100). There are actually two corrections that
RighTime normally applies, one while the system is running and warm, and
another when the system is turned off and cool. If you know the cool
correction, suggest it also. If you don't know one or you know neither
correction, RighTime will determine them anyway; it'll just take longer for
the corrections to mature to good accuracy.

If you have been using another resident driver or TSR to correct the
weaknesses of your clock, remove all references to it from your CONFIG.SYS
and AUTOEXEC.BAT files and, once you are confident that RighTime is all it
purports to be, remove the other driver or TSR from your system.

To get started, place RIGHTIME.COM in some directory (dev:\path,
which does not need to be included in a PATH statement), and run it from
the DOS prompt:

if you chose the CMOS RAM option,

dev:\path\RighTime /R /Wwarm /Ccool
or
dev:\path\RighTime /R /W /C

if you chose the disk file option,

dev:\path\RighTime /F /Wwarm /Ccool
or
dev:\path\RighTime /F /W /C

Also, in your AUTOEXEC.BAT file (as the first TSR, but after any
PROMPT, PATH or SET statements), add:

if you chose the CMOS RAM option,

dev:\path\RighTime /R

if you chose the disk file option,

dev:\path\RighTime /F

For example, I put RIGHTIME.COM in C:\DOS\TIME, my clock runs about
1.5 seconds fast per day when warm, and I use the CMOS RAM option. I
started by running

C:\DOS\TIME\RighTime /R /W-150 /C

and I added this line to my AUTOEXEC.BAT file:

C:\DOS\TIME\RighTime /R

Had I chosen the disk file option, I would have run

C:\DOS\TIME\RighTime /F /W-150 /C

and I would have added this line to my AUTOEXEC.BAT:

C:\DOS\TIME\RighTime /F

If RighTime encounters difficulty during its installation, it will
report one of several messages and terminate (see Installation Error
Messages, below). A successful installation will display the corrections,
an "Installed" message and a copyright notice.

Setting the Time

Now that RighTime is installed and running, set the date and time as
accurately as possible. If you have access to a time standard, use it.
For best accuracy, use a NIST telephone service time setting program such
as Professional TimeSet v6.0 by Peter Petrakis. Alternatively, you can
listen to WWV or CHU or a radio network news broadcast and be prepared to
set your clock when you hear the beep on the minute or hour. Don't use a
radio station that is airing a call-in talk show; the audio is usually
delayed six to ten seconds on such programs to allow for profanity dumping,
and so the beep will be equally late. An all-news format station is
probably not delayed. To be certain, call the radio station and ask for
engineering; they will know. Local telephone time services are usually
poor; don't trust that they are correct. What is important is accuracy;
RighTime needs a reference to initially learn from, and unless you care to
(and know how to) automate it, you are it.

From this moment on, RighTime will monitor each time set occurrence,
learning from your adjustments. Whenever you notice or suspect that the
indicated DOS system time is insufficiently correct to satisfy you, reset
it accurately. Separate time sets by a minimum of 30 minutes. You will
find that the clocks will become more and more accurate and the need for
adjustment will decrease, becoming infrequent; you must, however, set the
time accurately at least once per month.

When you turn your computer on, allow it to boot and then, if it is
necessary, set the time accurately within ten minutes of boot. Time
adjustments that are performed within ten minutes of boot will affect the
cool correction; adjustments performed after that ten minute period will
affect the warm correction.

Each time you reboot, RighTime will display the current corrections.
After a few days of your occasional diligent time setting, the corrections
should settle to fairly constant numbers, which will be true indications of
the uncorrected performance of your hardware clock. Once it is installed,
you can also display the current corrections by simply running RighTime
again at a DOS prompt (no parameters are required). The correction that is
currently being applied to the DOS clock will be displayed and a functional
self test will also be performed, verifying that RighTime is currently
running properly on your system.

As long as RighTime is in use and you've been diligent in your
adjustments, and the corrections have matured, the hardware clock error
will not be more than 0.5 second, and the DOS clock will be much more
accurate than that. In fact, the DOS clock error can be less than 0.01
second; but since DOS can't express the time any better than the 55
millisecond tick rate permits, this accuracy might not be easily seen.
Nevertheless, it is there. A tool is provided with RighTime that allows
verification and visualization of RighTime's actions; see TestTime, below.

RighTime has limits of one week of inactivity, and one month between
time sets, that can be corrected to a maximum of 5 minutes, 27.67 seconds
per occasion; beyond that, all bets are off. In that case, unpredictable,
and probably incorrect, clock changes can occur, but if it can, RighTime
will advise you of its difficulty. For example, if your clock runs two
minutes slow per day and you don't use the system for three full days, when
you boot up you will receive a message warning that the clock needs to be
adjusted manually. The subsequent adjustment will not affect the
corrections. Similarly, if you only set the time twice each year, RighTime
is not for you and will not cope well.


No Correction Storage Option

If you have difficulty with both the CMOS RAM and disk file options
or you need or wish to use neither option, RighTime can still correct the
clocks for as long as the system runs continuously. What RighTime has
learned will be lost when you reboot or power down, and there can be no
cool correction. Otherwise, all of the comments above apply. If you
suggest a good warm correction and you set the clock after you boot,
RighTime will serve well.

To run RighTime in this mode, add (as the first TSR, but after any
PROMPT, PATH or SET statements) the following line in the AUTOEXEC.BAT
file:

dev:\path\RighTime /N /Wwarm
or
dev:\path\RighTime /N /W

You might want to follow this with a TIME command (perhaps preceded
by a DATE command) to remind you to set the clock at each boot.


Installation Error Messages

RighTime might report one of the following messages at installation
execution time:

"DOS version 3.0 or later is required"
The PC/AT "CMOS" hardware clock is not supported by earlier DOS
versions.

"System is not 80286 code compatible"
RighTime expects that the system processor is at least an
80286. The 80C286, 80386(DX), 80386SX, and the 80486 are also
code compatible with the 80286. Systems that use the 8088,
8086, 80188, and the NEC V-series processors will not run
RighTime.

"No AT hardware clock is present or clock is not running"
Either a hardware clock or BIOS failure prevents use of the
clock, or the clock chip is not installed in the system.

"Hardware clock alarm is not functioning"
RighTime has failed a self test. Try again in a minute or so.
If this message persists, please notify the author.

"Alarm is not supported by BIOS"
The BIOS has reported an unsuccessful attempt to set the clock
alarm feature. The BIOS is not compatible with RighTime.

"Already installed"
RighTime is currently resident and running in the system.

"Correction storage switch is required"
Either the disk file (/F), CMOS RAM (/R) or no storage (/N)
option must be specified in the command line.

"Invalid switch"
An unrecognized option switch is present in the command line.

"Invalid parameter"
A value associated with an option is inappropriate.

"Directory must hold original RIGHTIME.TXT during evaluation"
The unregistered shareware distributed versions of RighTime and
TestTime require that their directory contains the original
unmodified documentation file, RIGHTIME.TXT.

"Program has been altered"
RIGHTIME.COM has been modified in some way. Immediately delete
it from your disk and replace it with the distributed program.


PC/AT and MSDOS Clock Esoteria

18.2

DOS historians say that the designers of the PC tried to do the DOS
system programmers a favor by dividing an hour into 65536 parts, or about
18.20444444 ticks per second, making the most significant 16 bits of the 32
bit tick count directly indicate the hour and theoretically simplifying the
system code. Somehow the hardware didn't turn out that way, resulting in
about 176 extra ticks per day. The 8254 timer/counter clock input of
1193180 Hz and its counter 0 load constant of 0 (effectively 65536),
yielded a hardware tick rate of approximately 18.20648193 ticks per second,
and that remains so today. That looks like a small difference, but it
amounted to an almost ten second gain per day.


DOS designers corrected for the hardware error by redefining the
number of ticks per day to include the extra ticks and a standard was set:
the exact ticker rate was defined by the quotient of the number of ticks
per day and the number of seconds per day (1573040/86400), which is
approximately 18.20648148 ticks per second. When they did that, they made
it possible to convert from ticks to time and from time to ticks in two
ways, each way exact, but one according to the PC hardware implementation
and one according to the day-length standard definition.

Using only 16 bit integer arithmetic, the conversion that matches the
PC hardware requires multiplying the current time in hundredthseconds by
59659 (which is 1193180/20), dividing that product by 65536 (discard the
least significant 16 bits), then dividing that quotient by 5 to yield the
tick count. The resulting rate is approximately 0.1820648193 ticks per
hundredthsecond, which is the same as the hardware rate. The conversion
for the day-length standard can be accomplished by multiplying the current
time in hundredthseconds by 19663 (since 1573040/86400 = 19663/1080),
dividing that product by 10800, then dividing that quotient by 10 to yield
the tick count. The resulting rate is approximately 0.1820648148 ticks per
hundredthsecond, the correct day-length standard rate.

Ironically, MSDOS authors ignored their own day-length standard and
chose to match the hardware to determine the time. The resulting error
(compared to the day-length standard) is very small, only 0.039 tick per
day, but for some requirements that can be significant. For example, if
the resulting time is rounded or truncated to whole seconds, the two
methods will yield different results for some values. For most
applications though, the choice won't matter.

Often, the number 18.2 or the period 55 milliseconds is used to
describe the system clock (interrupts 8 and 1Ch) tick rate. In every case,
that is not the correct number, but an approximation. Almost all PC
"compatible" machines use this 18.2 standard tick rate, but there are
exceptions; the AT&T 6300, for example, uses 18.75.

Stability, Accuracy and Resolution

Often confused, these three qualities are different and are only
obliquely related, although each is required to exist in any good clock.
They can be prioritized with little difficulty. Stability is foremost.
Even if lacking in other qualities, a stable clock is useful if you know
what to expect of it; an unstable clock generates worthless noise.
Accuracy can only be meaningful if the clock is stable. Resolution is
required only to meet the requirements of the clock's task; to catch a
train on time, for example, you don't need hundredths of a second
resolution, just an accurate, stable clock that will tell the time to
minutes, or maybe only hours.


Translation Gain, Resolution and Truncation Losses

Suppose that some accurate clock resolves only to minutes, and you
read the clock often at random, or asynchronous, times. Your time reading
will be correct if it is made at the instant the minutes have incremented
from one number to the next, but your reading will appear to be just under
one minute low if made at the instant before the next minute increment. If
you do this enough, the average or mean error of your readings will prove
to be one half minute low. This is the mean resolution loss; an artifact
of any finite resolution, resolution loss is present when asynchronously
reading any accurate digital clock.

Some applications require resolution loss compensation, which can be
as simple as increasing the time by one-half of the unit of resolution of
the clock; postcompensation can be applied when the time is read, or
precompensation can be applied when it is set. In the example, the range
of the compensated error would extend from 30 seconds low to 30 seconds
high; the mean resolution loss would be zero. More sophisticated
compensation schemes can synthetically increase the effective resolution of
the clock, but resolution loss, though smaller, remains unavoidable.

A similar effect, translation gain, occurs when asynchronously
setting a digital clock; the instant of time set can occur anytime between
one regular increment and the next. If set at the instant after an
increment, no error results; if set immediately prior to an increment,
however, the clock will be effectively set one unit too high. On the
average, asynchronous clock sets will produce a clock time that is one-half
unit of resolution high; negative precompensation of one-half unit of
resolution will compensate for translation gain.

Truncation loss is an effect that results from the disregard of
digits of low significance. When converting from one time base to another,
the result is often not an integral number in the new time base. If the
fractional part is ignored, loss results. Arithmetic rounding to the
nearest unit of resolution is effective compensation, and is easy to
implement by adding one-half unit of resolution; the fractional part of the
sum is then discarded by the time set function.

In the PC/AT, all of these compensations are useful, and when
combined, they are easy to implement. Translation and truncation errors
are intrinsic to the function of RighTime and are compensated, and since
few application programs - nor DOS itself - consider resolution loss, it is
precompensated.


TestTime

Included with RighTime is a program tool that can provide some
interesting insight into the relationship of the clocks in your system and
the function of RighTime. TestTime takes no command line parameters. It
will determine and express whether or not RighTime is running in the
system, and it provides a continuous single line display of the clock
system status.

The status line is terse:

H[date:hh:mm:ss(:aa)] D[date:hh:mm:ss] corr diff distrib

where
H is the hardware clock data. (:aa) is the alarm seconds data.
While RighTime is running, the alarm seconds will
increment in four second steps;
D is the DOS system clock data;
corr is the current correction that is applied to the DOS
system clock in hundredthseconds, if RighTime is
resident;
diff is the signed time difference between the hardware and DOS
clocks in seconds. A positive difference indicates that
the DOS clock leads the hardware clock (it displays a
higher, or later, time). Since DOS can only express time
to 55 millisecond resolution in hundredthseconds, the
difference is determined by a 100-sample averaging method
whose accuracy improves with time. The last character of
diff will initially be an approxima (a wavy equal sign)
to indicate that full accuracy has not been achieved; it
will change to an equal sign or a one-half sign when the
difference is accurate. A one-half sign indicates that
the difference value is between hundredths (an average of
5 milliseconds of resolution);

distrib contains three numbers corresponding to the percentage
of difference samples that are negative, zero, and
positive. When the average difference is zero, the
distribution of differences should ideally be balanced
around zero. As the DOS clock drifts away from the
hardware clock, the balance will shift until all samples
are positive or negative.

An arrow to the left of each seconds data indicates which data
last changed.

You can use TestTime to learn much about the behavior of the two
clocks in your system. Try running it without RighTime installed and
notice that the DOS clock is never the same as the hardware clock. Set the
time and run TestTime again; if your DOS sets the hardware clock, check to
see if the seconds are synchronized. They probably are not. Run TestTime
some time later and see if the relationship between the clocks has changed;
there's a good chance that it will have. Which, if either, is correct?

Try these things with RighTime installed and see the difference for
yourself.


Briefly, How RighTime Works

Every four seconds, RighTime reads the hardware clock time and
calculates and sets the proper system time tick count. As usual, DOS
continues to increment that count at each 55 millisecond timer tick
interrupt and uses the count to determine the time whenever it is
requested.

When the user or an application program resets the time, RighTime
determines the sign and magnitude of the adjustment and uses this data to
modify correction factors that it maintains. RighTime normally stores
these corrections in CMOS RAM or in its own program file on disk.

Every two minutes, RighTime stores the current time so the period of
inactivity can be determined when the system is next booted. The proper
(cool) adjustment can then be calculated and the hardware clock can be
adjusted if it is required. If the cool adjustment spans midnight, the
date will be appropriately adjusted.

RighTime provides a plus or minus 500 millisecond correction range.
When the calculated system clock time and the hardware clock time differ by
500 milliseconds, RighTime advances or retards the hardware clock as needed
to keep the correction within range. This adjustment is automatic and will
not affect the DOS clock which remains correct at all times.

RighTime takes interrupt 4Ah and hooks interrupts 8h, 1Ah, 21h, 28h
and 2Fh, and it is TesSeRact compatible. Use of the features of the
hardware clock is central to the function of RighTime, so the hardware
clock is strongly guarded. While RighTime is installed, any attempt (via
interrupt 1Ah) to set the hardware clock time, date or alarm time, or to
disable the alarm, will be ignored and will produce an error indication to
the offending program. If interrupt 4Ah is taken by another program, it
will be recovered by RighTime. The program is resistant to modifications.


Command Line Syntax

RighTime [{/F|/R[addr]|/N}] [/W[[{+|-}]warm]] [/C[[{+|-}]cool]]
[/Dmm] [/Umm]

where

/F causes RighTime to store corrections in its own program file;

/R causes RighTime to store corrections in 13 CMOS RAM
locations ending in addr (default 63, see /Raddr, below);

/N disables correction storage;

/W sets starting warm correction rate in hundredthseconds per day
(default 0, maximum +32767 or -32768);

/C sets starting cool correction rate, as above;

/D changes the cool adjust period allowance (after boot) from the 10
minute default. The valid range is 1 to 60. Consider this
option if your system exhibits a large difference in warm and
cool corrections and cabinet temperature is suspect. You
should also consider that the clock rate might be affected by
the lower supply voltage when the system is off;

/U changes the CMOS RAM or file update period from the two minute
default. The valid range is 2 to 60, and the value should be
even. If you think the default is unnecessarily frequent, try
this option. Remember that this is part of the cool correction
process, and less frequency might affect correction accuracy in
severe situations;

/Raddr will place the corrections in CMOS RAM at a location other
than the default of 63; this location is that of the last of 13
bytes that are stored. This option is potentially harmful,
since a careless value might allow RighTime to overwrite setup
data; inadvertently changing a hard disk type, for example, can
lead to a sad consequence. Be careful.


Hardware Compatibility

RighTime requires a hardware real time clock that is compatible with
the stock PC/AT part, an MC146818. The Dallas Semiconductor DS1287 is one
such part. Some modern PC/AT implementations provide an embedded hardware
clock, not a separate part, that is fully compatible.

The hardware clock and CMOS RAM usability depends upon the hardware
and the BIOS:

The Tandy 1000TL hardware is not compatible.

An Award 286 BIOS in an unlabeled AT clone did not support the
alarm feature of the hardware clock and is not compatible with
RighTime.

Toshiba laptops will not allow the use of CMOS RAM but no ill
effects result from trying aside from a checksum error at the
next boot which requires only a key press to correct. Use the
disk file (/F) option.

To date, all other AMI, DTK, Oak and Phoenix BIOS ROMs have
worked well.


If You Have Trouble

Please note the symptoms and circumstances as thoroughly as is
reasonably possible and contact

Tom Becker
Air System Technologies, Inc.
14232 Marsh Lane, Suite 339
Dallas, Texas 75234 USA

Telephone: 214/402-9660
CompuServe: 76436,3210

RighTime Usage Registration Form

Fill out this form, enclose the required funds and mail to:

Air System Technologies, Inc.
14232 Marsh Lane, Suite 339
Dallas, Texas 75234 USA


I would like to register the usage of RighTime.


Name:________________________________________________________________

Business name:_______________________________________________________

Address:_____________________________________________________________

_____________________________________________________________

City:______________________________ State:_________ Zip:_____________

Telephone:_________________________


Where did you get RighTime?__________________________________________


Registered RighTime programs are serial numbered. Registration is
required for each copy of RighTime that is simultaneously machine
resident. If you have, for example, three machines on which you want
to run RighTime, please register for three machines.

Single machine registration fee is $25.
Each additional machine registration fee is $15.


How many copies of the RighTime package do you want?_________________

On what media? 5.25"/360K______ 3.25"/720K______


Total enclosed: US$____________
Make your check or money order payable to Air System Technologies.

Does your business require an invoice?____________


Thank You!