ALARM.CDA DOCUMENTATION Version 3.2
June, 1989

(c) Copyright 1988, MaineFrame Software
All Rights Reserved

INTRODUCTION
Alarm.Clock is intended to provide you with reminders of
appointments, commitments, etc., as well as protect your
monitor by blanking it during periods of inactivity.

Alarm.Clock was intended to be a "weekend project," since
the operation concept is so simple:  Install an interrupt
and check the time every so often to see if an alarm event
is pending or if the machine has been inactive.  Simple
concept, yes; simple execution, NO!

I've invested more time developing this "simple" CDA than
I've spent on much larger projects.  Basically, the
complications stem from compatibility problems with the wide
variety of programs available for the IIGS.  Not all
conditions can be sensed by Alarm.Clock (e.g. is this a
modem communications program, or not?).  Therefore, you, the
user will have to modify the environment in which
Alarm.Clock works in order to avoid problems.  But don't
worry; most applications run just fine with Alarm.Clock
active.

The Alarm.Clock package contains the following files:
   1.  ALARM.CDA -- The program itself.
   2.  INSTALL.ALARM -- does the "housekeeping" in your
       */System/Desk.Accs  folder.  (Note:  "*" is the
       wildcard denoting your boot volume.)
   3.  ALARM.LAUNCHER -- a DeskTop program that creates
       launchers for those applications that don't run
       properly with certain features of Alarm.Clock active.
   4.  ALARM.TEMPLATE -- the model file used by
       Alarm.Launcher.
   5.  READ.ME.TXT -- this file.

INSTALLING ALARM.CDA
If you run Install.Alarm, the process of copying Alarm.CDA
to the System/Desk.Accs subdirectory of your boot disk is
automated for you.  You will probably want to put Alarm.CDA
on any disk that you boot regularly.

OPERATING ALARM.CDA
The actual operation of the CDA is very simple.  Just call
up the desk accessory from the CDA menu by pressing
Open-Apple Control Escape, highlighting the Alarm Clock &
Screen Save title with the up/down arrows, and pressing
return.  To set an alarm, position the cursor in the time
position of any of the seven event lines and enter the time
in either 12 or 24 hour format.  The entry routine is very
forgiving.  Any four digit number under 2400 will be
interpreted as a military format time (e.g. 0600 hrs) and
you don't have to add the "hrs."  One or two digit numbers
separated by a non-numeric character and followed by "a" or
"p" will be read in 12 hour format.  Examples:  3-9a enters
3:09 AM; 12x23p enters 12:23 PM; 4 4p enters 4:04 PM.  1234
enters 1234 hrs.  1234p returns an error buzzer, as does
11:15 (no "a" or "p").

There is also a field to enter a short note as to the reason
for the alarm.  Standard editing commands, including
control-Y (delete to end of line), open-apple-E (toggle
overwrite/insert mode), and delete (remove character to left
of cursor) all work.  Tab will take you to the next field,
as will Return.  Open-apple tab will take you back a field,
as will option-tab or shift-tab.  Control-X (or clear) will
wipe out both the time and note fields of the event.

Three alarm options are offered:  OFF ignores any alarms
posted.  DISPLAY brings up the Alarm.Clock screen when an
alarm occurs.  BORDER FLASH will just flash the borders when
an alarm happens, and beep (which will stop after a minute
or so).  This last option is intended to allow time-critical
programs, such as modem communications applications, to run
on undisturbed while the alarm is active.  Open-Apple O
(letter O) toggles these options.

To turn off the alarm, hit any key, or move the mouse.

The screen blanking works differently depending on the
program running.  If it's a text application, the screen
border and character background/foreground will be set to
black and the application allowed to run in the background.
Any keypress or movement of the mouse will bring back the
screen in its current state (not necessarily the way it was
when the screen went black).  Since the keypress is passed
through to the application, sometimes with unintended
results, it's a good idea to develop the habit of pressing a
non-action key, such as the open-apple, option, or control
key.  If a graphics application is being blanked, the screen
is blacked and Alarm.Clock waits for a keypress or mouse
movement.  This is because some programs have problems with
the display being switched in and out.

Several blanking intervals are offered:  One, five, ten and
fifteen minutes, and infinite, which disables the blanking
feature.

To blank the screen immediately, press the Option and
Open-Apple keys at the same time, and hold them for a second
or two.

A save feature is included which works under ProDOS-8,
ProDOS-16 or GS/OS.  This will preserve the current settings
and allow you to have permanent daily reminders of important
events, examples of which I've included on the screen.  The
boot disk must be on line in order to save data; if it
isn't, you'll be so informed.

To remove events, such as my examples, press "clear" on the
keypad section on the right side of your keyboard with the
cursor anywhere on the event you want to delete.

USING THE ALARM.LAUNCHER
As mentioned, some programs have problems with interrupts
and screen switching activities.  When you run across one of
these, try to determine whether the problem is with the
alarm only (usually the case), or with both alarm and
blanking.  If the alarm alone is the problem, see if setting
the alarm to Border Flash fixes the situation.  Once you've
determined the conditions under which your program will run
properly, run Alarm.Launcher from JumpStart, the Finder, or
any other suitable launching program.

You'll first be asked to select the blanking and alarm
options you want to have set when your program runs.   These
are the conditions that Alarm.Clock will be set to before
your program runs.  If you go to the CDA after your program
starts and change these settings, all bets are off.

Next, you'll see a window asking you to specify the name for
your launching program.  Consult your IIGS documentation if
you don't know how to interact with such a dialog box.

Finally, you'll be asked to specify the program you want to
run, using a similar dialog box.  The rest is automatic.

What you'll now have is a program to launch your program.
Instead of selecting YOUR.PROGRAM from JumpStart or Finder,
you'll choose RUN.YOUR.PROGRAM, which will make the
necessary adjustments to Alarm.Clock, run YOUR.PROGRAM, and
set things back the way they were when you're done.

For the curious, Alarm.Launcher works by copying
Alarm.Template to whatever pathname you've selected.  Then
the name of the program you want to run and the
blanker/alarm parameters are written into the new program.
Alarm.CDA periodically checks the status of the alarm and
blanking flags, and if both are zero (disabled) then the VBL
interrupt is removed from the queue.  If one of the flag
conditions change, then the interrupt is re-installed.

USING ALARM.CDA WITH JUMPSTART
MaineFrame Software also offers a versatile IIGS launching
program called JumpStart.   In addition to being able to
start any ProDOS-8 or 16 program (including BIN and TXT
files), JumpStart allows you to set any file as your boot
program, and provides you with up to a 64K printer buffer.

Alarm.CDA is designed to work closely with JumpStart to
provide the greatest ease and flexibility in using this
handy accessory, and to simplify altering Alarm.CDA
settings.  JumpStart allows you to preset the screen
blanking interval and the alarm preference (display screen,
flashing borders, or off) before launching a program.  No
interim launching program is needed.  See the JumpStart
documentation for further details.  When you launch your
program, the Alarm.CDA settings will be made automatically.
When you are done with your program, you  will be returned
to JumpStart and the settings will be restored.  If you
missed any alarms because you had the feature suppressed
while running your program, the alarm will be activated
after JumpStart gets going again, the theory being "better
late than never."  Depending on your reason for setting the
alarm, this may or may not be true.

However, if your application's pathname is greater than 62
characters long, this feature will be over-ridden (actually
over-WRITten!).  You shouldn't force yourself to use such
long pathnames anyway.

SUMMARY
We hope that you find Alarm.Clock useful and that it adds to
the performance of your Apple IIGS, along with your
enjoyment of this outstanding computer.  If you have any
suggestions regarding ways in which Alarm.Clock might be
improved, please let us know and we will strive to
incorporate your suggestions into our future products.
                  MaineFrame Software
                  Box 315A, Cousins Island
                  Yarmouth, ME  04096

      MCI Mail:  MaineFrame       CompuServe:  74425,1266
      GEnie:  D.Hill9             Ma Bell:  (207) 846-6745

ACKNOWLEDGMENTS
The author wishes to thank the following people for
bug-finding and extermination, as well as for invaluable
ideas regarding the functionality of Alarm.CDA.  They have
proven that a national network of Apple fanatics can work
together to make new ideas work.
          Apple Computer Developer Technical Services
          Beagle Bros., Inc.
          Glenn Hoffman
          Dave Lyons
          Sandy Mossberg
          Peter Paul
          Sam Pemberton
          Dave Sugar
I apologize if I've omitted anyone; everybody's help is
greatly appreciated.

                     David R. Hill
                     Cape Elizabeth, Maine
                     June, 1989