GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/zip/other/cal63.lzh/CAL63/CAL63.DOC

Text File | 1993-07-30 | 106KB | 2,178 lines

                         Cal v6.3: The Calendar Program
                        Copyright (c)1992 by Bill Aycock


Ever forgotten your anniversary or your kid's birthday? Missed a TV show
because you didn't remember what day it was broadcast? Went to work an hour
late (or even worse, early!) when you forgot to reset your clock for Daylight
Savings Time? If this has happened to you, Cal may be able to help!

Cal is a calendar program with a difference - it lets you attach 'events' to
any day of the year by date, according to a day's position in the month, or on
a regular cycle. When Cal loads, it reads the current date from your system
clock and checks to see if any significant events are scheduled for the day. If
so, Cal displays an alert that shows you the day's events. (When Cal loads as
an ACC, it dings the system bell if a significant event is scheduled.) Cal can
also communicate with CodeHead's HotWire (v2.1 or newer) to set up the day's
alarms automatically!

Also included in this package is Calshow, a program that reports on the
events you've stored in Cal and functions as an AUTO program, a full GEM-based
program or desk ACC, or from a CLI. As an AUTO program, CalShow will read the
events from Cal and display upcoming events on screen, then pause so you can
easily see what's on tap for the next few days or weeks. This should give you
plenty of time to plan for upcoming events!


====================================================

                    CONTENTS


       0. New Stuff in This Version

       1. Installation
         1.1. Installing from Scratch
         1.2. Converting from Older Versions
         1.3. DC-Squish Notes
         1.4. Limits

       2. Cal

         2.1. Concepts
           2.1.1. Event Types
           2.1.2. Importance

         2.2. Startup Actions
           2.2.1. Initialization and HotWire Alarms
           2.2.2. Alert Dialog
           2.2.3. Expired Event Dialog

         2.3. Main Calendar
           2.3.1. Types of Days
           2.3.2. Changing the Year or Month
           2.3.3. Looking at a Specific Day
           2.3.4. General Information
           2.3.5. Other Buttons

         2.4. Extras Dialog
           2.4.1. Days Between Two Dates
           2.4.2. Date of Easter

         2.5. Preferences Dialog
           2.5.1. Desk Menu Entry
           2.5.2. When An Event Expires
           2.5.3. Other Settings

         2.6. File Dialog
           2.6.1. Cal File Types
           2.6.2. Loading
           2.6.3. Saving
           2.6.4. Merging
           2.6.5. Talking with Other Cals
           2.6.6. Mass Erase Dialog
           2.6.7. Setting HotWire Alarms
           2.6.8. Checking Expired Events

         2.7. Scan Dialog
           2.7.1. Concepts
           2.7.2. How Scanning Works
           2.7.3. Scan Display
           2.7.4. Finding Events
           2.7.5. Scan Options

         2.8. Find Dialog
           2.8.1. Search String
           2.8.2. Type and Importance Filters

         2.9. Edit Dialog
           2.9.1. Edit Mode
           2.9.2. Fields on the Edit Screen
           2.9.3. Looking at Events
           2.9.4. The When and Help Dialogs
           2.9.5. Changing Existing Events
           2.9.6. Adding New Events
           2.9.7. Erasing Events

       3. Calshow
         3.1. Running from the AUTO Folder
         3.2. Running as a PRG or ACC
           3.2.1. Calshow Preference Overrides
           3.2.2. Calshow Preferences
         3.3. Running from the Command Line

       4. Final Notes
         4.1. Registration
         4.2. Version History

       5. Keyboard Shortcuts
         5.1. Main Calendar
         5.2. Alert Dialog
         5.3. Edit Dialog
         5.4. Expired Event Dialog
         5.5. Extras Dialog
         5.6. File Dialog
         5.7. Find Dialog
         5.8. Mass Erase Dialog
         5.9. Preferences Dialog
         5.10. Scan Dialog
         5.11. When Dialog
         5.12. Calshow Main Dialog
         5.13. Calshow Preferences Dialog
         5.14. Calshow Command Line Parameters

====================================================


0. New Stuff in This Version


The database format has changed in this version. To copy over your old
events, run Cal 6.3 and select the File button, then the Load From File button,
then select your old copy of Cal (any version 5.x or 6.x). The events will be
loaded and converted automatically. Remember to save your events in the new
file after you've converted them!



Main Cal changes (in no particular order):
------------------------------------------

* You can select more than one weekday when defining a positional event.

* You can perform a 'date calculation' in an event's message. In the
  message text, include a control-A (looks like an up-arrow) followed by
  a year of exactly four decimal digits. The message displayed for the
  event will replace these five characters with the number of years
  between the year you entered and the current year. (You'd use this for
  birthdays, for example... for someone born in 1980, make the text read
  something like "Joe's birthday (^1980 years old)" and the display will
  show "Joe's birthday (12 years old)".

* There's a new 'Help' button on the cyclic event edit screen. Use this
  button to find an ending date by adding a number of days to the start
  date.

* Add, delete, and replace event verification alerts now display some of
  the text of the message to be acted upon. Helps avoid errors.

* In the Edit screen, the Enter and Return keys will move the cursor to
  the next editable field. In old versions Enter either exited the screen
  or had no effect at all.

* An event can now be marked as a 'Holiday' or 'Skip on holidays' event.
  If a Holiday event falls on a day, any Skip-Holidays events will _not_
  be shown on that day. A new Prefs setting allows you to override this
  action and display even 'skipped' events.

* You may double-click the Prev or Next buttons in the Scan dialog to move
  to the first or last selected event.

* The statistics shown on the credits screen (Help at main calendar) now
  include the number of unused bytes remaining in the message area.

* The Expired Events dialog now has a clickable Exit button, instead of
  requiring you to press Undo to exit before checking all expired events.

* The Edit dialog now includes a Prev button to move you to the previous
  selected event (next to the existing Next Event button).

* Instead of a single 'switch to next edit mode' button, the Edit dialog
  now has three buttons that allow you to select an edit mode directly.
  The next selected event of the desired type will be displayed if one is
  present; if there are none, a blank template will be shown.

* The Edit dialog behaves in a MUCH more reasonable fashion. The Next and
  Prev buttons will cycle through all selected events in order no matter
  what type they are. (Previously, if the first event Edit showed was a
  Date event, for example, all Positional events were deselected.) But
  note, if a cyclic event is displayed you will still need to select
  the ^Date or ^Pos button to exit cyclic edit mode.

* There is a new Prefs button to default new date events to one-time
  events if you wish.

* When creating a new Cal data file for saving events, the file name is
  displayed in the do-you-want-to-do-this alert.

* Key equivalents have been added or changed for new or changed buttons.


Main Calshow changes (also in no particular order):
---------------------------------------------------

* Calshow 6.3 supports the Cal 6.3 database format (not older formats).

* Preferences have been moved to a separate dialog to make room for new
  features.

* You may select, for each importance level, VDI text attributes (bold,
  underlined, italics, outlined, grayed-out) for the display of events of
  that importance. Obviously these attributes will only work when you view
  a GEM coming-events listing.

* The days-until, date, and alarm display in a GEM listing are in normal
  text now. If an event is defined as a holiday, the values will be shown
  in boldface. If the event is a skip-on-holidays event, AND a holiday
  event falls on the same day, AND you've selected the show-skipped-events
  button, the values will be grayed out (even if the holiday event is not
  displayed due to an importance level filter).

* The old 'Week' quick-view button is now a 'nn-Days' button. There is a
  Prefs setting to set the number of days for this button. (The value is
  also editable from the main screen, but you will need to cursor down to
  the field (or hit Alt-D) to edit the value... if you click the button,
  you'll get the display instead of just moving the cursor.)

* Calshow supports the new date-calculation feature in event messages.

* On a GEM display, you may now use the mouse to page through or pause the
  display. One click means continue, 2 clicks means wait (like pressing
  Help), 3 clicks (if you can click that fast!) means exit now (like
  pressing Undo). The keys may still be used.

* The Quickview buttons (nn-Days and Today) will now honor the Start Date
  if one is entered on the main display.

* Calshow should now print to an Atari laser printer if the LaserBrain (and
  possibly the Diablo) driver is used. To do so, select the 'print anyway'
  button when Calshow says the parallel printer is not ready. (Too bad the
  SLM drivers don't intercept GEMDOS printer status calls. :-)

* For the alerts that choose file or printed reports, formfeed yes or no,
  and recheck printer or print anyway, you may hold down the Alt key when
  you click your answer. When you do so, Calshow registers the button you
  click as the new default button, so in the future you'll be able to select
  it by just hitting the Return key. (Make sure you save your Calshow
  preferences after choosing a new default button!)

* Key equivalents have been added or changed for new or changed buttons.

* Calshow will now accept commands passed on the command line. All commands
  passed MUST begin with the dash character ('-'). All characters passed are
  uppercased and blanks are removed when parsing the command line. If any
  command errors are detected, an informative message and the actual command
  line used (upper case, no blanks) are displayed, followed by a help display.
  Extra characters following a command or argument, or non-numeric chars when
  digits are expected, will be ignored. Unless the -G (GEM mode) command is
  included, Calshow will exit after the output is written or displayed. The
  preferences saved in the Calshow file will be used unless overridden by
  switches on the command line. Enter a question mark as the first non-blank
  character to view the Help display (or include the -? switch anywhere on
  the command line). Use '-I' with no arguments to select all importance
  levels. If the '-O' switch is used with no arguments, the output will be
  written to a file named EVENTS.TXT in the current directory. File output
  will always overwrite an existing file with no warnings. See the Keyboard
  Shortcuts appendix at the end of this document for a complete list of valid
  command line parameters.


====================================================


1. Installation


1.1. Installing from Scratch

Installing Cal and CalShow is simple. Cal comes ready to go, pre-configured
with over a hundred commonplace and obscure events. To use Cal, either install
it as a desk accessory in the normal fashion, or just run it as a program. Cal
uses roughly 90K of memory, and runs on any ST or TT in any resolution.

Likewise, CalShow can run as a normal GEM program from the desktop or as a
desk accessory. However, CalShow can also run from the AUTO folder, so you can
be reminded of upcoming events every time you boot your system. To do so,
create a folder named AUTO on your boot disk and copy CSHOW63.PRG into the new
folder. Like Cal, CalShow can run in any resolution on any ST or TT. It uses
under 60K as an accessory. (Note: Cal does NOT need to be installed as an ACC
in order to use Calshow as an ACC.)

NOTE: You can also place Cal in your AUTO folder if you want. It won't _do_
much of anything when you boot up, but it won't crash your system! <grin>


1.2. Converting from Older Versions

In the past, upgrading to a new version of Cal meant either running your old
version and saving your events in the new one, or running a separate conversion
program (to convert from 4.x to 5.x). It's even easier now!

Even though Cal's database format has changed again, Cal 6.3 lets you load
events _directly_ from an older Cal 6 or 5.x Cal file. Simply run Cal 6.3,
click the File button, click the Load button, and use the item selector to
find your old copy of Cal. Cal 6.3 will read in all your events and convert
them to the new format automatically. When converting from v5.x, HotWire alarm
information is removed from your messages and stored in the new alarm settings
fields, and the importance of each event is set to level 7 for significant
events, level 4 for normal events, and level 1 for trivial events.

When you return to the File dialog, click Save to store your new events into
the Cal 6.3 program file. Simple!


1.3. DC-Squish Notes

Cal and Calshow are compatible with DC-Squish 1.4, Double Click's program
compressor. This little jewel basically lets you "arc" your programs and desk
ACCs to save space on your disk. The program is automatically unArced when you
run it (or load the ACC). Another advantage of DC-Squish is that since the
program files are smaller, they generally load a bit quicker (especially from a
floppy). DC-Squish is a part of the DC Utilities package available wherever you
buy ST software.

To squish Cal and Calshow, simply follow the DC-Squish instructions. When you
click the "Squish" button, you should see an alert that says "offset protocol
recognized- use it?".

            IMPORTANT: YOU MUST ANSWER YES TO THIS QUESTION!!!

This makes DC-Squish compress the program part of Cal and Calshow, but leave
the embedded data alone. If you answer No instead, you will not be able to save
your events in Cal, and Calshow won't be able to read Cal's event data! (If
your copy of DC-Squish doesn't support the 'offset protocol', DO NOT use it on
Cal or Calshow- upgrade to the latest version of the DC Utilities!)


1.4. Limits

Cal 6 provides around 20K of space for the event database, and enough room to
hold 511 events in its index. There are no limitations for any group of events
(e.g., events on a single day, events to be scanned) other than those imposed
by the size of the database and index.

If each of your events uses every character on all three lines available for
the message, Cal will run out of room at around 166 events. If you define the
maximum number of events, then each event can have a message 17 characters in
length. In practice, most users will fall somewhere between these two limits.
Database usage statistics are shown on the Credits screen (see below).


====================================================


2. Cal


2.1. Concepts

Cal is, among other things, a universal calendar. You can use Cal to see the
calendar of any month in any year from the year 1 to the year 9999. But more
than that, Cal is designed to help you remember birthdays, anniversaries, TV
shows, and more- any event that occurs on a particular day. It works equally
well for weekly TV shows, monthly meetings, birthdays that only roll around
once a year, or once-in-a-lifetime experiences. This section explains some
basic concepts that will help you make the most of Cal and Calshow.


2.1.1. Event Types

The concept of an "event" is central to Cal. Webster defines an event as
"that which comes, arrives, or happens, especially an incident of importance".
In Cal, an event is any incident that occurs on one day. Cal recognizes four
basic types of events: recurring date events, one-time date events, positional
events, and cyclic events.

A "date event" is any event that occurs on a specific date in a month.
Birthdays and anniversaries are date events; some holidays, such as New Years
and Christmas, are date events. Bills that are due on the 15th of the month are
date events.

The above examples are "recurring" date events, since they occur more than
once. Birthdays and holidays happen every year, bills are due every month. The
other type of date event is a "one-time" event. If you have a dentist
appointment on September 21st, 1991, you can set it up as a one-time event. The
difference between one-time and recurring date events is that recurring events
happen over and over, while one-time events occur in one specific year; after
the event has passed, it's no longer valid- it "expires".

The third type of event is the "positional event". You schedule a positional
event by its position in the month. Examples: Thanksgiving Day is always the
fourth Thursday in November; the last Sunday in October is the end of Daylight
Savings Time. Ptaug, our local Atari users group, holds meetings on the last
Wednesday of every month except July and December.

Cal 6 provides a fourth event type, the "cyclic event". Cyclic events are
those which occur repeatedly over a fixed time span, every so many days. If you
get paid every two weeks, add a cyclic event for every 14 days to remind you.
If you need to mark your summer vacation so you won't schedule a meeting during
that time, you can set up a cyclic event that occurs every day during that
time. Cal allows cyclic events to occur every one to 255 days over a period
of up to 100 years. Just tell Cal the date of a cyclic event's first
occurrence, how often it occurs, and an ending date after which the event
expires.


2.1.2. Importance

Another basic concept is that of an event's "importance". Starting with Cal
6.0, an event can have an importance level of zero to nine, with zero as the
least important and nine as the most. The importance level affects the way Cal
displays an event, and gives you another way to select groups of events as
you'll see later.



2.2. Startup Actions

Several important things happen when you start Cal. If you run Cal as a
program, these actions occur all at once; if you load Cal as an accessory
instead, some things happen when the accessory loads and others don't occur
until you select the accessory from the Desk menu.


2.2.1. Initialization and HotWire Alarms

Cal starts out by checking if it's running from the AUTO folder. Any program
that relies on GEM cannot run while your ST is just booting up. Most GEM
programs don't check to see if they're running at boot time, and simply crash
your system... Cal DOES check, and DOESN'T crash- it just displays a short
message on your screen and gracefully quits.

Next, Cal reads your system clock to find out what day it is. Then it checks
to see if any events are scheduled for the current day. If an event is
scheduled, two things happen. First, Cal checks to see if CodeHead's HotWire is
active. (HotWire is an enhanced desktop replacement- very powerful, easy to
use... highly recommended!) If it is, Cal can set up to sixteen HotWire alarms
for you, to keep you on track during the day! (Note: Cal is smart enough to
skip setting alarms for times that have already passed. Also, Cal won't set
alarms that already exist, so you don't need to worry about having a dozen
copies of the same alarm go off at once. :-) HotWire must be at version 2.1 or
above for this feature to be active.

Then, if Cal is loading as an accessory, it will ding the system bell to
remind you that something is happening today.


NOTE: Cal will set your alarms as soon as he initializes. Also, every time
you go to the main calendar screen Cal will check to see if today's date has
changed. If so, Cal will automatically set your alarms for the new day. You
can also ask Cal to set the day's alarms at any time from the File dialog;
more on that later.

ANOTHER NOTE: If you own CodeHead's MultiDesk Deluxe and you set up Cal as a
non-resident accessory, you MUST include the "-I" parameter in your TITLES.MDX
file if you want to set HotWire alarms when you boot! This parameter tells
MultiDesk to let Cal perform its initialization - which includes setting the
day's alarms - when you boot up your system. Cal will still work fine as a
non-resident ACC without the -I parameter, but your alarms won't be set until
you actually choose Cal from the MultiDesk menu. For further information, see
Appendix A in the MultiDesk Deluxe user guide.



Next there's a break in the action. If Cal is running as an accessory,
nothing else happens right now- the rest of the initialization waits until the
first time you select Cal from the Desk menu. If you're running Cal as a
program, there's no pause; it keeps right on truckin' along.


2.2.2. Alert Dialog

The next step of Cal's initialization is to let you know about any events
scheduled for the day. If nothing is on tap, this step is skipped; otherwise,
Cal brings up the Alert Dialog.

The title bar at the top of this dialog will normally read "Events of the
Day". However, if Cal tried setting any HotWire alarms for you, the title bar
will tell you so. It will also let you know if Cal was unable to set one or
more of your alarms; be sure to read the message to find out the status of the
day's HotWire alarms.

NOTE: If the MOST important event on a given day has an importance level of
zero, the Alert Dialog will NOT be displayed automatically. The only time this
is not the case is when the level-zero event is an alarm, HotWire is active,
and Cal was unable to set the alarm for you. If this happens, Cal will display
the alert so you can see the error message.

The upper box of this dialog shows the day of the week, date, and year, plus
the Julian date (that's the day of the year, folks) and how many days remain in
the year. The main part of the dialog is a large box that lists the events
scheduled for the day.

This box can show up to eight events at a time, depending on how many lines
of text each event contains. If all of the messages for the day fit on this
screen, the "next page" button at the bottom of the screen will be grayed out;
if there are too many messages to display at once, you can click this button to
view the rest of the events. Each click shows you the next few events; after
the last waiting event is displayed, Cal 'wraps around' to the first one and
starts over. Unlike older versions, there is _no limit_ to the number of events
Cal can display on a single day (other than the total number of events defined,
that is)... but if you end up with more than 50, I'd _still_ recommend hiring a
secretary. :-)

The first line of each event is marked with a small symbol, either a triangle
(for a normal event) or a clock face (if the event has an associated alarm).
This makes it easy to see where one event ends and the next begins. In
addition, you may click on a clock face; this will display the event's alarm
time in the box at the top of the dialog.

You may edit an event from this screen if you wish; click on the message text
or on an unused slot in the display (or press a number key on the numeric
keypad). This takes you to the Edit Dialog; more on that later. Since we're
still booting up, click the Cancel button or just hit Return and Cal will
finish its initialization.


2.2.3. Expired-event Dialog

As the last step of its initialization, Cal searches your events looking for
one-time date events and cyclic events. If any are found, Cal looks to see if
each event's last occurrence has passed; if so, then the event has expired.

One of three things happens next. First, Cal can ignore the fact that the
event has expired, and just continue initializing. Second, Cal can go ahead and
erase the old event for you automatically. Third, Cal can ask you what to do
with the event. Which of these happens depends on how you've set up Cal; the
initial setting is for Cal to ask you what to do, but you can change this to
your taste. (See the Preferences section for information on how to do this.)

Cal asks you what to do with an expired event by displaying the Expired Event
Dialog. The top of this dialog shows the event and the day it was scheduled to
occur. The buttons on this dialog will let you erase the event, leave it alone
for the moment, or convert a one-time date event to a recurring event.

If you prefer to wait until later to look through the expired events, press
the UNDO key to cancel the process. When you have more time, you can start the
process again from the File menu.



2.3. Main Calendar

Most of Cal's main screen is taken up by a calendar display. The month and
year of the calendar is shown right underneath the display, and there is a
column of month buttons to the right. There are plenty of other buttons too; in
fact, almost anything you click on will do something <grin>. More about that in
just a minute...


2.3.1. Types of Days

The calendar display has changed significantly from older versions. If Cal is
showing the current month and year, then today's date will be highlighted
(white numbers on a black background). Days in the preceding and following
months are grayed out. The other days in the month may be surrounded by boxes
of varying thickness. These borders indicate the importance level of the _most
important_ event falling on that date... a heavy border means an important
event (levels 7 to 9) occurs that day, a medium border means the most important
event is between four and six, and a skinny border means that a level 1 to 3
event occurs. If there is no border surrounding a day, then only level zero
events occur then (or, of course, nothing at all is scheduled that day).


2.3.2. Changing the Year or Month

There are a couple ways to look at different months and years. First notice
the column of buttons to the right of the calendar. These buttons are labeled
with the names of the months; click one of these buttons to move directly to
that month. The bottom two buttons are labeled Next and Prev, and will skip
forward or back one month. (Also note that the buttons are marked like the top
row of keys on your keyboard, with numbers 1 to 0 plus - and =... pressing one
of these keys will act just like clicking the appropriate month button. You may
also use the numeric keypad keys 1-9, (, ), and / to select a month. The left
and right arrow keys move you forward or back a month like the Next and Prev
buttons.)

Next, note the arrow and double-arrow buttons right underneath the calendar.
These buttons, or the up and down arrow keys, move the display forward or back
one or ten years at a time.

If you want to look at a specific year, click on the box that shows the
current month and year. When you do this, you see a dialog that allows you to
type in the year you want. You'll probably find this easier than clicking the
up and down buttons.


2.3.3. Looking at a Specific Day

To find out more about a specific day or discover the reason for a border
around a number, simply click directly on that day in the calendar. This takes
you to the Alert Dialog which we (I :-) talked about earlier. You'll see the
date spelled out and a list of the day's events.

(Incidentally, this is the easiest way to add a new event to Cal -- look at
the month the event falls in, and click on the day. When the Alert Dialog shows
up, click on the text of any message or on an empty message slot. You'll go to
the Edit Dialog, with the date preselected, ready to add a new event. We'll
discuss that part later; right now, let's finish up with the main screen.)


2.3.4. Other Buttons

The buttons across the bottom of the main calendar screen will take you to
several other dialogs, which are explained in detail below.

The question-mark button takes you to the Extras dialog, where you can find
the date of Easter or perform date calculations.

Today, obviously enough, tells Cal you want to see the calendar of the
current month. If you already looking at the current month, then Cal will show
you the Alert for today's date.

The Prefs button allows you to customize Cal's behaviour from the Preferences
dialog.

The File button lets you load or save Cal's events, erase an entire month's
worth of events at once, or check Cal's database for events which have
expired.

The Scan button moves you to the Scan Dialog, where you can see a number of
events at once.

The Quit button lets you exit Cal.

NOTE: Cal keeps track of whether you change any of your events or customize
Cal's setup. If you look right under the column of month buttons, you'll see
the word SAVED or CHANGED to remind you.

If you've changed something during your Cal session but haven't saved your
changes, you get a chance to do so when you click Quit. An alert appears that
asks you if you want to save the new information, resume what you were doing in
Cal, or go ahead and quit. Choose the one you feel is most appropriate. If you
select Save, the GEM item selector will appear so you can locate the Cal file.
(If you press the Alt key when you select Save, you'll go to the File dialog so
you can save to a file or to a Cal ACC.) After you save your events to a file
successfully, you'll exit Cal; otherwise you'll return to the main dialog.

WARNING: If you run Cal as a program (or a non-resident ACC) and decide to
exit without saving your changes, they're GONE. If you're running Cal as a
regular accessory, your changes will still be in place when you next open the
ACC (and, if you _still_ don't save your setup, you'll be reminded when you try
to exit again).

ANOTHER NOTE: One of your options is to have Cal erase expired events for you
automatically. When this happens, the event is removed from the copy of Cal
currently in your Atari's memory. This means Cal's setup can change _even if
you don't do anything_! If you see the "setup has changed" alert when you exit
Cal but you haven't changed anything, it's probably because Cal has erased an
expired event for you.


The last button on the main screen is the largest one- it's the main title
bar that normally reads "Calendar 6.3". When you click on the title bar, you
go to a special screen that shows you the current version number and release
date, how many of each event type is currently defined, how much room is still
available in the event database, and where to send your shareware donation
<grin>. Press any key or click the mouse button to exit this screen.

The title bar also allows you to reposition Cal's dialog on the screen. Click
on the title bar and hold down the mouse button, then drag the outline of the
dialog to the desired location and release the button. The relative position
of the dialog is saved whenever you save your setup; if you wish, you can tell
Cal to use this saved position automatically when it starts up.



2.4. Extras Dialog

The Extras dialog is a simple screen that lets you find the number of days
between two dates or the date of Easter for a given year, or lets you add or
subtract some number of days from a base date and find the resulting date.

Use the top half of the dialog to perform date calculations. Enter a base
date at the top, then type in a date (to find the days between) or a number of
days (to calculate a new date), then press Enter. The two radio buttons let you
choose USA (month/day/year) or European (day/month/year) style dates.

If you leave part of a field empty, Cal will use the current date (month,
day, or year) for that value. If you leave both empty, Cal will gladly tell you
that there are zero days between today and today. :-)

The bottom half of the dialog will calculate the date of Easter for a given
year. (Betcha didn't know you could calculate that, did ya? :-) Type in a year
and hit Enter, and Cal will tell you when Easter falls that year.

Click Exit or press Undo to leave the Extras dialog.



2.5. Preferences Dialog

As was mentioned above, you can customize several aspects of Cal's behaviour.
These include the handling of expired events, whether to use USA or European
dates, and a number of other options. To change any of these items, click  the
Prefs button on Cal's main calendar screen.


2.5.1. Desk Menu Entry

The top of this dialog contains a text field labelled "Desk Accessory Menu
Entry". When you run a fresh copy of Cal as a desk accessory, it shows up in
the menu as "Calendar 6.3". If you wish, you can change this entry by typing in
a new entry to use. If you have a large number of events to keep track of, you
may want to split them up between two or more copies of Cal... this feature
gives you a way to distinguish between the different copies in the Desk menu.
(The string you type in here also shows up in the main screen's title bar, so
you can tell which copy of Cal you're running.)

NOTE: When Cal runs as a non-resident ACC under MultiDesk Deluxe, the entry
in MultiDesk's menu comes from a special list you set up in your TITLES.MDX
file. That means if you change the title here, it WON'T automatically change.
See your MultiDesk Deluxe guide for more information.


2.5.2. When An Event Expires

Underneath the menu entry field are a number of radio buttons. The lower left
group lets you tell Cal how to handle an expired event. There are three buttons
in this group: Erase the event, Leave it alone, and Ask what to do. If you
select Leave It, then Cal will never check for expired events unless you choose
to do so from the File dialog. If you select Ask, then Cal will ask you what to
do with each expired event when you first run Cal. You can also select Erase
It- when you do, Cal will automatically erase any event that has expired.

NOTE: You must save your Cal setup to disk after an expired event has been
erased; otherwise it will still be in Cal's database on disk, and will be there
the next time you load Cal. Also, Cal keeps track of any changes that were made
in a session. When you exit Cal, it checks to see if you've saved your changes-
if not, you'll see an alert asking if you want to save your changes. Remember
that if _Cal_ erases an expired event for you, you may see this alert even
though _you_ haven't changed anything!


2.5.3. Other Settings

Between the menu entry and expiration setting is a box labeled "New Event
Defaults". When you add an event, you can assign a particular number of days of
advance notice for the event; Calshow pays attention to this number when it
builds its display. The first field in the Default Values box is marked "days
notice", and tells Cal what value to use as the default notice whenever the
Edit dialog shows you an empty template. The second field is marked
"importance", and allows you to set the default importance level for new
events.

The right side of the Prefs dialog has a box labeled Options which control a
number of features. In each case, select the button next to a feature you want
to turn on or deselect the button to turn the feature off:

The 'Alarms' button gives Cal permission to set HotWire alarms. IF THIS
BUTTON IS NOT SELECTED, CAL WILL NEVER SET ANY HOTWIRE ALARMS ON ITS OWN! The
only way to set alarms when this button is not selected is to choose the Set
Alarms option from the File dialog.

The button marked 'Beeps On' asks Cal to ding the ST's bell whenever a GEM
alert is displayed. You shouldn't see many alerts normally, but feel free to
turn off the beeps if you wish.

When the 'Euro Date' button is selected, the European day/month/year style is
used for all dates instead of the USA style month/day/year. (Actually, in most
cases Cal will display the month name spelled out, or the first three letters
of the name. Or, to show a number of months at once, Cal displays a string with
the first letter of each month name, or a period if the month isn't selected.
Example: "JF........ND" indicates January, February, November, and December.)

You may select the button marked '24hr Time' if you would prefer to see alarm
times in military 24-hour time instead of 12-hour AM/PM time. This setting
affects the display in the Scan dialog and the Alert dialog.

The 'Zoomboxes' button asks Cal to draw decorative shrinking boxes when
changing from one dialog to another. Unless you have a fast machine and a
blitter, you'll probably want to leave this button deselected. :-)

If the 'Location' button is selected, Cal will use the saved position of the
dialog when it appears. Otherwise, the dialog will be centered on screen. (The
location is saved as a relative position, so you never need to worry about
Cal's dialog appearing halfway off the screen!)

The 'One-time' button, when selected, defaults new Date events to one-time
events. When an empty date-mode template appears in the Edit screen, the Year
field will be filled in with the current year automatically.

The button labelled 'No skips' asks Cal to ignore the skip-on-holidays
setting for each event. Skip-holiday events will be displayed in the Alert
screen even if the selected date is a holiday.

The last section of buttons in the Prefs dialog lets you decide if you want
to be warned before you add, replace, or erase an event. Some people find these
alerts irritating, intrusive, or excessive, so I've supplied a way to turn them
off. Simply deselect the button, and be sure to save your changes. (Note: in
older versions, the alerts occurred after the fact. That was like locking the
barn door after the horse escaped, and I asked myself many times why I did that
<g>. They work correctly now, and ask you BEFORE the event so you get a chance
to change your mind.)


After you make any changes in the Preferences dialog, be sure to save the new
information in the Cal program file! Either save the information from the File
dialog, or you'll have a chance to do so when you exit Cal.



2.6. File Dialog

The File Dialog allows you to save the events and preferences you've stored
in Cal. There are also options to reload a new set of events into Cal, merge
the events from a Cal file into Cal without erasing what's already there, erase
a number of events at once, check to see if any of your events have expired, or
set HotWire alarms for the day.

There are several important concepts to keep in mind here:

   1. BEFORE you run Cal or load it as a resident desk accessory, all
      your events and preferences are stored IN THE CAL PROGRAM FILE.

   2. AFTER you start Cal or load it as a resident desk accessory, your
      events and preferences are stored IN YOUR COMPUTER'S MEMORY.

   3. Once Cal is running, CAL HAS NO CONNECTION WITH THE ACTUAL PROGRAM
      FILE ON DISK.

   4. This means that any changes you make in Cal - adding new events,
      changing existing events, or setting new preferences - ONLY AFFECT
      THE COPY OF CAL IN YOUR ST'S MEMORY! If you want to make your
      changes permanent, you must SAVE your setup to the program file.

   5. This also means that once Cal is running as a standard accessory,
      CHANGES YOU MAKE TO THE PROGRAM FILE DO NOT AFFECT THE CAL ACC!
      If Cal is running as an ACC, and you run Cal separately as a program,
      the changes you make to the PROGRAM will NOT show up in the ACC
      until you load the new setup from disk (or save it to the ACC).


2.6.1. Cal File Types

There are two basic types of Cal files. The first is the Cal program file
itself. Your events are stored in the actual program file until Cal starts up.
(Note: the format of Cal 6's database is not identical to older versions. Cal 6
will let you load your events from an older 5.x version, but you will not be
able to save to an old version.)

The second type of Cal file is an external Cal data file. Starting with
version 6.0 of Cal, you can save your _events only_ to a separate file for
archiving, transporting, or other special uses. A Cal data file is around 20K
in size and contains only the event database; no preferences or program code.

Note: Versions 4.9 and up of the Whatis File Identifier can recognize Cal
data files. The latest versions of Whatis and Cal can always be found on
Compuserve's Atari Productivity Forum (GO ATARIPRO at any ! prompt).


2.6.2. Loading

The Load From File button in the File dialog lets you completely replace
Cal's events with those stored in a disk file. Click the Load button, use the
item selector to choose a file from which to load, and click OK. If the
operation was successful, Cal will contain the same events that are present in
the disk file.

You can load events from either the Cal program file or from an external Cal
data file. When you load from the program file, your preferences are loaded at
the same time. If you load from a Cal data file instead, only your events are
changed (since the data file doesn't contain any preference data).

Cal 6 will also let you load your events (but not preferences) from a copy of
Cal version 5. As the events are loaded, they are converted to the new Cal 6
format automatically. This makes it simple to convert to Cal 6 from an older
version of Cal.


2.6.3. Saving

The Save To File button allows you to save your events to a disk file. To
save all your events and preference settings to the Cal program file, click
Save, use the item selector to locate Cal, then click OK. If the operation was
successful, your copy of Cal on disk will contain the same information as the
copy of Cal that is currently running.

You also have the option of creating a separate Cal data file, or saving your
events to an existing Cal data file. To create a new file, simply type a new
filename when the item selector appears. You'll be told that the file doesn't
exist, and asked if you wish to create a new file; click Yes or hit Return, and
Cal will save all your events into a new data file.

It's even easier to save your events to an existing Cal data file - just
select the data file with the item selector, as if it were the Cal program
file. Cal can tell which type of file you've selected, and will save in the
correct format automatically.

Reminder: Cal 6.3 cannot save events to an older version of Cal. If you see an
alert that says "Not Cal, or wrong version", try again and be sure you select
your version 6.3 file.


2.6.4. Merging

Cal 6 adds the ability to 'merge' events from any version 6 Cal program or
data file into its database. When you merge events, none of the events
currently in Cal are changed - Cal reads the events from the file one by one,
and if they are not already present, they are added to what's already there.
Exact duplicates are ignored, so you won't need to worry about having two
copies of each event.

Events cannot be merged from an older version of Cal. To accomplish this,
first save the events you've defined in Cal to an external data file, then load
the events from your older version. When that's complete, you can merge the
events from the data file you created.


2.6.5. Talking with Other Cals

Versions 6.1 and later of Cal have the ability to communicate with any Cal
ACCs in your system. If you have Cal installed as an accessory and then run Cal
as a program, the program will be able to read the events from or save a new
set of events into the accessory. If you have two or more copies of Cal running
as ACCs, each will be able to read or write the events stored in the other.
This communication is controlled by three buttons and an editable text field in
the File Dialog.

The two buttons on the right of the dialog, under the Save to File button,
are labelled 'load from acc' and 'save to acc'. When these buttons are enabled,
you can use them to read or write events from an active Cal ACC just as you
would from a Cal program file.

To the left is a button marked 'rescan for acc', and underneath this button
is a box marked 'name' with a text entry field. These two objects control which
copy of Cal you are talking to.

When your ST loads an accessory, GEM keeps track of the file name. Later,
applications can ask GEM if a particular ACC has been loaded. To talk with one
particular Cal ACC, type the filename of that ACC, minus the extender, into the
Name field, then click the Rescan button. Cal will ask GEM if that file has
been loaded; if so, the load-from and save-to buttons will be enabled.

NOTE: When Cal tries to load from or save to an ACC, it will wait up to five
seconds for the ACC to respond. Normally the process will be very quick, but if
you have Cal set up as a non-resident MultiDesk MDX, it will take MultiDesk a
couple seconds to load Cal.

IMPORTANT NOTE: You WILL NOT be able to save your events successfully into a
non-resident copy of Cal! The process may appear to finish without error, but
once the Cal MDX has responded, MultiDesk unloads it from memory- meaning that
none of the new events are saved. If your copy of MultiDesk Deluxe is at
version 3.4 or higher, Cal will not let you try saving to a non-resident MDX.

ANOTHER NOTE: The restrictions dealing with MultiDesk ACCs that talk with
other ACCs applies to Cal. See your MultiDesk manual for more information.


2.6.6. Mass Erase Dialog

This dialog is used to erase all the events in one or more months at one
time. Click the File dialog's Erase button and the dialog will appear; then
select the months you wish to erase and click the Erase button. If you respond
Yes to the alert that appears, all the events that occur in the selected months
will be removed. Cyclic events are not affected.

NOTE: This process entails moving around a lot of data, so it may take awhile
to finish, depending on how many events you have and which months are being
erased. The cursor will change to the busy-bee shape while Cal is working. Be
sure to give Cal enough time to complete the process!

You also have the option of erasing ALL OF YOUR EVENTS AT ONCE. If you select
the All button, then verify that you really want to do so, Cal will erase every
one of the events you've defined. This process takes only a fraction of a
second. When it completes, you will have a totally empty copy of Cal with no
events defined at all.


2.6.7. Setting HotWire Alarms

The lower left button on the File Dialog is marked 'set Alarms'. When you
click this button, Cal will check every event scheduled for the current date
and set any HotWire alarms that aren't already set. You'll see an alert that
tells you how many alarms were attempted and how many were set. This button
will be grayed out if HotWire 2.1 or later is not active in your system. (Note:
since Cal is very good about setting alarms when needed, you'll only need to
use this feature after you've defined a new alarm for the current day. In most
other cases, the report will show that no new alarms were set.)

NOTE: If you select this option, Cal will set the appropriate HotWire alarms
even if you've turned off alarms in the Preferences dialog.


2.6.8. Checking Expired Events

The last option in the File Dialog allows you to check all your events and
find those which have expired. For each expired event, you will see the Expired
Event Alert. You may leave an expired event alone for the time being, erase the
event, or convert the event from a one-time date event to a recurring date
event. See the section above on the Expired Event Dialog for more information.



2.7. Scan Dialog

The Scan Dialog lets you view a number of events at once. You can browse
through a summary of all your events, or use the Find dialog to select a subset
of events to view.


2.7.1. Concepts

Cal keeps an index of all the events you've set up. This index is sorted by
month, date (for a date event) or week and weekday (for a positional event),
alarm time, and importance level. All positional events for a month show up
before the date events for that month (they have a 'date' of zero). Cyclic
events are listed first in the index, before any other types of events.

NOTE: Any event that is scheduled for more than one month is listed in the
index as if it occurred in the _first_ scheduled month. For example, if you pay
the rent on the 15th of every month, the event shows up with the January
events. If you pay your car insurance in March and September, the event shows
up in March.


2.7.2 How Scanning Works

The way Cal's Scan feature works requires some explanation. Cal keeps a 'map'
of all the events listed in the index. This map contains a special flag for
each event. Each flag can be either on or off. When an event's flag is ON, that
event is 'selected' and will show up on the Scan display. When the flag is OFF,
the event will not appear- it will be 'hidden'.

When you first enter the Scan dialog, all the flags are turned ON; that means
all your events can be displayed. To find specific events or groups of events,
you can use the Find dialog. This dialog will look at each event whose flag is
ON, and see if it satisfies your request. If it doesn't, the Find routine will
turn that event's flag OFF.

The Reset button at the bottom of the Scan display will turn all the event
flags ON, no matter what state they're in at the moment.


2.7.3. Scan Display

The title bar in the Scan Dialog displays the number of events currently
selected (those with ON flags) and the total number of events in Cal's
database. The dialog can display up to eight events at a time. The entry
for each event takes up two lines. The first line is in small type, and
shows you the event's index number, what importance level you've assigned
the event, the time of the event's alarm, and when the event occurs. If the
event is defined as a Holiday, an 'H' will appear next to the importance
level; an 'S' in this position indicates an event that will be skipped on
holidays. The next line contains, in large type, the first line of the
event's message text. Just to the left of this text is a small 'bullet'.

If you want to find out more about an event or make changes to it, click the
message text. This takes you to the Edit Dialog, which shows you all the
information about the event. (The Edit Dialog is explained below.)

When you first enter the Scan Dialog, the display is positioned to the first
event in the month you were viewing. Two buttons at the bottom of the dialog,
Prev and Next, allow you to scroll the display forward or back a page at a
time. Several other ways to scroll the display are also available from the
keyboard.

The Clr/Home key will move you to the first event. Shift Clr/Home moves to
the last event. The left and right arrow keys scroll the display one event at a
time, and the up and down arrows scroll a page at a time.

You can use the top row of keys on the main keyboard (numbers 1-0, -, =) to
start the display at the first event in any month, January to December. If
there are no events indexed in that month, the display will show the first
event in the following month. If no events at all occur past that month, the
first event will be displayed.

Note: Remember that cyclic events are indexed before the other types. If you
use the '1' key to move to January, all your cyclic events will have scrolled
off the top of the display... you'll need to scroll back to see them.

You may 'hide' an event by clicking on the bullet next to the event's text.
When you do this, Cal turns the event's flag OFF so it doesn't appear.


2.7.4. Finding Events

The Find button at the bottom of the Scan dialog takes you to the Find Dialog
so you can select a different group of events to display. When you return to
the Scan dialog, only the events that match your selection will be shown. The
next section of this manual explains the Find Dialog.


2.7.5. Scan Options

You have several options available when any events are selected. Click the
title bar of the Scan dialog, and the Scan Options alert will appear. If you
wish, you may erase all the events that you've selected, or you can swap the
'selected' status of all events (those that were hidden will be selected, those
that were selected will be hidden). This gives you an easier way to perform
housekeeping.



2.8. Find Dialog

The Find routine uses the same event-flag method as the Scan dialog. When you
try to find events that satisfy your requirements, Cal checks each event whose
flag is ON to see if it matches. If not, the event's flag is turned OFF. If
there are NO events which satisfy your request, Cal will ding the system bell,
restore the event map to the way it was before you tried your search, and
return you to the Find dialog. Otherwise you'll return from the dialog, and the
event map will have the results of your search.

The Reset button at the bottom of this dialog acts exactly like the one in
the Scan dialog - it turns the flags ON for all your events ("resets the map").
If a search is unsuccessful, you may want to click this button to make sure Cal
looks through all your events.

In some cases, you may enter the Find dialog when ALL the event flags are
turned OFF. When you start a search Cal notices this and gives you the option
of searching through all your events; if you say it's ok, Cal will reset the
event map for you before the search starts.

The Find dialog gives you several ways to specify the events you want to
find. You can search for events that contain a certain string, or use 'filters'
to specify certain event types, status, or importance level.


2.8.2. Search String

The top section of the Find dialog lets you specify a string to search for.
If you enter a string in this field, only events which contain the string will
be selected. You may use the radio buttons below the string to choose if the
search should be case-sensitive or not.

You can search for strings that include non-ASCII characters (those which
don't appear on the keyboard) if you wish. To enter a non-ASCII character in
your string, hold down the ALT key and type in up to three decimal digits on
the numeric keypad. The cursor will turn into a busy bee until you either
release the ALT key or enter three digits. When you do so, the appropriate
character will appear in the string.

Cal can find a string in any part of an event's message text; the string can
appear on any of the three lines. In fact, Cal can even find the string if it
is split between two lines! The end of a line of text is counted as a space
character when searching, so just include a space where the end of a line might
occur. For example, if your event has "This is a sample of an event" as the
first line and "split between two lines" as the second, you could find the
event by using "event split" as your search string.

If you do not enter a string in this field, Cal will find any event matching
the filters you enter below.


2.8.3. Type and Importance Filters

The lower section of the Find Dialog lets you set up 'filters' to give you
more control over the events you find. The first part of this section lets you
find events of a certain type. If you select the button next to one of the four
event types, only events of that type will be included in the search.

If you decide to search for one-time data events, you have the option of
restricting the search to certain years. You should see two entry fields where
you may type in a start and/or end year for the search. If you enter a start
year, only one-time events that occur in that year or after will be found; an
end year restricts the search to events through the end of that year.

The bottom part of the dialog lets you specify importance levels you're
interested in. There are eleven buttons across the dialog, marked 0-9 and one
button that is blank. If you select any of these buttons, only events whose
importance matches a selected button will be found. The empty button will
deselect all the importance buttons, so that events of any importance will be
allowed.

Once you've set up the dialog to find a group of events, click the Select
button or press Enter. Cal will find all the events that match your parameters
and return you to the previous dialog. If no events match, Cal will ding the
system bell and you'll return to the Find dialog.



2.9. Edit Dialog

The Edit Dialog allows you to add, change, or erase events stored in Cal's
database. You can reach this dialog two ways: either click on a message slot in
the Alert Dialog, or click on a message slot in the Scan dialog. If you enter
the Edit dialog by clicking on a message, the edit screen will display all the
information on that event; if you click on a blank slot instead, Cal will show
you the first event on that day. If no events are scheduled on a day, the Edit
dialog will show you an empty 'template' ready for you to add a new event.

This is the most complicated dialog in the Cal system, so it deserves careful
study. We'll start with a discussion of a few basic concepts.


2.9.1. Edit Mode

Cal supports four different types of events. Each type is scheduled in a
different manner, so Cal needs to provide a way to enter the data for any event
type. Cal does so by providing three different 'edit modes' - Date mode (for
recurring and one-time date events), Position mode, and Cyclic mode. Most
fields on the Edit screen are the same for each mode, but the section regarding
when an event occurs is different for each.

The screen for editing Date events contains a number of month buttons, plus
fields where you can enter a date and year to specify when the event occurs.
The Position mode screen contains the same month buttons, but instead of fields
for a date and year, you will see radio buttons where you can select a week and
weekday for an event. The screen for Cyclic events has fields for you to type
in the date of the event's first and last occurrence, and the number of days
between each occurence of the event.


2.9.2. Fields on the Edit Screen

First, take a moment to look at the dialog. Most of the dialog is taken up by
a large box. The top section of this box shows you the message text for each
event. Up to three lines of text are allowed here. The first line has a box
around it to remind you that only the first line of text is displayed in the
Scan dialog.

Three radio buttons directly under the text read 'Holiday', 'Ordinary', and
'Skip holidays'. If an event with the Skip Holidays button selected falls on
the same day as one with the Holiday button selected, the Skip-holiday event
will NOT show up on the day's events. (You can override this action using the
No Skips button in the Prefs dialog.)

The center of the edit screen shows you all the information needed for
scheduling the event. This portion of the screen will be different for each
different mode; in Date mode you'll see the date entry fields, in Position mode
you see the week and weekday buttons, and in Cyclic mode you see the start/end
dates and the period.

The lower part of the large box contains information common to all event
types: fields for the importance level, the number of days advance notice for
the event, and for HotWire alarm events, the time of day and slot number for
the alarm.

Directly under the large box are two groups of small buttons. The first
group lets you switch directly to any edit mode; click one of these buttons
(or press Control + the D, P, or C key) to toggle to date mode, position mode,
or cyclic mode. The second group of buttons lets you jump to the previous or
next event on a particular day; click a button, or press Alt-P or Alt-N.

Across the bottom of the Edit dialog you'll see a number of action buttons.
These buttons allow you to find an event with the Find dialog, erase an event,
replace an existing event, or add a new event. The last button lets you exit
the Edit dialog.


2.9.3. Looking at Events

Now let's see how to look at an event. If you clicked on the text of an event
message to get here, then the Edit dialog will show you all the information on
that event. If you clicked on a blank message slot, then all the fields here
will be blank or in their default states.

For the moment let's assume there's an event showing. The message field at
the top tells you which event you're looking at. You can see the event's
importance, days advance notice, and alarm information at the bottom of the
screen. These fields should be pretty easy to understand.

The center part tells you exactly when the event is scheduled: if the event
occurs in a particular month, then that month button will be selected. If an
event occurs in more than one month, all the appropriate month buttons are
selected. If this is a cyclic event, the start/end dates are shown.

When you look at a date event, the date on which the event falls is listed on
the right. If this happens to be a one-time event, the year in which the event
occurs is shown on the left.

IMPORTANT NOTE: THIS IS THE ONLY DIFFERENCE BETWEEN A NORMAL DATE EVENT AND A
ONE-TIME DATE EVENT. If there's a year in the box, it's a one-time event;
otherwise it's a normal recurring date event. One-time events expire; recurring
events don't.


Now that that's straight, let's see how to look at a _different_ event.


If more than one event is scheduled on the day (or position in the month)
you're looking at, simply click the Next Event button (or press Alt-N). Every
time you click this button, Cal shows you the next event on this schedule.
Click the button as often as you wish to cycle through all the events on that
day, or click on the Prev button to back up through the events. After the last
event on this schedule is displayed, you'll see an empty template; click the
Next button again to start back at the first event.

If only a single event, or no events at all, are scheduled on that day, then
you need to change days. To do so, just change any of the month or position
buttons, or type in a different date, then click the Next Event button.
Whenever you click this button, Cal looks to see what schedule you've selected,
then goes through his database looking for events on that schedule. If any are
found, Cal will display them one at a time.

IMPORTANT NOTE: If you wish, you can select more than one month button for
your search. When you do this, you'll be able to scan through all the events
matching your schedule that occur in any of the months you select. For each
event, Cal will use the month buttons to show you when the event is scheduled,
but will still remember which month buttons YOU selected. If _YOU_ change the
month buttons, then Cal will use your choices for looking at events. If _CAL_
changes the month buttons to show when an event occurs, that WON'T change the
months you selected. Cal will continue to use your month selections until you
change the edit mode, or select different month buttons on the dialog. (Note:
Cal won't store your selections until you actually change the month buttons
yourself.)


Let's say you're looking at date events, but you want to switch over and look
at a positional event. To do so, just click the small '^Pos.' button near the
bottom left. Cal will shift into Position Mode and will display the next
selected positional event in the index (if one exists). Then select the buttons
for whatever schedule you want, and click the Next Event button - this makes
Cal look for selected events on the schedule you requested.

NOTE: The Next and Prev buttons will cycle through all selected events in
the database, no matter what their type may be. However, whenever a Cyclic
event is displayed, the dialog is 'locked' in Cyclic mode. Simply click on the
^Date or ^Pos buttons to switch to a different edit mode.

The Next and Prev buttons are useful for scanning through the details of all
_selected_ events. If you're looking for a particular event, it may be easier
to use the Find dialog to help; just click the Find button at the bottom of the
screen. Use the dialog, and when you exit, the next event you found will be
displayed.

NOTE: 'Next event' means the first marked event whose position in the index
follows the event that was on the screen when you called Find. On occasion
there WON'T BE ANY MARKED EVENTS that are indexed AFTER the previous event.
When this happens, you'll see an empty template on the screen. To view your
events, just click the Next Event button - Cal will 'wrap around' at the end of
the index, and you'll see the first marked event.


2.9.4. The When and Help Dialogs

Any time the Edit dialog is showing a valid cyclic event, the small "Show
When" button in the middle of the screen will be enabled. If you click this
button, you will see the When Dialog for that event. This dialog lists the date
of every occurrence of the event. Use the 'Past' and 'Future' buttons to scroll
forward and back through the list. If you wish, you can click on one of the
dates- when you do so, you return to the main calendar screen, showing the
calendar for the date.

The 'HELP' button next to the expiration-date field can help you calculate
an end date for a new cyclic event. If you want the event to expire after a
certain number of days, click this button (or press HELP) and small dialog
will appear. Type in the number of days after which you want the event to
expire, and Cal will calculate the proper end date for you.

2.9.5. Changing Existing Events

Now that you've seen how to _look_ at an event, you can learn how to _change_
an event. You'll be pleased to know that it's simple... just find the event,
then change its message, schedule, importance, days notice, or whatever. When
you've finished the changes, click the Replace button at the bottom of the
screen. When you do this, Cal erases the old event you were looking at, then
adds whatever you typed in as a new event. Any settings you didn't change are
left as they were.

Cal has several features to make editing events simpler. When you're editing
a text field, you can use the shifted left and right arrow keys to move to the
beginning or end of the field you're editing. The Clr/home key will move the
cursor right to the first line of the message; shifted, to the HotWire alarm
slot. (The up and down arrow keys also 'wrap around' these two fields.) You can
even enter non-ASCII characters in a field by holding down the Alt key and
typing in three decimal digits on the numeric keypad. Pressing the Return or
Enter key in the Edit dialog will move the text cursor to the next editable
field.


2.9.6. Adding New Events

Adding a new event is as simple as changing an existing one- in fact, the
process is exactly the same. The only difference is that to add a completely
new event, you should click Add instead of Replace.

When an empty 'template' appears on the screen, just enter the information
you need to define a new event. Or go ahead and type over an event that's
already displayed on the screen- when you click Add, the old event isn't
changed at all; a brand new event is added to the database. However, if the
event you type in exactly matches an event already in the database, you'll be
told that the event exists and the duplicate will not be added.

NOTE: Starting in Cal 6.3, you can perform a 'date calculation' in an event's
message. In the message text, include a control-A (looks like an up-arrow)
followed by a year of exactly four decimal digits. The message displayed for
the event will replace these five characters with the number of years between
the year you entered and the current year. (You'd use this for birthdays, for
example... for someone born in 1980, make the text read something like "Joe's
birthday (^1980 years old)" and the display will show "Joe's birthday (12 years
old)".

ALSO: When adding a Cyclic event, you're asked to enter dates using numbers
for the year, month, and day. By default, Cal is set up to use USA style dates
- this means you need to enter the month, then the day, then the year. However,
if you have selected the 'Euro Dates' option in Preferences, Cal will expect
you to enter the day first, then the month and year. Remember to enter the
month and day in the correct order!

ANOTHER NOTE: There's one editing shortcut that may come in handy. If you are
editing a date event, you can type a year into the Year field to create a
one-time date event.  Since you'll usually want to insert the current year, you
can simply click the word "Year:" on the Date edit screen (or press Alt-Y);
doing so will insert the current year in this field, and move the cursor to the
field as well. (You may also ask Cal to fill in the current year for you
automatically; select the 'One-time' button in the Prefs dialog to do so.)


2.9.7. Erasing Events

An event can be erased by clicking the button marked Erase on the bottom of
the screen. Simple enough, eh?

WARNING: BEFORE you click the Erase button, be SURE you're pointing to the
right event! Cal remembers the last event displayed on the screen. If you
change the month buttons or other scheduling fields, be sure to click the Next
Event button _before_ you click Erase - this will guarantee that Cal is
pointing to the right event. If you're not careful, you'll erase something you
don't want to lose!

If you've enabled Erase Warnings in the Prefs dialog (highly recommended!),
an alert will appear asking if you're sure. This alert will display most of
the text for the event, so you can verify Cal is pointing to the proper one.


====================================================


3. Calshow

Calshow was designed primarily as an AUTO program to remind you of upcoming
events whenever you boot your Atari. You can also run Calshow as a normal GEM
program or desk accessory to see a list of upcoming events at any time, or to
write several types of reports to a printer or disk file. Calshow will also
accept parameters from the command line in case you wish to run it from a
CLI.

Basically, Calshow finds your copy of Cal, reads its event database, and
displays on screen any events that will occur within a short period of time.
The display can include the number of days until the event, the date on which
the event falls, the alarm time, and the message you entered for the event.



3.1. Running from the AUTO Folder

The easiest way to run Calshow is directly from your AUTO folder. When you do
so, it provides you with a list of upcoming events whenever you boot your
Atari.

When you run Calshow, the first thing it does is look for your copy of Cal.
There's a way to tell Calshow exactly where you keep Cal- that's explained in
the section below on running as a program. But even if you haven't told Calshow
where to find Cal, chances are Calshow can find it!

Calshow first looks for Cal wherever you told it to look. If it can't find
the file, or the file isn't Cal, Calshow looks at all the other files in that
folder whose names match the pattern "CAL*.AC?". If none of those are Cal,
Calshow checks all "CAL*.PR?" files.

If none of the files checked turn out to be Cal, Calshow takes more drastic
measures. It checks _seven more folders_ looking for any file with the name you
specified, or whose name matches one of the patterns above. First, Calshow
looks in the folder from which it was run. Then it looks in the root directory
of the same disk. If that doesn't work, Calshow keeps on looking in these
folders: \ACCS\, \MULTDESK.MDX\, \MULT_MDX\, \DESK\, \DESKACCS\, and \ACC\. If
Calshow still can't find Cal, it gives up (and shame on you for hiding it! :-).

NOTE: If one of the files Calshow examines _is_ Cal but doesn't have any
events in its database, Calshow ignores it and continues looking.


After Calshow finds Cal, it reads in the event database and displays a list
of upcoming events. Calshow displays an entry for every event whose advance
notice period is close enough to today's date. (Normally Calshow will display
up to one screen's worth of upcoming events, but you can change this setting;
see the section below on running Calshow as a program.) The entry includes the
number of days before the event, the date on which the event falls, and the
message you defined for the event.

NOTE: Calshow determines the screen size by asking the operating system for
the current resolution. Unfortunately, the value returned doesn't always
reflect the correct screen size. If you have a large-screen monitor such as a
Moniterm, you may want to adjust the Prefs setting for the maximum number of
events to display.

As distributed, Calshow will display any event, no matter what its importance
level. This setting can be changed as well; again, see below for more
information.


Once Calshow has displayed the list of upcoming events, it pauses for a
moment so you can read the list. The normal wait period is 15 seconds (but this
setting too can be changed to suit you). After this amount of time has passed,
Calshow finishes running and your bootup process continues. You can press any
key to make Calshow quit before time has expired, or press the HELP key to make
Calshow wait for a keypress before continuing.

NOTE: If Calshow can't find a valid copy of Cal, or there are no events
happening soon enough to display, Calshow will display a message on the screen
and pause for _one second only_. This means your bootup won't be delayed
unless there's a good reason.

Versions 6.1 and later have a feature that lets you tell Calshow to display
events only on the first boot of each day (see Preferences below). If you
reboot your ST and wish to see the display anyway, hold down the Alternate key
as Calshow loads. If you want to skip Calshow's display for some reason, hold
down the Control key instead.

NOTE: If your ST doesn't have a built-in clock, then you probably have an
AUTO program to set the time from a separate clock chip, your hard disk, or
some other method. Be sure this program runs BEFORE Calshow when you boot, or
the events you see won't be the ones you want to see!

IMPORTANT NOTE: Calshow uses your GEMDOS clock to determine the current
date. If you have an external clock chip but you can't get Calshow to display
the correct date when you run it from the AUTO folder, it's possible that your
clock program is only setting the keyboard clock. You can correct this by
running a program such as CLOCKSET.PRG (freeware from Little Green Footballs
and Charles F. Johnson) before Calshow runs. This program reads the keyboard
clock and sets the GEMDOS clock, so the date will be correct.



3.2. Running as a PRG or ACC

Calshow provides you with MUCH more control over its output when you run it
as a program or desk accessory. In addition, you can configure a number of
settings, such as those mentioned above, to tailor Calshow's behaviour. These
settings, prepared from the Preferences dialog, are saved in the Calshow file
so they will be active the next time you run Calshow at boot time. Calshow's
main dialog allows you to override many of these settings temporarily.


3.2.1. Calshow Preference Overrides

The top section of the main Calshow dialog allows you to set up your options.
First you see a box labelled "Show __ Events": this box lets you set the
MAXIMUM number of events Calshow will display. You can type in a specific
number of lines, or leave the value as zero. If you say zero, Calshow will try
to determine the size of your Atari's screen and display only the number of
events that will fit.

IMPORTANT NOTE: Calshow may not display this number of events every time...
it depends on the days notice you defined for each event! Remember, this is the
MAXIMUM!

Next is a field that says "Pause ___ Seconds". This field controls the length
of the pause after Calshow has displayed its event list. Type in any number
from zero to 999 seconds here.

IMPORTANT NOTE: IF YOU SET THIS FIELD TO ZERO, CALSHOW WILL WAIT FOREVER FOR
YOU TO PRESS A KEY! Keep this in mind when you're deciding on a value to enter
here.

Beneath these two fields is a buttons marked 'Show Skipped'. If you select
this button, any events you've said should be skipped on a holiday will instead
be displayed, even on a holiday. (The days-until, date, and alarm time on the
display will be grayed out to indicate that the event would normally be skipped
over.)

On the right side of the dialog is a button marked "Locate Cal". Use this
button to tell Calshow exactly where your copy of Cal is located. Click on the
button, then use the GEM item selector to find your Cal program file.

IMPORTANT NOTE: Cal doesn't actually have to be in the folder you locate!
Calshow will store the path and filename you select, even if the file isn't Cal
or doesn't even exist. This means you can configure Calshow first, then move a
copy of Cal into the right place later. You'll see an alert that warns you of
any error, but the information will be stored in memory anyway.

The next button in this part of the dialog is marked "Preferences". Click this
button to move to the Preferences dialog, where you can configure Calshow's
settings as desired.

Beneath these two buttons is a group of ten buttons marked 0-9. These buttons
tell Calshow which importance levels to show. If the button corresponding to an
event's importance level is NOT selected, that event WON'T be shown in
Calshow's display. Once you've selected the levels you wish to view, you may
click the small "Importance Filters" title to toggle your selections on and
off. You may also double-click the title to select all levels at once.


Underneath these setup items is a box where you can enter a specific start
or end date for Calshow's display.

When you enter a starting date, Calshow pretends that 'today' is the date you
entered. You don't need to enter a complete date here; if you just want to see
a list of events for the first part of May, simply enter the number "5" in the
month field. When you enter a year, any two-digit number is assumed to be in
the 1900s and any one-digit number is treated as if it's in the 2000s. Thus, a
year of "93" would be 1993 and a year of "1" would mean 2001.

You can enter a new ending date in the same fashion. Of course, Calshow will
warn you if you try ending the display before it starts.

IMPORTANT NOTE: If you enter an ending date, CALSHOW WILL IGNORE THE DAYS
ADVANCE NOTICE SPECIFIED FOR EACH EVENT. When you tell Calshow the end date you
want, it assumes you want a complete list of events up to that date regardless
of the advance notice. Calshow will keep showing events until this end date is
reached OR the maximum number of events has been shown. (Remember, you set up
the maximum in the "at most" field above.)


The next section of the Calshow dialog is labelled 'Alternate Reporting
Options'. The three buttons in this section allow you to create three different
reports to a disk file or printer.

The first type, Events, produces a report on events that will occur in the
near future. This report looks exactly like the display you'd see when running
Calshow from the AUTO folder. Each entry contains the number of days before the
event, the date and time of the event, and the message.

The second type, Datebook, will produce a datebook-like list with one entry
for every day in the time period you specify. The starting month and year are
listed on one line. Under this, another line lists the date and day of the
week. Then, if there are any events scheduled for that day, the event messages
are listed on a separate line, preceded by the event's alarm time. This type of
list is most useful when you specify a time period of a week or month; you may
want to use the Datebook output as a to-do list.

The last option allows you to produce a Master List of all the events you've
stored in Cal's database. If you choose this type of output, any starting or
ending date you've entered is ignored; every event in Cal is listed, one event
per line (with extra lines if the event uses more than one line for its
message). Each entry contains the event number, letters to indicate the months
in which the event occurs, the date or position on which the event falls, the
alarm time and number of days advance notice you've set, the event's
importance, and the event message. For a cyclic event, the entry shows the
number of days between occurrences and the date of the first occurrence. You
have the option of listing all events or only those matching the importance
levels you've selected.

If you select one of these reports, you're asked if you want the report to go
to a file or a printer. If you choose to print the report, Calshow will check
the parallel port for a printer. If your printer isn't ready, an alert will
tell you so and will give you the option of cancelling the report, checking the
printer again (presumably after you've turned it on :-), or trying to print
anyway. If you have an Atari laser printer using the LaserBrain driver, you'll
need to choose the 'print anyway' option. (LaserBrain seems to intercept the
printed output properly, but it ignores the printer status check so Calshow
can't tell if the printer is ready. Bummer. :-)

After Calshow has written the report, you'll return to the main dialog.

NOTE: For the alerts that choose file or printed reports, formfeed yes or no,
and recheck printer or print anyway, you may hold down the Alt key when you
click your answer. When you do so, Calshow registers the button you click as
the new default button, so in the future you'll be able to select it by just
hitting the Return key. (Make sure you save your Calshow preferences after
choosing a new default button!)



Four buttons appear at the bottom of Calshow's dialog. The one on the left is
marked "Go!". When you click this button or hit Return, Calshow will close its
dialog, open a large GEM window, and show you the Coming Events display.
When the display has completed, you return to the main dialog.

The next two buttons, "nn-Days" and "Today", let you instantly select a
coming events listing for the day or the next few days. Unlike the standard
Calshow display, the advance notice for your events is ignored so you get a
full picture of upcoming events. The importance filters you've selected are
still taken into account, though, as is the start date (if you've entered
one).


The GEM Coming Events window has several parts. The information line under
the title bar tells you the starting date for Calshow's list of events. The
rest of the window displays upcoming events according to the options you
specified above. First the number of days before the event, the day of the
week, the date, and the alarm time for the event appear in normal type (or
boldface if the event is a holiday). The message text for the event appears on
the rest of the line.

The message will be displayed in one of several different styles, depending
on the event's importance level. Calshow allows you to select the specific
'attributes' - boldface, italics, underlined, or outlined - that will be used
for each level. Any combination of attributes can be used; see the Preferences
section below for more information.


At the bottom of the screen, you'll see one of two messages. If the entire
list of events fits on a single screen, Calshow will display the message "press
any key to continue". You can press a key or click the mouse to return to the
main dialog, or simply wait for the pause time you entered above to expire.

If there are more events to display than will fit on a single screen, Calshow
displays the message "press a key to go on or UNDO to quit". If you press the
UNDO key, Calshow will exit to the desktop. If you press any other key, or wait
for the pause time to run out, Calshow will clear the screen and display a
second group of events. This process continues until all events waiting to be
shown have been displayed.

If you need more time to view a display, press the HELP key or double-click
the mouse button. When you do so, Calshow will wait for you to click the mouse
again or press any key before continuing.


Once Calshow has completed a display, you return to the Calshow dialog. You
can choose to see another Calshow display, or you can exit the program by
clicking the eXit button or pressing UNDO.


3.2.2. Calshow Preferences

The Preferences Dialog lets you customize Calshow's default settings and save
your configuration in the Calshow file.

The upper left part of the dialog has fields for you to specify the default
maximum number of events to display, the time to wait after displaying each
screen, and the number of days to use in the 'nn-Days' quickview button.

The upper right section contains three selectable buttons. If the Once Per
Day button is selected, then Calshow will only display upcoming events on the
first bootup of each day; if you reboot later in the day, you must hold down
the Alternate key when Calshow loads if you wish to view the display.

NOTE: Calshow uses the date stamp on the Calshow program file to determine
if each bootup is the first for the day. You must not write-protect Calshow if
you want to take advantage of this feature.

The Euro Dates button tells Calshow to expect European-style dates (day,
month, year) instead of USA-style dates (month, day, year) for the start and
end dates entered below.

The button marked Show Skipped will make Calshow display skip-on-holiday
events even if the date is a holiday.


The center portion of the dialog allows you to specify which importance
levels Calshow will display, and set text attributes for each level. The
importance filters here work just like the ones on the main dialog; select a
button to display events of that importance, or deselect it to ignore those
events.

Underneath each importance level button is a column of five letters. B, G, I,
U, and O stand for Bold, Grayed, Italics, Underlined, and Outlined. Select the
buttons corresponding to the text attributes you wish; when an event of this
level is displayed, the message text will be shown in the attributes you've
chosen.


The bottom of the Prefs dialog contains five action buttons.

When Calshow first loads, it saves a copy of its configuration into a special
'holding area'. You may click the "Revert to saved" button to restore these
settings at any time.

The "Save Prefs" button lets you store a new configuration into the Calshow
program file. When you save your prefs, Calshow also saves the configuration
in its holding area, and copies the configuration into the active settings.

The "Locate Cal" button is used to tell Calshow where your copy of Cal
resides. Click the button, then use the GEM item selector to locate the Cal
file.

The "Accept" button copies the configuration you've chosen into the active
settings. Accepting your changes does NOT cause them to be written them into
the Calshow file, nor will the configuration be copied into the holding area.
You can Accept the changes to try a new configuration temporarily; if you don't
like it, you can return to the Prefs dialog and use the "Revert" button to
restore your old settings from the holding area.

The Cancel button returns you to the main Calshow dialog without affecting the
configuration.


3.2.3. The Command Line

Calshow 6.3 will now accept commands passed on the command line. You can use
this feature to prepare any of the alternate reports or view the GEM coming
events display without using the main dialog. The preferences saved in the
Calshow file will be used unless overridden by switches on the command line.

All commands passed MUST begin with the dash character ('-'). All characters
passed are uppercased and blanks are removed when parsing the command line.
Extra characters following a command or argument, or non-numeric chars when
digits are expected, will be ignored. Use '-I' with no arguments to select all
importance levels. If the '-O' switch is used with no arguments, the output
will be written to a file named EVENTS.TXT in the current directory. File
output will always overwrite an existing file with no warnings.

Unless the -G (GEM mode) command is included, Calshow will exit after the
output is written or displayed.

If any command errors are detected, an informative message and the actual
command line used (upper case, no blanks) are displayed, followed by a help
display. Enter a question mark as the first non-blank character to view the
Help display (or include the -? switch anywhere on the command line).

This chart lists the valid command parameters:

   1. One of these switches is required:

        -?           show this help (or '?' as first character)
        -V           coming events list
        -B           datebook output (-O or -P required)
        -M           master list (-O or -P required)

   2. These optional switches may be entered as desired:

        -Ofilespec   output filespec (not with -P)
        -P           output to printer (not with -O)
        -F           formfeed after (ignored except with -P)
        -Smmddyyyy   start date
        -Emmddyyyy   end date (ignored with -D)
        -Dnn         show next nn days (-V only; ignores -E)
        -Cfilespec   Cal location
        -Innnnnnnnnn show only these importance levels
        -#nnn        show nnn events max (ignored with -E)
        -Wnnn        wait nnn seconds after display
        -K           toggle show-skipped-events setting
        -U           toggle European dates setting (ddmmyyyy)
        -G           GEM mode (-V only; returns to dialog)

Some example command lines:

Show the normal Coming Events listing, just as if you pressed the 'Go'
button in the Calshow dialog.

      -v-g

Show the coming-events listing for the next two weeks, in GEM mode. Return
to the Calshow dialog afterward. Pause for 30 seconds on each screen.

      -v-g-d14-w30

Save datebook-style output in a file named P:\DATEBOOK.PRT. The output
should start on September 1, 1992, and should show 31 days. Cal is located
in a subfolder named CAL on the D: drive.

      -b-op:\datebook.prt-s09011992-d31-cd:\cal\cal63.acc


====================================================


4. Final Notes


Cal and Calshow were written completely in assembly language using the HiSoft
DevpacST assembler. The resources were created with WERCS and converted to
assembly code using a program written by Carl Barron. Thanks to Robert
Birmingham for convincing me to add events to my simple calendar program, and
to Myles Cohen, Colin Robertson, and many others for some great suggestions!
Many thanks also to the CodeHeads for telling me how to hook into HotWire and
to the Double Click folks for help getting these programs working with
DC-Squish. Special thanks are due Charles F. Johnson for hints on letting a
program figure out if it's an ACC or AUTO program.

And, of course, many thanks and best wishes to the folks who've sent cards
and letters (and donations) -- people like you keep shareware authors writing!

The calendar routine I use in Cal was based on Zeller's Congruence, which
explains a simple way to calculate the day of the week for a given date without
resorting to a lookup table. Articles dealing with this subject appeared in
Computer Language Magazine, March and December 1988. (The articles were
helpful, although they included a couple of typographical errors. :-) Also note
that the modern Gregorian calendar wasn't invented until the 1580s, something
to keep in mind if you're poking around in the dim and distant past <grin>.

Please let me know if you use this program!!! Comments, suggestions,
requests, and bug reports are all welcome. Remember: if you find a bug but you
don't let me know about it, chances are I won't fix it. :-)



4.1. Registration


This program is distributed as shareware - try Cal out for awhile, and if you
decide to keep it, send a donation to me at the address below. For every
donation of $25 or more, I'll send a disk containing the latest versions of all
my programs (Cal, the Whatis File Identifier, KXPset Printer Setup Utility).


You may also register Cal online, using CompuServe's Shareware Registration
database. To do so, enter the command   GO SWREG   at any ! prompt. When the
Shareware Registration menu appears, select choice #2 (Register Shareware).
Then, to find Cal in the database, select 'Search by filename' from the menu,
and use CAL.LZH as the filename. Follow the prompts to select Cal and register
the program, and the $25 registration fee will be charged to your CompuServe
account.





      Bill Aycock
      2310 North Elm Street
      Greensboro, NC 27408-5120

      Compuserve ID: 76703,4061
      Internet: [e-mail]
      September 1, 1992

PS- The latest version of Cal is always available in Compuserve's Atari
    Productivity Forum (GO ATARIPRO at any ! prompt). Since I'm on the
    Forum's staff, I always upload there first. For fastest response to
    inquiries, post a message to me in ATARIPRO.

PPS- If you somehow lose my address, just press the Help key from Cal's main
     screen. :-)



4.2. Version History


v6.3: Cal: multiple weekdays for an event, holiday/skip holidays, date
      calculation in event text, new mode/prev/next buttons in Edit, new
      prefs settings, more informative alerts
      Calshow: new prefs dialog, user selectable attributes for GEM display,
      nn-Days quickview, mouse support for paging display, command line
      support, holiday/skip holiday support
v6.2b talks to MultiDesk Deluxe to find when running as non-resident MDX
v6.2a corrects behaviour of background window when a resident ACC
v6.2: Cal: more displays of alarm time; more Scan options; When dialog to show
      cyclic event dates; more date calculations; ability to move dialog on
      screen; Calshow: alarm time displayed, events sorted by alarm time; new
      Week and Today buttons; return to menu instead of exit
v6.11 both: corrected keyboard shortcuts and mouse handling in ACC mode
v6.1: Cal: adds ability to communicate with other Cal ACCs; Calshow: allows
      European date format, once-per-day bootup display
v6.02 Cal: fixed 'invisible' level-0 events, edit logic change; Calshow: fixed
      max display lines, problem when cancelling a locate-Cal process
v6.01 allowed shifted command keys; in Cal: corrected Cancel key in Mass
      Erase, added default importance level, honors alarms-disable button,
      extended cyclic period to up to 255 days; fixed Calshow to save
      importance filter, allowed Master List to pay attention to importance
      filters
v6.0: complete rewrite: added cyclic events, file load/save, importance
      levels, keyboard shortcuts, many many more changes!
v5.3: fixed Cal & Calshow to work if system date is not valid
v5.2: added extended data area; fixed Calshow to recognize any 5.x version
v5.1: Cal: added alert when no room remains to add an event
v5.0: Cal: added compatibility with DC-Squish; three importance levels; one
      event can occur in multiple months; specify advance notice separately
      for each event; Hotwire alarm feature; bug fixes, optimizations, etc.
      Calshow: completely rewritten to run as a GEM program or ACC or from
      AUTO folder; DC-Squish compatible; new Datebook and Dump output
      options; importance filter for event displays; lots more stuff
v4.7: added support for significant/non-significant events
v4.5: added multiple positional events; when saving setup, file selector now
      defaults to path Cal loaded from; allow more events on single day; added
      code to help guard against unusual March start date problem
v4.4: added option to supress add/replace/erase event alerts; added case
      sensitive search; retains search string between searches
v4.3: fixed a logic bug occurring when exiting Cal in some circumstances;
      added keyboard exit from Browse screen
v4.2: added Replace button in Edit; added option to ignore expired events;
      added type filters to Find function; changed Browse logic
v4.1: added grow/shrink box support; added leap-year check for one-time
      events on Feb 29; skip saving duplicate events; sundry other tweaks
v4.0: added multiple events on the same date; added alphabetic sort; added
      one-time events and expired-event handling; various other tweaks
v3.5: fixed filepath setup for standard GEM file selector problem
v3.4: fixed logic error in Calshow; enabled 'last' week position button
v3.3: fixed obscure bug in Find function; redesigned Browse screen and Today
      button logic; added Prev and Next month buttons; added option to save
      changed setup when exiting
v3.2: fixed occasional bus errors after erasing events and then browsing;
      included Calshow for bootup reminders
v3.1: first released version supporting events
v2.0: final calendar-only version

====================================================

5. Keyboard Shortcuts

5.1. Main Calendar

      UNDO                 Exit
      HELP, Space bar      credits, statistics
      numbers 1-0, -, =    month buttons
      keypad 1-9, (, ), /  month buttons
      Clr/Home             January
      shift Clr/Home       December
      R arrow              next month
      L arrow              previous month
      Up arrow             forward one year
      shift Up arrow       forward ten years
      Down arrow           back one year
      shift Down arrow     back ten years
      Y                    Year dialog
      F1, /, ?             extras dialog
      F2, T                Today
      F3, P                Preferences dialog
      F4, F                File dialog
      F5, S                Scan dialog


5.2. Alert Dialog

      UNDO                 Exit
      numbers 1-8          select event 1-8
      keypad 1-8           select event 1-8
      F1, N, space bar     Next page


5.3. Edit Dialog

      UNDO                 Exit
      HELP                 end date Help (cyclic events)
      Return               move cursor to next field
      ^C                   toggle to Cyclic mode
      ^D                   toggle to Date mode
      ^P                   toggle to Positional mode
      Alt-N                Next event
      Alt-P                Previous event
      Alt-H                Holiday event
      Alt-O                Ordinary event
      Alt-S                Skip-holidays event
      Alt-W                When dialog (cyclic events)
      Alt-Y                this Year (date events)
      F1, Alt-F            Find dialog
      F2, Alt-E            Erase event
      F3, Alt-R            Replace event
      F4, Alt-A            Add event


5.4. Expired Event Dialog

      UNDO                 Exit
      F1, C                Convert event
      F2, E                Erase event
      F3, I, space bar     Ignore event


5.5. Extras Dialog

      UNDO                 Exit
      F1, C                Calculate
      D, ^ R arrow         Day/month/year order
      M, ^ L arrow         Month/day/year order


5.6. File Dialog

      UNDO                 Exit
      F1, Alt-L            Load from file
      F2, Alt-S            Save to file
      F3, ^ R              Rescan for acc
      F4, ^ L              Load from acc
      F5, ^ S              Save to acc
      F6, Alt-M            Merge from file
      F7, Alt-E            mass Erase dialog
      F8, Alt-A            set Alarms
      F9, Alt-X            check eXpired events


5.7. Find Dialog

      UNDO                 Exit
      ^ L arrow            case sensitive
      ^ R arrow            not case sensitive
      Alt-A                Alarm events
      Alt-C                Cyclic events
      Alt-D                Date events
      Alt-E                Expired events
      Alt-H                Holiday events
      Alt-N                Normal (non-holiday) events
      Alt-O                One-time events
      Alt-P                Positional events
      Alt-S                Skip-holiday events
      ^ space bar          clear importance flags
      F1                   reset event flags
      F2                   select events


5.8. Mass Erase Dialog

      UNDO                 Exit
      numbers 1-0, -, =    month buttons
      keypad 1-9, (, ), /  month buttons
      A                    erase All events
      F1, E                Erase events


5.9. Preferences Dialog

      UNDO                 Exit
      F1                   accept changes


5.10. Scan Dialog

      UNDO                 Exit
      HELP                 scan options alert
      numbers 1-0, -, =    first event in that month
      keypad 1-8           select event 1-8
      ^ 1-8                hide event 1-8
      Clr/Home             first event
      shift Clr/Home       last event
      L arrow              back one event
      R arrow              forward one event
      Up arrow             back one page
      Down arrow           forward one page
      F1, R                Reset event flags
      F2, F                Find dialog
      F3, P                Previous page
      F4, N                Next page


5.11. When Dialog

      UNDO                          Exit
      P, L arrow, U arrow, F1       Past
      F, R arrow, D arrow, F2       Future
      1-0                           go to date 1-10


5.12. Calshow Main Dialog

      UNDO, X            eXit
      HELP               wait for keypress
      B                  dateBook report
      D                  nn-Days quickview
      E                  coming Events report
      G                  Go!
      I                  toggle Importance filters
      L                  Locate Cal
      M                  Master list report
      P                  Preferences dialog
      S                  show Skipped events
      T                  Today quickview
      Alt-D              edit nn-Days number of days


5.13. Calshow Preferences Dialog

      UNDO               cancel
      A                  Accept
      E                  European date format
      I                  toggle Importance filters
      L                  Locate Cal
      O                  Once-per-day boot display
      P                  save Preferences
      R                  Revert to saved preferences
      S                  show Skip-holiday events


5.14. Calshow Command Line Parameters

      One of these switches required:

        -?           show this help (or '?' as first character)
        -V           coming events list
        -B           datebook output (-O or -P required)
        -M           master list (-O or -P required)

      Optional switches as desired:

        -Ofilespec   output filespec (not with -P)
        -P           output to printer (not with -O)
        -F           formfeed after (ignored except with -P)
        -Smmddyyyy   start date
        -Emmddyyyy   end date (ignored with -D)
        -Dnn         show next nn days (-V only; ignores -E)
        -Cfilespec   Cal location
        -Innnnnnnnnn show only these importance levels
        -#nnn        show nnn events max (ignored with -E)
        -Wnnn        wait nnn seconds after display
        -K           toggle show-skipped-events setting
        -U           toggle European dates setting (ddmmyyyy)
        -G           GEM mode (-V only; returns to dialog)

Example command lines:

Show the normal Coming Events listing, just as if you pressed the 'Go'
button in the Calshow dialog.

      -v-g

Show the coming-events listing for the next two weeks, in GEM mode. Return
to the Calshow dialog afterward. Pause for 30 seconds on each screen.

      -v-g-d14-w30

Save datebook-style output in a file named P:\DATEBOOK.PRT. The output
should start on September 1, 1992, and should show 31 days. Cal is located
in a subfolder named CAL on the D: drive.

      -b-op:\datebook.prt-s09011992-d31-cd:\cal\cal63.acc