Additional Alarm documentation (2.09)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In addition to the "normal" user facilities of !Alarm as documented in the
User Guide, it is also possible for applications to set and receive alarms
by using some WIMP messages. These are as follows:

To set an application alarm, send the following message.

block+16     &500          indicate message to !Alarm
     +20     0/1           indicate set an alarm (1 if 5 byte format)
     +24     date/time
     +30     name of application sender, terminated by 0
     +n      application-specific unique alarm identifier, terminated by 0

Date & time must be given in standard 5 byte format if +20 is 1, otherwise
the layout is:

+24     year as low-byte/high-byte
+26     month
+27     date
+28     hour
+29     minutes

Neither the name nor the alarm identifier may be longer than 40 chars each.

To cancel the alarm, use the following message block:

block+16     &500          indicate message to !Alarm
     +20     2             indicate cancel an alarm
     +24     name of application, terminated by 0
     +n      application-specific unique alarm identifier, terminated by 0

The name & identifier must match exactly for the alarm to be successfully
cancelled. It is not necessary to specify the time of the alarm, as this may
have changed due to being deferred by Alarm.

If these messages are sent recorded, !Alarm will acknowledge with 0 if
successful, or a 0 terminated error string.

When an alarm goes off, the format of the block sent by !Alarm as a
broadcast is:

block+16     &501          indicate an alarm has gone off
     +20     name of application sender, terminated by 0
     +n      application-specific unique alarm identifier, terminated by 0

If the named application recognises the identifier, it must acknowledge this
message, otherwise !Alarm will ask the user to install the named
application. If the latter occurs, the alarm is deferred for one minute to
allow the application to be installed.

All alarms set are stored in <Alarm$Dir>.!Alarm. This is a data file
containing a linked list of alarms as follows:

PTR     Contents
~~~     ~~~~~~~~
0       PTR to first alarm, -1 if none set
5       PTR to first free space, -1 if none available
...
For each alarm or free space block:
n       PTR to next alarm/free space block, -1 if last
n+5     PTR to previous alarm/free space block, -1 if first
n+10    set alarm time stored as five byte format plus urgent flag (as a string)
n+17    alarm text
        contains 3 strings, each a maximum of 40 characters
        if a task alarm then the 3 strings are concatenated to form the command
        if an application alarm then string 1 is the task name
                                     string 2 is the unique indentifier
n+144   flags:
        bit 0 = application alarm
            1 = normal repeating alarm
            2 = task alarm
            3 = 5 day week
            4 = special repeating alarm
If a normal repeating alarm then
 n+145   repeat period:
         bit 0 = minutes
             1 = hours
             2 = days
             3 = weeks
             4 = months
             5 = years
 n+146   repeat multiplier (1 byte)
else
 n+145   bits 0 to 3: day in the week to repeat on (1-7)
         bits 4 to 7: offset within month          (0-5)
 n+146   number of months of skip                  (1-12)
endif
