Introduction

The Alarm agent manages time triggers and adds english extensions for time phrases to natural language parsers.

Time triggers can be installed, deleted, or modified by other agents, using OAA library trigger procedures; e.g.

oaa_AddTrigger(time,Condition, Action, Params),

oaa_RemoveTrigger(time, ...), and oaa_ReplaceTrigger(time, ...).

The Condition will be either a time_expr or a time_phrase, as explained below.

These library calls cause a time trigger to be installed (removed, replaced) in the Alarm agent. When the trigger fires, the Alarm agent then executes the specified Action.

Alternatively, OAA library data procedures can be used to manipulate the data solvable oaa_trigger(Id,time,Cond,Action,Params), on the alarm agent. (But this alternative is not usually needed, and will not be described here.)

Usage

To run the Alarm Agent under Unix, simply invoke the binary alarm, from the Unix command line, with no arguments. Under Windows, use alarm.exe.

In either case, make sure your setup.pl file contains the correct address (host and port) for a running facilitator (or give the address on the command line or environment variables).

Note: The following code samples would be used in implementing an agent in Prolog, by calling OAA Prolog library procedures such as oaa_AddTrigger and oaa_RemoveTrigger. Similar library procedures exist in the Java and C libraries, but procedure names and arguments may vary slightly, and additional code is needed to construct the input terms.

To set a time trigger, use syntax as shown in this example:

    oaa_AddTrigger(time,
        time_expr(date(98,4,13,13,29,19),date(98,4,13,13,29,19),recurrence(0,0)),
        oaa_Solve(notify('David Martin', []), []),
        [address(alarm)])

where time_expr() has three fields, a starting date-time, an ending date-time, and a recurrence value. Date-times are expressed as

       date(YEAR,MONTH,DAY,HOUR,MIN,SEC),

where YEAR would be 99 for 1999 and 101 for 2001, month is 0=January, 11 = December, and time is expressed using military time, where 13,24,01 is 1:24.01pm.

Recurrence is expressed as recurrence(0,0) if it's NOT recurring, and recurrence(NUM,UNIT) if it is, for instance recurrence(3, minute) to represent "every three minutes".

Note, time triggers manage their own recurrence as part of the trigger Condition and the recurrence parameter in the Param list (the fourth argument to oaa_AddTrigger (e.g. recurrence(when)) is ignored.

Usage with English Phrases

For convenience, the alarm agent also supports setting triggers using english phrases instead of time expressions, for instance:

    oaa_AddTrigger(time,
        time_phrase('in five seconds'),
        oaa_Solve(notify('David Martin', []), []),
        [address(alarm)])

    oaa_AddTrigger(time,
        time_phrase('every day at 2pm from now until Christmas'),
        oaa_Solve(notify('David Martin', []),[]),
        [address(alarm)])

Sample phrases include :

	On January 3rd
	Every thursday at two pm from now until xmas
	December 3, 2001
	This Monday
	Next Monday
	Last Monday
	The day after tomorrow
	On thursday at three thirty five pm
	At five oclock on December 3rd
	In the evening
	Every evening until December fifth

Note: clock-time expressions must be written out:

	At 4:30 pm  		% FAILS: time in this format not implemented yet.
	At four thirty pm    	% OK

Additional Usage Notes

Like 'comm' triggers, 'time' triggers MUST specify an address parameter, indicating which alarm agent to use. If you use [address(alarm)] and there is more than one alarm agent connected to the OAA community, the time trigger will be set multiple times, resulting in multiple firings. It's better to query first to make sure one or more alarm agents are present, perhaps using

	oaa_CanSolve(nl_time_expression(_,_), AddrList))

and then use an explicit address to pick just one agent to send the time trigger to.

When calling

oaa_RemoveTrigger(time,Condition, Action, Params),

it is normally best to use a variable for Condition, rather than trying to reproduce the Condition that was originally specified for the trigger. This is because the Condition (time expression) that's actually stored by the alarm agent may be expressed differently than the original, for recurrent triggers, or in cases where the original was a time_phrase.

For debugging and tracing purposes, it can be very useful to turn on tracing in the alarm agent. To do this, run the Debug agent, and click on "Trace all". Then edit the resulting ICL command, replacing the word "all" with the word "alarm" (so as to direct the trace command only to the alarm agent). Then press Enter to dispatch the command.

Known Bugs & Issues

Although the program is smart about days of the week (if it's Friday, 'next saturday' and 'this saturday' or 'saturday' are different, but 'next thursday', 'this thursday' and 'thursday' are the same), it's not smart about years (for instance, if it's September 2001, "January 1st" should mean Jan 1st 2002, but 2001 is returned instead) nor hour times ('at three thirty' probably means 'three thrity PM' but it will choose AM instead).
Time should be supported in numeric form: 4:38pm. Dates too: 11/24/01.
nl_sentence_ext() and nl_translate_ext() not tested because DCG_NL not currently shipped with this compiled in. When reinstated, adding the alarm agent automatically enhances DCG_NL's capabilities to parse sentences such as "In ten minutes, send mail to bob", correctly generating time triggers for this sentence type.
The time expression format, particularly for MONTH, is not very intuitive (MONTH is 0 based, so 0 = January, 11 = December), but this is what is used internally by Quintus Prolog so it's a pain to change.
In OAA 1.0, the alarm agent persisted data in a file, so that long running triggers would exist if you brought down the alarm agent and restarted it later. This functionality has been removed in this version of the agent, not because it's not useful but rather because it's so useful, it should be added as a general parameter option for all data predicates. However, when this is added to OAA 2.0, this agent will need to be updated to use a hook to grab loaded triggers at startup and then install all the time alarms (reinstating the restart_saved_triggers function that is commented out).
This agent's three solvables (documented on the Alarm Agent Overview Page) haven't been tested yet, because DCG_NL, at the time of this writing, doesn't make use of them.

Alarm Agent Overview Page