^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^ ^
^ AGRCLK.COM ^
^ ^
^ version 1.1 ^
^ copyright (c) 1989 ^
^ by Wayne Brink ^
^ ^
^ All rights reserved. ^
^ ^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

GENERAL
You may print these instructions by typing "COPY AGRCLK11.DOC LPT1" and
pressing ENTER. If your printer is not connected to LPT1, type the
appropriate printer connection.

This is a simple to operate memory resident on-screen clock which gener-
ates an audible signal at given intervals--one hour on this version. The
color and location are selectable. In graphics programs, the clock will
still be displayed, though the color may be different than the text clock
color.

QUICK START
You can read this whole set of instructions first, or you can just dive
right in. If you want to dive, here's a quick guide:

With the disk containing AGRCLK11.COM in place, type AGRCLK11 /c1 if you
have a CGA graphics display, or AGRCLK /c12 if you use an EGA or VGA
display and hit ENTER. Default parameters will set up the rest of the
clock.

NOTE: YOU MUST SELECT A COLOR SETTING IF YOU ARE GOING TO USE THE CLOCK
IN A GRAPHICS PROGRAM, or else the clock will be black on black!

If you want to get a little fancier, use the parameters when installing
the clock. The parameters are:
/cx -- Choose the clock's color; x is any positive integer.
/lx -- Choose the clock's location; x is l(eft), c(enter), r(ight).
/px -- Choose the audible signal pitch; x is l(ow), or h(igh).
/dx -- Choose the delay (length) of the audible signal; x is 0-9.
/s -- Show all the options, without loading the clock.
For example, to place the clock in the upper left corner of the
screen, and use a low pitch for the tone, type:
AGRCLK11 /ll /pl
and press ENTER.

Once the clock is loaded, there are three hot-key combinations:
CONTROL-RIGHT SHIFT will allow you to change the clock color.
CONTROL-ALT toggles the clock display off and on.
ALT-RIGHT SHIFT changes the location of the clock.

Be aware that when entering the graphics modes, the clock will not be
displayed immediately. However, it should show up within one minute.

CHANGES FROM VERSION 1.0
* Simplified method of selecting the clock color from the command line.
* The graphics clock color is now selectable from both the command line
and with the hot key.
* The location of the clock, both text and graphics, is now selectable
with the hot key.
* The graphics clock is located just slightly higher, on the very top
line of the screen.

A FEW THINGS TO NOTE
This clock was specifically designed to work with the Prodigy Service, how-
ever, it should work with most text and graphics applications. Although
it has not been tested with all computers' text and graphics modes, I be-
lieve that it will function as described with monochrome, Hercules, CGA HI,
CGA LO, PCjr and Tandy 16-color, EGA and VGA modes. It has been tested on
Tandy 1000SX, and IBM PS/2 with VGA with no problems. Naturally, don't ex-
pect the color functions to work on monochrome screens and modes, and the
graphics clock will not function if you haven't got graphics capability. On
older CGA modes, you may experience "snow" when the clock is refreshed. If
this is a problem, send $5.00 for a compatible version of the program.

Note that when the computer is in graphics mode, as with Prodigy, parts of
the clock may be overwritten by changes in the Prodigy screens. At times,
the entire clock disappears. Due to the time involved in checking to see if
the clock needs to be refreshed and actually refreshing the clock, it is
actually refreshed only once a minute (whether it needs it or not!) when it
would "flip" over to a new minute. I don't feel that this is a serious
problem--most of the time, the clock is on-screen, ready to go, and on the
occasions when the clock is not there, when you look back up, it probably
will be back, too. If you feel that it is a problem, let me know, and I'll
see about creating a version that refreshes more frequently. However, in
graphics programs that change the screen very frequently, not only may the
the clock be unable to keep up, but it may actually slow down the system if
it tried to.

INSTALLING and RUNNING
In its simplest form, simply type AGRCLK11, and the clock will install it-
self. However, there are a number of features which you may wish to use.
The following discussion explains the clock in greater detail.

The on-screen clock is a digital clock that indicates AM or PM in text mode
only, graphics displays are twelve hour time only.

The audible signal is a two-tone signal that occurs on the hour. (A ver-
sion is available with selectable time intervals of 5, 15, 30 or 60 min-
utes. However, with the clock visible on all screens, I've decided to save
space and keep the program simple by eliminating that feature here.)

All the selections are entered as parameters following the AGRCLK command:

AGRCLK11 [/cx] [/lx] [/px] [/dx] [/s]

where
/cx, /lx, /px, /dx, /s
are all optional, may be entered in any order, must be separated by a
space, and must be entered in lower case. The options for each para-
meter are:

/cx = a TEXT color combination, x being a up to 3 characters
based on the following:
0 = black 8 = darkgray
1 = darkblue 9 = lightblue
2 = darkgreen 10 = lightgreen
3 = cyan 11 = lightcyan
4 = red 12 = lightred
5 = magenta 13 = lightmagenta
6 = brown 14 = yellow
7 = lightgray 15 = white
If x is '1', the clock will be darkblue on black, if '2', it
will be darkgreen on black, etc. Additional colors can be
attained by using multiples and additions, e.g. '16' is
black on darkblue, '17' is darkblue on darkblue (not a good
choice!), '32' is black on darkgreen, etc. You will observe
that multiplying the colors 0 through 7 by 16 creates the
background color. Add to that the number of the foreground
color you want, and that is your value for x. Those of you
who are familiar with this type of system should be fore-
warned that you cannot get blinking colors. The colors are
all mod 128.
To get yellow on red, for example, multiply red's number
(4) by 16, and add 14: 4 * 16 = 64 + 14 = 78.

Graphics colors:
0 = black on black, 1 = red on black,
2 = gray/black, 3 = blue/black,
4 = white/black, 5 = brown/black,
6 = green/black, 7 = white/black,
8 = blue/black, 9 = magenta/black,
10 = lightmagenta/black, 11 = lightred/black,
12 = yellow/black, 13 = light green/black,
14 = lightcyan/black, 15 = cyan/black.
(Tandy 16-color video card.)
The colors in graphics mode are x modulo the colors availa-
ble in that graphics mode. That is, if you have four colors
available, if you select color 9, that is 9 modulo 4 = 1
(9/4 = 2, remainder 1). All graphics clock colors are on a
black background.

These colors are for CGA monitors; EGA and VGA are likely to be the same,
but I have not tested them to be sure.

If you are working in monochrome, probably color '1' is your best choice.

/lx = the location where you wish the clock to be displayed.
x may be any of the following:
l is left corner,
c is centered,
r is right corner (default).
Note that in some graphics modes, selecting the right corner may actually
place the clock closer to the center than you would expect. This is be-
cause the "distance" to the right side of the screen varies in some modes.

/px = the pitch of the tones. x can be:
h is high (default),
l is low.

/dx = the duration of the signal. Use it to adjust the signal to
match the CPU you are using. x may be:
0--shortest duration, appropriate for slow CPUs.
1.
2.
3--default. Signal lasts about 1/8 second on 8Mhz CPUs.
4.
...
9--longest duration, appropriate for very fast CPUs.
These values (if you add one to them) are simple multiples;
A value of 9 means the signal lasts 10 times longer than one
of 0.

/s = show options. List these parameter options on-screen.
Choosing this option exits the program without installing the
clock. If you choose any other options with this, they will
be ignored.

This program chooses selections for you if you enter incorrect values for
the parameter options, e.g. /pg is the same as /pl. However, if you enter
an incorrect parameter, previous parameters may be affected, e.g.
/lc /lp will reset the location to some program defined position.
Invalid parameters are ignored.

HOT-KEY OPTIONS for clock color and display on/off
To use these options, do the following:
Press CTRL and the RIGHT SHIFT key to change the clock color.
A text line will appear asking you to enter your ONE character color
choice if you are in text mode. Enter a single character or an
ALT KEYPAD code. The clock will not (usually) immediately change
color, however the next time the clock must be freshed--when the time
changes, when the screen is scrolled up, or when the screen is
cleared--it will change color. The color you get will correspond to
the ASCII code for the character you enter, or the ALT code you
enter. For example, blue on black is color number 1. Press
ALT-(numpad)1. Or black on red is color number 64. Press
ALT-(numpad)64 or just 'a'. See the command line section on how to
determine the color number selection. When you choose this option in
graphics, no text line will be displayed, instead you will get a
scrambled line one pixel high. This is your only cue to enter the
new color character. Whether in text or graphics, once you enter the
character, the line will disappear, with the original text or
graphics taking its place.

Press CONTROL and ALT to toggle the display off or on.
This is useful when the clock either is obscuring something you must
see or if the screen will be scrolling DOWN, in which case the
clock will also scroll down. It also can be useful with programs
that print the screen or use screen data so you won't include the
clock in the printout or data. Be aware, however, that the clock
will not immediately disappear when toggled off. It will, however,
when the screen is scrolled up, cleared, completely replaced or when
the clock's area of the screen is changed.

When in text mode, if the clock is toggled on, it will immediately
appear.
In graphics mode, the clock will appear on the next occurrence that
the clock has to be updated--within 59 seconds.

Press ALT and RIGHT SHIFT to change the clock's location.
Each time this combination is pressed, the clock will move right by
one position. If it is on the left side of the screen, it will move
to the right side of the screen. The clock's new position will not
show up until the next time the clock is refreshed. The old posi-
tion will maintain the clock (in frozen time) until that area of the
screen is modified by the system or main program.

HINTS AND OTHER NOTES
This version of AGRCLKxx.COM has been tested on the TANDY 1000SX, IBM
compatible CGA modes, and IBM PS/2 Model 50z, VGA mode. It should work
with either monochrome or color monitors--Hercules, CGA, EGA, VGA,
although it apparently does not work in Hercules graphics. However,
be aware of the following:

The clock is displayed by accessing screen memory directly. Oth-
er programs that access memory may cause duplicates of the time
to appear either on-screen or in the other program's data. My own
experience has shown the former to happen rarely, and the latter
has not occurred.

Occasionally, the hour may be obscured by other screen displays. It
is less likely to occur on the right side of the screen, where less
information is likely to be placed. It is most likely to happen
in cases where the entire screen is given over to data, as in DOS.
A program that creates a window for you and thereafter doesn't do
anything in that area of the screen will have no problem.

Other programs that read and write directly to and from the screen,
such as Prodigy, will occassionally write over the clock. The clock
will reappear on the next minute. Prodigy also "overlays" the
screen occasionally, especially with its "WORKING" signal. When it
does this, it saves the data underneath and restores it. This is not
a particular problem itself, but what may happen is that the clock
could write to the "WORKING" window, and when the window disappears,
the old, now incorrect time will be displayed. The alternative is
to place the clock in the left corner or in the center. The center
is probably the worst place in Prodigy, because it is very frequent-
ly being overwritten. The left side is less often completely over-
written, but even this area is not completely safe. Nonetheless,
one of these three locations on the top line are the least likely
spots to be overwritten.

The audible signals and graphics numerals require a short period to
complete. The computer is controlled by the clock program during
that time. Keystrokes and data transfers, etc. will be delayed.
When downloading files via a modem, you may notice a retransmission
request when the tone sounds. Usually, this is no problem.

Some computer operations will be suspended when you choose the CON-
TROL-RIGHT SHIFT option to change the clock's color. I have tested
it under a number of conditions--while doing disk operations, there
appears to be no problems. While compiling programs using Turbo C,
the compilation was suspended until the color was selected. Compil-
ation then continued successfully. The time-for-this-call feature
within ProComm (c) was suspended until the color was selected, at
which time it correctly updated itself. To be safe during critical
operations, you should probably not change the clock color; instead,
wait until no other operations are taking place, and all files have
been saved.

This program is in my AUTOEXEC.BAT file, and is the first TSR I load. I
have not observed any conflicts with other memory resident programs
(most notably mouse drivers, Sidekick and DesqView).

DISCLAIMER, REGISTRATION, ETC.
*********************************
* UNDER NO CIRCUMSTANCES WILL I *
* BE LIABLE FOR ANY DAMAGE OR *
* LOSSES, DIRECT OR INDIRECT, *
* RESULTING FROM THE USE OF *
* THIS PROGRAM. NO WARRANTIES, *
* EXPRESSED OR IMPLIED ARE IN- *
* CLUDED WITH THIS PROGRAM. *
*********************************

Test this program before using it. If it interferes in any way with your
own programs, I recommend you do not use it.

If you feel that this program is useful and would like to be included in
notifications of further upgrades, send a registration fee of $5.00 to
me. Registered owners are eligible for debugging for 30 days from the
date of registration. Debugging is limited to program errors. Incom-
patibility problems are not covered, except at my discretion. Customiz-
ing is described below.

This program may be copied as frequently as you wish and given to your
friends, relatives, work associates, etc. When copying the program,
include this documentation file--I request copying and forwarding the
original AGRCLKxx.ZIP file.

If you would like to have a customized version of this program,
for example, one that plays particular notes, send me $5.00 and a post-
age-paid disk (5.25 double density or 3.5, double density or high den-
sity) with a description of your needs. Please be specific, and if you
wish a particular tune, please include the actual notes to be played.
Unusually difficult customizations may require an additional charge. You
will be automatically registered for upgrades.

For comments, upgrades:
Wayne Brink
QCC
670 West Boylston St.
Worcester, MA 01606

Prodigy Address: PSKH44A

TRADEMARKS
Turbo C is a registered trademark of Borland International.
ProComm is copyrighted by DataStorm Technologies.
CGA, PCjr, IBM are registerd by International Business Machines Corporation.
Prodigy is a registered trademark of IBM and Sears.
Tandy 1000 is a registered trademark of Tandy Corporation.