Alarm Agent (alarm)
User Manual



Contents:


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)])
or
    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


Back to Alarm Agent Overview Page

Copyright (c) 2001 by SRI International