SIDECLOK - SIDEKICK Alarm Clock Utility
---------------------------------------

This program is a real time CLOCK program and an alarm utility which
works with the SIDEKICK CALENDAR function. Specifically, the program
performs the following functions:

1. Displays a realtime clock, in reverse video, in the upper right
hand corner of the monochrome display. The display is updated every
second.

2. Interrogates the SIDEKICK CALENDAR file and builds an internal alarm
table of times and the associated messages. Five (5) minutes before
the specified time (i.e. at 8:55 for a 9:00 entry) a 10 second alarm
will sound and the message from the CALENDAR file associated with
the specified time will flash in the upper left hand corner of the
screen.

There are several commands which can be entered on the command line when
SIDECLOK is evoked:

1. FILE command. This command tells SIDECLOK the path and filename of
the file which is used by the SIDEKICK CALENDAR function. The default
name for this file is 'd:\calndr' so this command must be issued
if a different file name or drive specification is used by your
SIDEKICK. This command normally will need be issued only once
(at boot-up) since SIDECLOK will 'remember' the new default until it
is changed -or- until the system is rebooted. The format of the
FILE command is:

f=b:calndr.sk
f=d:\sk\calndr.fle

'f=' is the required keyword identifier and the rest of the
command specifies the drive/path/filename.ext for the SIDEKICK
CALENDAR file.

2. DISPLAY command. This command tells SIDECLOK to turn the on screen
clock display 'off' or 'on'. A '-' turns the display OFF; SIDECLOK
is still ticking and the alarm function will still work, but the
on screen clock display is suppressed. A '+' will turn the display
ON. The format of the DISPLAY command is:

d=-
d=+

'd=' is the required keywork identifier and the rest of the command
specifies the off or on condition.


3. ALARM command. This command will enter a manual alarm into the
SIDECLOK alarm table. The alarm will sound at exactly the time
specified in the ALARM command rather than 5 minutes before as is
the case with the CALENDAR file alarms. The format of the ALARM
command is:

a=10:20
a=10
a=14:13

'a=' is the required keyword identifier and the rest of the command
specifies the alarm time. The alarm command will accept time in
a military format with hours and minutes only. The format of the
time specified must be hh:mm. Seconds are not allowed and will be
ignored if entered.

4. MESSAGE command. This command will associate a message to be displayed
on the CRT with an ALARM time. In order to display the message,
the ALARM command must specify an ALARM time on the same command
line. The format of the MESSAGE command is:

a=10:20,m=This is a manual message
m=Meeting with George,a=10

'm=' is the required keyword identifier and the rest of the command
specifies the message to be displayed at the associate alarm time.
A message length of up to 27 characters is accepted.

Any one, none or all of these commands can be entered on the command line.
In addition, SIDECLOK commands may be specified in upper or lower case.
Commands must be separated by commas with no intervening spaces. For
example:

A>sideclok f=b:calndr,d=-
A>sideclok F=d:\sk\calndr
A>sideclok d=+,f=b:cal.sk
A>SIDECLOK A=15:20,M=HAIRCUT,D=-
A>sideclok f=b:calndr.skf,a=12:00,m=LUNCH
A>sideclok

are all valid command lines. The following examples will cause errors:

A>sideclok f = b:cal.sk
A>sideclok f=b:cal.sk d=-
A>sideclok a:10:20,m:This is WRONG!

The following miscellaneous notes may answer some questions about the
way the SIDECLOK utility works..

1. If the SIDEKICK CALENDAR file name is different from the default,
you should issue the FILE command at boot up. The best idea is to
place this command in your AUTOEXEC.BAT file.

2. The alarm function will flash the CALENDAR file message in the left
hand corner of the screen and sound the PC alarm 10 times. After the
alarm sound goes off, the message will remain on the screen so that
if you are away from your PC at the time of the alarm, you will still
get the message. The flashing message will be removed whenever the
screen is refreshed by whatever program is active in the PC.

3. The alarm utility function should work with any program (including
the COURIER 3270 emulation program) except those that disable the
timer interrupt. Ironically, SIDEKICK is one which does disable the
timer interrupt. See NOTE 8 below for additional details.

4. If a non existant file name is specified in the FILE command, SIDECLOK
will issue and I/O error and terminate. The clock display will continue
to work properly, but the alarm function will not work.

5. If a new 'entry' is added to the SIDEKICK CALENDAR file during the
course of the day, SIDECLOK must be executed in order to insert the
new entry(s) into the internal alarm table. Simply execute SIDECLOK
(no commands are necessary) to re-initialize the alarm table. If you
DO NOT execute SIDECLOK after inserting new entries in today's
CALENDAR, the alarm will not be activated for those new entries.

6. Turning the clock display off or on (with the DISPLAY command) has no
effect on the alarm function. The alarm will still sound at the
appropriate times during the day if there are CALENDAR entries active.

7. If your computer is left 'on' overnite, SIDECLOK should be executed
(at some time) at the beginning of the next day OR the alarm table
values for the previous day will still be active (and will sound 5 min
before the CALENDAR time).

8. If you are performing a function which disables the timer interrupt
(SIDEKICK for example) the clock display will not appear on the
screen (which is a hint that the timer interrupt has been intercepted).
In this case, the alarm function will not function either but.. when
the timer interrupt is restored, any pending alarms will immediately
be activated. You will get the alarm late, but it will not be lost.

9. Any CALENDAR file entry which begins with a period (.) will be ignored
by the alarm table initialization routine. This allows you to enter
a 'comment' in a CALENDAR file slot without sounding an unwanted
alarm.

10. Any 'manual' alarms in the alarm table are retained with each new
execution of SIDECLOK..IF the alarm time is greater than the current
time. This allows multiple 'manual' alarms to be entered (either
thru the keyboard -or- in a batch file) AND insures that a new
manual alarm entry during the day doesn't wipe out alarms entered
earlier.