Additional Alarm documentation (0.98)

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 a task 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 task sender, terminated by 0
     +n      task-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 task, terminated by 0
     +n      task-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 task sender, terminated by 0
     +n      task-specific unique alarm identifier, terminated by 0

If the named task 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 task 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 n+17 alarm text
        contains 3 strings, each a maximum of 40 characters
        if a task alarm then string 1 is the task name
                             string 2 is the unique indentifier
n+144 flags:
        bit 0 = task alarm
            1 = repeating alarm
n+145 repeat period:
        bit 0 = minutes
            1 = hours
            2 = days
            3 = weeks
            4 = months
            5 = years
n+146 repeat multiplier (1 byte)