RighTime v1.1, TestTime v1.1 Copyright 1991, GTBecker
April 28, 1991 All Rights Reserved

Shareware Notice

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

Neither evaluation program will run if the program file has been
modified in any way, including filename, length and content. A
fresh distribution file of the latest version is always available
on the SBE/DFW BBS, 214/647-0670.

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

Commercial shareware distributors must make arrangements with Air
System Technologies prior to distribution of these programs.

You may use these evaluation programs for up to one month, and you may
- and are encouraged to - pass the distribution file along to others for

their evaluation, but no one may modify, rename or sell the files or programs
to anyone under any circumstances. The programs will notify you when the
evaluation period has elapsed.

This document is a complete description of the programs, including the
license that will be granted upon registration. There are no surprises. If
you have questions or suggestions, or if you need assistance, you may call
the telephone number at the end of this document any time during evaluation.

We encourage you to register your use of RighTime. Registered RighTime
users receive a diskette containing the current version of the registered
programs, a printed user manual and license agreement, notification of new
releases, and enthusiastic support from the author when needed. The
registered version of RighTime is functionally identical to the shareware
distributed evaluation version, but it lacks registration reminders, it is
smaller in size, and it is serial numbered.

Beyond the immediate tangible benefits, registration also provides
support for the shareware software distribution concept. Shareware is not
free software, nor is it in the public domain. Shareware means quality
software that you try before you buy, generally at a far lower cost than a
similar retail product, if one exists. More happy shareware users mean 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 use.

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


Version 1.1

A number of new features have been added to RighTime since the previous
version (1.0a) was released, and problems that a few users encountered and
reported have been fixed. If you tried RighTime v1.0 or v1.0a and found that
you could not use the program, try again with v1.1. Please report any
difficulties you have. Sometimes your trouble can be remedied by a single
telephone call, but if not, your information can be valuable in improving
future releases of the programs.

RighTime v1.1 includes these new features:

* DRDOS 5.0 support;

* CMOS RAM requirement decreased to 12 bytes;

* Time trim provided in hundredths of a second;

* Permanent disable, temporary disable and reenable;

* Quiet mode silences beeps in error messages;

* Four termination codes testable by batch ERRORLEVEL;

* Automatic timeset request by two criteria;

* CMOS backup battery failure detection;

* Improved TestTime accuracy;

* New command line switches /H, /O, /T, /E, /K, /S, /Q.


What is RighTime?


RIGHTIME.COM is a TSR for MSDOS v3.0 and later and DRDOS which will
correct the 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 about 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. By far, the majority of current 80286, 80386
and 80486 machines are compatible, but systems like the AT&T PC
6300, some Tandy-manufactured machines, AST Six Pack equipped PCs
and XTs, ROM-socket and floppy-connector clocks 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. Unlike
DOS alone, the hardware clock seconds transition will be properly set by
RighTime and the time will be set to hundredths of a second resolution, and
these qualities will survive through rebooting.

Each time you set the time, RighTime will improve the accuracy of the
clock error 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 much better. Command line options are provided that
allow fine tuning the correction process to your system. A trimming option
provides for offset adjustments in hundredths of a second.

An option is provided that assists in automatic timesetting by allowing
RighTime to notify the AUTOEXEC batch file when a specified number of days
has elapsed since the last timeset, or if the system has been inactive for
too long and requires a timeset.

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 usually 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.


If You Are In a Big Hurry, or If You Don't Read Manuals

You can't know how to take best advantage of a new product unless you
take the time to read the instructions, but if you insist on trying RighTime
before you understand what you're trying, here's a helping hand:

1) Make a new directory, for example:
MD \RT

2) Copy RIGHTIME.COM, TESTTIME.COM and RIGHTIME.TXT into the new
directory.

3) Set the date, if necessary.

4) Run from a DOS prompt:
\RT\RighTime /F /W /C

5) Set the system time very accurately with DOS's TIME command or,
far better, with a telephone timesetting program.

6) Add this command to your AUTOEXEC.BAT:
\RT\RighTime /F

7) Reboot.

8) For a few days, set the time accurately immediately before you
shutdown your system for the night, and immediately after booting
in the morning. If you never shutdown your system, set the time
accurately a few times each day.

9) There are other considerations, and there might be additional
features that are useful to you, so read the rest of this
document, perhaps twice.


Getting Started

To use RighTime, first decide where to store the corrections. There
are three options: disk file, unused CMOS RAM, or neither. In general, try
the disk file option first, if you can. If you have a hard disk, you can use
the disk file or probably the CMOS RAM option. If you have only floppies the
disk file option is impractical, so try the CMOS RAM option. A diskless
machine cannot use the disk option, unless it is equipped with a non-volatile
RAM disk which appears to the system as any other disk would.

The CMOS RAM option involves some initial bravado: although only the
first 52 bytes of CMOS RAM are defined by the IBM PC standard (presumably
leaving the last 12 bytes available), some modern BIOSs use these 12 bytes
for other functions. If you have adopted a user-specified hard disk format,
for example, your specification is probably stored there. 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 if you can.

If you choose the disk file option, RighTime will attempt to write to
its own program file from time to time, so write access must be allowed. If
the "disk" is actually a non-volatile RAM disk card, the card must remain in
the machine if this option is to work properly. If you use the disk file
option on a battery powered hard disk laptop, you might want to decrease the
update frequency to allow your hard disk to spin down after periods of
inactivity to increase the battery life (see the /U option, Command Line
Syntax, below). The disk file option causes RighTime to maintain an open
handle to its program file which might present a problem when running a file
defragmenting utility, but RighTime can be disabled during defragmentation
and restarted afterwards (see the /K option, Killing, Disabling and
Reenabling Resident RighTime, below).

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, you can
suggest it also. If you don't know one or either correction, RighTime will
determine them anyway; it'll just take a little longer for the corrections to
mature to good accuracy.

If you need to restart RighTime and it is currently resident and
running, you must first kill the resident program (see Disabling and
Reenabling Resident RighTime, below). If appropriate, the corrections that
RighTime has already learned can be suggested to the new program copy.

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 choose the CMOS RAM option,

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

if you choose the disk file option,

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

As discussed above, the /W and /C switches are required, but the warm
and cool parameters are optional in this first execution.

Also, in your AUTOEXEC.BAT file, add:

if you choose the CMOS RAM option,

dev:\path\RighTime /R

if you choose the disk file option,

dev:\path\RighTime /F

Do not use the /W or /C switches in the AUTOEXEC.BAT invocation; if you
do, you will defeat the learning process. Use the /W and/or /C switches only
when starting - or restarting - the error correction learning process of
RighTime; normally this needs to be done only once, the very first time you
run RighTime from the DOS prompt. If you use other options to modify the
behavior of RighTime, these options must be included in the AUTOEXEC.BAT
invocation, and should be included in the initial DOS prompt invocation.

RighTime cannot be INSTALLed in the CONFIG.SYS file.

In the examples above and in those that follow, substitute your
appropriate device specification and the program file path.

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, a
copyright notice, and an "Installed" message.


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 (register with him, too).
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. You will find that the clocks will become more and more accurate
and the need for adjustment will decrease, becoming infrequent; however, you
must set the time accurately at least once per month (an option is provided
to assist in automating this - see Errorlevels, below).

Allow sufficient time to elapse between time sets so that enough error
exists for RighTime to use in its correction calculations; the more time that
you allow, the better the correction factors that are determined. Time sets
that are separated by less than 30 minutes will be disregarded. Careless
timesets will result in poor correction or even wild clock behavior; remember
that you are "training" the program, so do it well. If you are eager, four
hours will probably be an adequate initial wait; of course, you can use your
system as you normally would during this time.

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 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 (see Error Messages, below).

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 RighTime will advise you of
its difficulty if it can. 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 (or automatically; see Errorlevels, below). The subsequent
adjustment will not affect the corrections.

Keep in mind that the date is the most significant part of the time.
If you change only the date, you are in fact making a very large change in
the time. The change will not affect the corrections due to its large size,
but it will very likely change the seconds synchronization, and that, in
turn, will create additional error at the next time set. A solution to this
problem is to set the time twice after you change the date; first,
deliberately set the time an hour off, and then set the time accurately.
Neither of these two timesets will affect the corrections due to their size.


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 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.


Killing, Disabling and Reenabling Resident RighTime

Earlier versions of RighTime (which were running with the disk file
option) reportedly could cause occasional loss of data or system lockups
during high-speed communication sessions. If you encounter similar
difficulties with RighTime v1.1, you can temporarily suspend the function of
RighTime and reenable it later. The disabling and reenabling command lines
can be placed in a batch file surrounding the invocation of the offended
program. RighTime should not be disabled for an extended period.


In the Software Carousel environment, RighTime seemed to interfere with
the automatic partition starting process of the task switcher. This problem
was cured by installing and then immediately disabling RighTime in
AUTOEXEC.BAT, then reenabling RighTime when the last partition was started.

Once RighTime is resident, it can be disabled by running at a DOS
prompt:

dev:\path\RighTime /T

Resident RighTime can then be reenabled by running:

dev:\path\RighTime /E

Programs that defragment or reorganize the hard disk should always be
run with no open files. When using RighTime's disk file option, an open
handle is maintained to the program file, so before running a disk
reorganizing utility, RighTime should be killed. After the utility
completes, RighTime can be restarted with the same command line used in the
AUTOEXEC.BAT file. This precaution is not required when using the CMOS RAM
option.

RighTime can be irreversibly disabled (or "killed") by running:

dev:\path\RighTime /K

The /K switch will cause the function of RighTime to terminate, but the
memory that was allocated to RighTime will remain allocated and unavailable.
If you wish, another copy of RighTime can be started with different options.
In that case, a memory map will indicate multiple RighTime allocations, but
only one will be active.

If it is your intent to permanently remove RighTime from your system,
you can do so by killing the resident program and removing the RighTime
invocation in your AUTOEXEC.BAT. Rebooting is not immediately necessary.


Errorlevels

RighTime provides four unique termination codes. The termination code
can be tested in a batch file to guide subsequent operations.

Code value Indication

0 Installed normally, cool correction within range, last
timeset within specified elapsed period.

1 Installed, cool correction within range, but more than
the specified period has elapsed since a timeset.

2 Installed, but cool correction was out of range (the
system has been inactive too long), so a timeset is
externally required.

255 Not installed due to syntax error, insufficient memory,
incompatible hardware, etc.

These codes can be tested in the AUTOEXEC batch file with the
ERRORLEVEL batch command. For example, if the termination code is 1, then
more than 28 days have elapsed since the last timeset (this duration can be
changed with the /S option). It would be wise to have a NIST telephone
service time setting program such as Professional TimeSet v6.0 automatically
set the time in this situation to prevent RighTime from exceeding its one
month limit, or you could cause execution of the system DATE and TIME
commands to urge the user to set them manually.


Error Messages

RighTime might report one of the following messages:

"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 8086, 8088, 80186, 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.

"System skipped a hardware clock alarm"
RighTime has not passed a self test, but this condition can
occasionally occur normally. 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.

"Program has been altered"
RIGHTIME.COM or TESTTIME.COM has been modified in some way. This
message might indicate the presence of a software virus in your system.
Immediately delete the program from your system and replace it with the
distributed program. If the original distributed copy displays this
message, notify the author. This message will also result from an
attempt to INSTALL RighTime in the CONFIG.SYS file.

"Enable resident RighTime first"
RighTime has been disabled with the /T switch. Reenable the program
with the /E switch.

"Hardware clock indicates low or no battery"
The hardware clock and CMOS RAM are powered by a battery during periods
when the system is turned off. Replace the battery or batteries or
replace the clock module if the battery is self-contained.

"Calculated correction is too large"
RighTime has determined that a single adjustment of more than about 5.5
minutes is required. The time must be set manually or via a subsequent
program that can be invoked within AUTOEXEC.BAT by testing the
termination code with ERRORLEVEL.


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. That is never
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

Frequently 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. Since few application
programs - nor MSDOS itself - consider resolution loss, it is precompensated
by default; DRDOS 5.0, however, includes resolution loss compensation.
RighTime's /H0 option should be used on DRDOS systems.


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 being applied to the DOS
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 moving average 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, which is indicated by a diff value of zero. 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. If RighTime is doing its job, you should
see that corr and diff are essentially the same value - the former is the
cause, and the latter is the effect.

If the corr and diff values differ by some small, fixed amount, you can
trim RighTime with the /O option to achieve better accuracy. One way to
determine the proper trimming offset is by starting RighTime with a /W0
switch, then running TestTime. Making certain that the corr value is zero
(it should be, since you started RighTime with /W0), let TestTime run 100
seconds or more; the approxima will be replaced by an equal sign or one-half
sign. If the diff value is then not zero, use its complement value as the
trimming offset with the RighTime /O switch. For example, if the difference
is -00.02 second, the proper offset trim should be +2 hundredthseconds, so
the proper RighTime option expression would be /O+2.

Since TestTime measures the difference between the two clocks with a
moving average, the diff value will lag the corr value. For warm correction
values of 864 hundredthseconds per day or smaller this presents no problem,
but for larger daily correction values the current corr value will change
within the 100 second window of TestTime. TestTime will never "catch up"
with the correction, so the indicated diff value will be somewhat low under
these conditions.


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

If you use other options to modify the behavior of RighTime, the
options (except options /W and /C) must be included in the AUTOEXEC.BAT
invocation, and should be included in the initial DOS prompt invocation.
Options /W and /C must be specified in the initial DOS prompt invocation and
must not be specified in the AUTOEXEC.BAT invocation. The options are not
case-sensitive (either /f or /F will work) and space between options is not
required. There must be no space between an option switch and its related
parameter.

RighTime [ [{/F | /R[addr] | /N}] [/W[[{+|-}]warm]] [/C[[{+|-}]cool]]
[/Dmin] [/Umin] [/H[{0|1}]] [/O[{+|-}]trim] [/Sn] [/Q] |
[{/K | /T | /E}] ]

where:

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

/R causes RighTime to store corrections in CMOS RAM;

/Raddr causes RighTime to store corrections in CMOS RAM at a specific
location other than the default address of 63. This location is
that of the last of 12 bytes. 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 sadness. Be careful;

/N disables correction storage;

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

/C sets initial 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 lower
supply voltage when the system is off;

/U changes the CMOS RAM or disk 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;

/H sets positive half-tick compensation on (1) or off (0). The
default is on (1) for MSDOS systems. Off (0) should be used on
a DRDOS-equipped system, which includes its own compensation;

/O allows DOS clock offset trim in hundredthseconds. Default is 0; the
valid range is -99 to +99. This can be used to compensate for
fixed system overhead in the operating system, or to anticipate
relay and contactor actuation delays and motor start times in
process control system applications;

/T temporarily disables RighTime function;

/E reenables RighTime function;

/K irreversibly disables (kills) RighTime function. The memory that is
occupied by RighTime remains allocated and unavailable;

/S causes RighTime to set the program termination code, which can
be tested with ERRORLEVEL in the AUTOEXEC batch file if the
duration since the last timeset exceeds n days. The default is
28 days;

/Q will mute any error message beeps.


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.

* The Tandy 3000 and an unlabeled AT clone with an Award 286 BIOS
do not support the alarm feature of the hardware clock and are
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
SBEDFW BBS: 214/647-0670
Fidonet: 1:124/1213.0
CompuServe: 76436,3210

Software License Agreement

When you register, this will be the agreement between you (the user)
and Air System Technologies to which both parties are bound upon the payment
and acceptance of the license fee, which is part of the registration fee.

Grant of License
In consideration of the payment of each license fee by the user to Air
System Technologies, Air System Technologies will license to the user a
nonexclusive right to use one copy of each of the software programs (RighTime
and TestTime) on one computer at a time. The license is expressly for
program use only, per the terms of the license. No other rights are implied.

Ownership of Software
Air System Technologies is the owner of the software programs and holds
full title to them. The user may own the physical media on which the
software programs are recorded, including the original disk which is provided
by Air System Technologies to the user, but the user does not own the
software programs nor any copy of the software programs.

Copies
The software programs and the documentation are copyrighted and
therefore may not be copied without permission. Permission is granted to the
licensed user to make copies of the software programs and the documentation
as required in the conventional course of computer system data backup.
Permission is granted to copy the shareware distribution file in its
complete, unmodified form. No other permission to copy is granted.

Use and Transfer
The Grant of License applies only to one copy of each of the software
programs. Simultaneously functional resident copies of the software programs
each require licensing. You may not transfer any copy (except the shareware
distribution file) of the software programs to a computer which is not under
your control, nor may you rent, lease, sell or otherwise assign control of
the software programs to anyone.

Termination
The license is in effect until it is terminated. When the license is
terminated, the user's rights that are granted by the license are revoked.
The license is automatically terminated upon violation of any of its terms,
without notice.

Disclaimer of Warranty
No warranty of performance or suitability is expressed or implied.
Every effort has been made to make the software programs deliver as the
documentation describes, but the correctness for your application or
environment cannot be assured. Air System Technologies cannot assume
responsibility for the failure of the software programs, nor for any
consequence of their use.


RighTime Usage Registration Form Evaluation version 1.1

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 use 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 $20.


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!