Open Agent Architecture (OAA)

Agent Library Reference Manual Version 2.0

The OAA Home Page is at: http://www.ai.sri.com/~oaa

Open Agent Architecture and OAA are trademarks of SRI International.

This document furnishes descriptions of the API provided by the libraries used to create components compliant with OAA 2.0. Descriptions and examples are given for both Prolog and Java versions of the library. Java programmers are referred to the JavaDoc-generated documentation for LibCom and LibOaa as it will provide additional language- and implementation-specific information.

Alphabetical Index

Glossary

Alphabetical Index

call_n
com_AddInfo
com_Connect
com_Connected
com_Disconnect
com_GetInfo
com_SendData
icl_BasicGoal
icl_BuiltIn icl_ConsistentParams
icl_ConvertSolvables
icl_GetParamValue
icl_GetPermValue
icl_GoalComponents
memberchk_nobind
oaa_AddData
oaa_AddDelayedContextParams
oaa_AddToCache
oaa_AddTrigger
oaa_CanSolve
oaa_CheckTriggers
oaa_ClearCache
oaa_ComTraceMsg
oaa_Declare
oaa_DelaySolution
oaa_Disconnect
oaa_GetEvent
oaa_Id
oaa_InCache
oaa_Inform
oaa_Interpret
oaa_IsConnected
oaa_LibraryVersion
oaa_MainLoop
oaa_Name
oaa_Ping
oaa_PostEvent
oaa_Ready
oaa_Redeclare
oaa_Register
oaa_RegisterCallback
oaa_RemoveData
oaa_RemoveTrigger
oaa_ReplaceData
oaa_ResolveVariables
oaa_ReturnDelayedSolutions
oaa_SetTimeout
oaa_Solve
oaa_TraceMsg
oaa_Undeclare
oaa_Version
remove_element
would_unify

com_Connect

Declaration

Prolog:	com_Connect(+ConnectionId, +Params, ?Address)
Java:	boolean comConnect(String connectionId, IclTerm params, IclTerm address)

Description

Connect a client agent to the Facilitator found at Address. Assign the value of ConnectionId as the name for this connection which is used to reference it in subsequent operations such as oaa_Disconnect and com_GetInfo.

The Java implementation returns true if the connection attempt was successful and false otherwise.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

Params is a list of IclTerms which provide additional information on how or where to connect to the Facilitator. At present, only one parameter is valid but the list will be extended on an as needed basis in future versions. This valid paramter is:

resolve_vars(T_F): If false, com_Connect will presume that the Address parameter is not an unitialized variable but contains an explicit connection address. No attempts will be made to fill-in Host and Port as described below. Default: true

Address may be either an explicit connection address for a Facilitator or an unitialized variable. The latter is most commonly used. Examples include tcp("test.ai.sri.com", "7576") and tcp(Host, Port).

If Address is an uninitialized variable and the resolve_vars parameter is T, com_Connect will determine values for Host and Port according to the following order of priority

Retrieve host and port from command line arguments
Example:
Retrieve this information from the environment variables OAA_HOST and OAA_PORT (Prolog only).
Use information found in the configuration file setup.pl. Entries must be of the form
For example
com_Connect() locates setup.pl by first looking in the local directory, then if not found, looks in the user's home directory.

Implementation

For successful connections, com_Connect() adds a new entry to a database maintained by LibCom, also called the InfoList. LibCom uses this database for managing the the set of connections, and for Java, a corresponding set of execution threads (one per connection). The database contains a key which identifies the connection (ConnectionId), a list of ICL Terms that describe the connection (e.g., status(connected), connection(8)), and a pointer to a buffer which is used for storing data received from the Facilitator for the client.

Examples

Java

    // First, connects to the facilitator
    if (!oaa.getComLib().comConnect("parent", 
         new IclStruct("tcp", new IclStr(inHostName), 
                              new IclInt(inPortNumber)), 
         (IclList)IclUtils.icl("[]"))) {
       System.out.println("Couldn't connect to " + inHostName + "," + inPortNumber);
       return false;
    }

Other examples appear under oaa_Register.

Remarks

A client agent may connect to only one Facilitator. The value for connectionId must be 'parent' or "parent" for the Prolog and Java implementations respectively. Future releases will support connections to multiple facilitators by a single client.

com_Connected

Declaration

Prolog:	com_Connected(?ConnectionId, ?Protocol, ?Type, ?Status)
Java:	TBD - resolve with existing com_Connected method

Description

Look-up information on a connection(s). If ConnectionId is a variable, return a list of current client-Facilitator connections and associated values for each of the above parameters. If ConnectionId is specified and represents a valid client-Facilitator connection, return values for Protocol, Type, and Status for this connection. If ConnectionId is specified and does not represent a valid client-Facilitator connection, com_Connected will fail.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

Protocol is a Prolog ICL atom or Java String that specifies the transport protocol supporting the given connection. At present, the only valid value is 'tcp.'

Type is a Prolog ICL atom or Java String that describes the endpoint of the connection. Values may be 'client,' 'server,' or 'child.'

Status is a Prolog ICL atom or Java String that describes the status of the connection. At present, the only valid value is 'connected.' If the connection is unconnected, the value will be null (Java) or uninstantiated (Prolog).

com_Disconnect

Declaration

Prolog:	com_Disconnect(+ConnectionId, +Params)
Java:	boolean comDisconnect(String connectionId, ICLTerm params)

Description

Shut down the connection between client agent and Facilitator as named by ConnectionId.

The Prolog implementation succeeds silently if there is not an open connection having the given id. The Java implementation returns true if the disconnection attempt was successful and false otherwise.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection. At present, the value must "parent" for the Java implementation, and be either 'parent' or its numeric connection identifier for the Prolog implementation.

Params is a list of IclTerms which indicate options for performing the disconnection. At present, only one parameter is recognized, TBD. It signals to the Facilitator that the client is temporarily disconnecting (e.g., robot out of range, or PDA temporarily off line). Future service requests received by the Facilitator for the disconnected client will be queued by the Facilitator and delivered upon reconnection.

Implementation

com_Disconnect() immediatly disconnects the client-Facilitator connection with no delays (e.g., remaining data on the connection is discarded) and removes the entry corresponding to ConnectionId from the LibCom database. For the Java implementation, com_Disconnect() also kills the thread of execution associated with this connection.

Remarks

It is strongly suggested that oaa_Disconnect be called directly rather than com_Disconnect() as the former performs other client clean-up activities necessary for proper shutdown of a client-Facilitator connection.

oaa_IsConnected

Declaration

Prolog:	oaa_IsConnected(+ConnectionId)
Java:	boolean oaaIsConnected(String connectionId)

Description

Determines whether the client-Facilitator connection at connectionId is valid and is connected. The Java implementation returns true if so and false otherwise.

Arguments

connectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

oaa_Disconnect

Declaration

Prolog:	oaa_Disconnect(+ConnectionId, +Params)
Java:	boolean oaaDisconnect(String connectionId, IclTerm params)

Description

Disconnect the connection between client agent and Facilitator at ConnectionId.

The Java implementation returns true if the connection exists and was disconnected, and false otherwise.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

Remarks

It is strongly suggested that oaa_Disconnect be called directly rather than com_Disconnect as the former performs other client clean-up activities necessary for proper shutdown of a connection.

oaa_Register

Declaration

Prolog:	oaa_Register(+ConnectionId, +AgentName, +Solvables, +Params)
Java:	boolean oaaRegister(String connectionId, String agentName, IclTerm solvables, IclTerm params)

Description

Register a client's name and capabilities declarations (solvables) with the Facilitator found at ConnectionId. This step is to be performed after a client agent successfully connects to a Facilitator agent using com_Connect().

The Java implementation returns true if registration was successful, or false if the connection between client and Facilitator is not open or if the registration otherwise fails.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection ('parent' for the Prolog implementation and "parent" for Java implementation).

AgentName is a symbolic name representing the agent, e.g., 'email'.

SolvableList is a list of capabilities or data definitions (solvables ) for this client. For example, [send(email,ToWhom,Params)].

Implementation

Note: the actions described below provide a view of how oaa_Register() is implemented; these are NOT actions for a client agent to perform separately.

The registration process involves handshaking (i.e., an exchange of messages) between the client and Facilitator. The client sends a message containing its name, OAA library version, and implementation language. The Facilitator returns information about itself including:

Facilitator name: symbolic name of the Facilitator
OAA version: version number of the agent library used to construct the facilitator
Language: facilitator's implementation language
Client address: an address for this client which contains a local id assigned by the Facilitator
Facilitator address: an address for the Facilitator to be used by this client

The client agent then provides its hostname (as retrieved from environment variable 'HOST') to the Facilitator using oaa_AddData(). As the last step in the registration process, the client declares its solvables to the Facilitator using oaa_Declare().

Examples

Prolog

% It is necessary to load the 'com' module before loading the 'oaa' module:
:- use_module(_Module, com_tcp, all).
:- use_module(oaa, all).

% a very simple agent
runtime_entry(start) :-
  com_Connect(parent, [], _Address),
  oaa_Register(parent, calendar, [appointment(_Person,_Date,_Time,_Appt)]),
  oaa_RegisterCallback(app_do_event, user:oaa_AppDoEvent),
  oaa_MainLoop(true).

oaa_AppDoEvent(appointment(Person,_Date,_Time,Appt), Params) :-
  format('Looking up the appointment for ~p.~n',[Person]),
  Appt = 'busy'.

oaa_RegisterCallback

Declaration


Prolog:	oaa_RegisterCallback(+CallbackId, +CallbackProc)
Java:	void oaaRegisterCallback(String callbackId, OAAEventListener callbackProc)

Description

Declare an application-defined method to be invoked by the LibOaa when a key, well-known event (CallbackId) occurs during execution.

The table below defines the set of well-known events, lists the interface definition for the Java method (Prolog is similar) which will be invoked when the event occurrs, and provides a description of the condition under which the callback is executed. User-defined callbacks need not be named as below in the Definition column, but they must support the listed set of arguments. Although each callback has the same argument list, not all will be used for every well-known event. The Description column will note which arguments will be used; those that are not will be null.

CallbackId Definition (Java) Description

app_init boolean oaa_AppInit(IclTerm goal, IclList params, IclList answers) Called when oaa_Register has completed successfully to signal registration of the client with the Facilitator. No arguments are used; all are null.

app_done boolean oaa_AppDone(IclTerm goal, IclList params, IclList answers) If the agent receives a "halt" event, the app_done callback is called before the agent exits. No arguments are used; all are null.

app_idle void oaa_AppIdle(IclTerm goal, IclList params, IclList answers) Executing the app_idle callback provides a way for LibOaa to pass control to a client after oaa_MainLoop has been executed. Control is passed when LibOaa is idle, such as during a timeout while waiting for an incoming communication event, or when a user-defined timeout has occurred (see oaa_SetTimeout). app_idle is useful only for Prolog which has a single thread of execution. No arguments are used; all are null.

app_do_event boolean oaa_AppDoEvent(ICLTerm goal, ICLList params, ICLList answers) app_do_event is called when a new ICL request has arrived for the client. Users may register either one callback for all new ICL requests, or one callback per solvable. The latter is done when declaring a solvable by using the "callback" parameter (see Declaring Solvables) of oaa_Register or oaa_Declare. All app_do_event parameters are used.

app_on_data_change void oaa_AppOnDataChange(ICLTerm goal, ICLList params, ICLList answers) app_on_data_change is called upon any data change event. Users may register either one callback for all data change events or one callback per event. The latter is done when publishing a data declaration by using the "callback" parameter (see Declaring Solvables) of oaa_Register or oaa_Declare.
Only the first argument will be used, the remaining two will be null. The first argument indicates the type of data change event that occurred and will be in the form:

removed(Data)
added(Data)
replaced(OldData, NewData)
defined(Data, Params)
redefined(Data, Params)
undefined(Data)

Arguments

CallbackId is a Prolog ICL atom or Java String that specifies the name of the well-known event for which a callback is being registered. See CallbackId column in the table above for the list of valid ids.

CallbackProc is the name of the Prolog procedure or Java method to be invoked when the event specified in CallbackId occurrs.

Examples

Prolog

% It is necessary to load the 'com' module before loading the 'oaa' module:
:- use_module(_Module, com_tcp, all).
:- use_module(oaa, all).

% a very simple agent
runtime_entry(start) :-
        com_Connect(parent, [], _Address),
        oaa_Register(parent, calendar, [appointment(_Person,_Date,_Time,_Appt)]),
  oaa_RegisterCallback(app_do_event, user:oaa_AppDoEvent),
        oaa_MainLoop(true).

oaa_AppDoEvent(appointment(Person,_Date,_Time,Appt), Params) :-
        format('Looking up the appointment for ~p.~n',[Person]),
        Appt = 'busy'.

Remarks

If a user-defined callback is not registered and the event is received, a warning message is printed to stdout.

oaa_ResolveVariables

Declaration

Prolog:	oaa_ResolveVariables(+VarList)
Java:	Not applicable. See Remarks below.

Description

Find values for arguments in VarList by looking in the command line arguments, environment variables, and setup file (setup.pl).

Arguments

VarList is a list of lists containing the arguments to resolve and an indication of how to resolve them. Sublists may contain elements in the following format:

env(EnvVar, Val)	Look for "EnvVar" in the environment variables
env_int(EnvVar, Val)	Look for "EnvVar" in the environment variables and return it as an integer
cmd(CmdVar, Val)	Look for "CmdVar " on command line
setup(File,SVar, Val)	Read SVar from setup file

Implementation

The first sublist that completely resolves provides the value for oaa_ResolveVariables.

Remarks

oaa_ResolveVariables is not applicable for non-console based applications such as Java or C-XWindows as these do not have access to environment variables (e.g., Java) or local files (e.g., Java applets).

Examples

Prolog

Resolve host and port by searching first the command line, then the environment variables, and lastly the setup file.

oaa_ResolveVariables([
  [cmd('-oaa_host',Host), cmd('-oaa_port', Port)],
  [env('OAA_HOST', Host), env_int('OAA_PORT', Port)],
  [setup('setup.pl',oaa_host, Host), setup('setup.pl',oaa_port, Port)]])

oaa_Ready

Declaration


Prolog:	oaa_Ready(+ShouldPrint)
Java:	void oaaReady(boolean shouldPrint)

Description

Tell the Facilitator that the agent has compleeted initialization and is ready to receive requests from the agent community. oaa_MainLoop() automatically calls oaa_Ready(), so only agents using other event loops (for instance XtMainLoop()) are required to call oaa_Ready() directly.

Arguments

ShouldPrint indicates whether or not to print 'Ready' to standard out.

Warning!

If oaa_Ready() is not called, either indirectly through oaa_MainLoop() or explicitly by the agent programmer, the agent will not receive any events because it's status with the Facilitator will not be updated to 'ready'.

oaa_MainLoop

Declaration

Prolog:	oaa_MainLoop(+ShouldPrint)
Java:	void oaaMainLoop(boolean shouldPrint)

Description

Initiate the event loop which controls execution for this client.

Arguments

ShouldPrint indicates whether or not to print 'Ready' to stdout.

Implementation

oaa_MainLoop first calls oaa_Ready, to let the Facilitator know that the agent is ready to receive events. Next, the main event loop for the application is run. It

Reads an event using oaa_GetEvent()
Executes the event using oaa_Interpret()
Checks for and fires any triggers registered expressing interest in this communication reception event.
Checks for and fires any application task triggers

If a timeout occurs waiting for an event (see oaa_SetTimeout), the app_idle callback is called.

Examples

Prolog

% It is necessary to load the 'com' module before loading the 'oaa' module:
:- use_module(_Module, com_tcp, all).
:- use_module(oaa, all).


% a very simple agent
runtime_entry(start) :-
        com_Connect(parent, [], _Address),
        oaa_Register(parent, calendar, [appointment(_Person,_Date,_Time,_Appt)]),
  oaa_RegisterCallback(app_do_event, user:oaa_AppDoEvent),
        oaa_MainLoop(true).

oaa_AppDoEvent(appointment(Person,_Date,_Time,Appt), _Params) :-
        format('Looking up the appointment for ~p.~n',[Person]),
        Appt = 'busy'.

com_SendData

Declaration

Prolog:	com_SendData(+ConnectionId, +Data)
Java:	boolean comSendData(String connectionId, String data)

Description

Cast data as a simple term, i.e., "term(Data).", and send it to the Facilitator named by ConnectionId.

The Java implementation returns false if the send attempt fails, otherwise it returns true.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

Data is the information to be sent.

Implementation

A single attempt to write data to the Facilitator at ConnectionID is made. com_SendData fails if the connection to the Facilitator does not exist (ConnectionId is invalid), or if the write attempt on a valid connection fails.

Remarks

It is intended that application developers use either oaa_Solve to request a solution to a stated goal, or oaa_PostEvent to send a low-level event to the Facilitator. DO NOT use com_SendData unless you are developing equivalent functions to those provided by LibOaa and therefore require direct data transport services.

com_AddInfo

Declaration

Prolog:	com_AddInfo(+ConnectionId, +NewInfo)
Java:	boolean comAddInfo(String connectionId, IclTerm newInfo)

Description

Add NewInfo to the database entry for the client connection described by ConnectionId. If NewInfo already exists in the database for this client, update its value instead.

The Java implementation returns true if the entry was successfully added and false otherwise.

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

NewInfo is a Prolog ICL Term or a Java String which contains one or more elements to be stored for this client such as status(S), type(T), or protocol(P); e.g., "status(connected), protocol(tcp)".

com_GetInfo

Declaration

Prolog:	com_GetInfo(+ConnectionId, +Info)
Java:	IclTerm comGetInfo(String connectionId, IclTerm info)

Description

Find and return information associated with Info stored in the client database for the connection named ConnectionId.

The Prolog implementation returns an empty ICL Term if ConnectionId is invalid or if Info is not found in the dataset. Otherwise, it returns an ICL Term with the result(s).

The Java implementation returns null if connectionId is invalid or if Info is not found in the dataset. Otherwise, it returns an IclTerm instance containing the result(s).

Arguments

ConnectionId is a Prolog ICL atom or Java String that specifies the name of the Facilitator connection.

Info is a Prolog ICL Term or a Java String which contains one or more elements to look-up in the list of data for the client. Possible values of Info to search for include status(S), type(T), protocol(P), or others defined by the client. Placeholder values such 'S,' 'T,' and 'P' are ignored and real values are returned in an ICL Term.

oaa_PostEvent

Declaration

Prolog:	oaa_PostEvent(+Body, +Params)
Java:	void oaaPostEvent(IclTerm inBody, IclTerm inParams)

Description

Send a single low-level event message to another agent.

Arguments

Body is an IclTerm which contains the event to be sent.

Params is a list of parameters which provide additional information regarding the event or its handling. The Params list may include:

priority(P): P ranges from 1 (low priority) to 10 (high priority) with a default of 5.
flush_events: Will flush (dispose of) all events of lower priority currently queued at the destination agent. These events are lost, and will not be executed. This parameter should be used with caution!
address(Addr): The full address of the destination agent for the event. Addr must be an agent address, not a symbolic name. If caller is a client agent, the only meaningful address is that of the client's facilitator.
from(Id): The address Id of the originating agent.

Events

An event is comprised of a body and a set of parameters. In "ev_connect(AgentInfoList)" the body is "ev_connect" and "AgentInfoList" is its single parameter.

Below is a list and brief description of the events that are defined by the agent library for all agents. For more detailed information about events, please see the chapter on Events in the Developer's Guide.

Note that this table is not complete with respect to the implementation. It is TBD to add the other events and, for each, describe the context in which it is used and any parameters for it.

Event Description

ev_trace_on Turns tracing mode on

ev_trace_off Turns tracing mode off

ev_debug_on Turns debug_mode on (Prolog only)

ev_debug_off Turns debug_mode off (Prolog only)

ev_com_trace_on Turns COM-level tracing on

ev_com_trace_off Turns COM-level tracing off

ev_halt Shuts down the agent

ev_set_timeout(N) Changes the current timeout value to N

ev_solve(GoalId, Goal, Params) Requests that the agent attempt to solve Goal augmented by Params. GoalId is an identifier assigned by the library (LibOAA) for this goal.

Remarks

oaa_PostEvent is generally used within other LibOaa methods such as oaa_Solve and infrequently used directly by client agent implementors. A common use when called directly is to turn debugging on and off for a remote agent using "ev_com_trace_on" and "ev_com_trace_off" respectively as the Body.

oaa_SetTimeout

Declaration

Prolog:	oaa_SetTimeout(+NSecs)
Java:	Not applicable. See Remarks below.

Description

Set the timeout value used by oaa_GetEvent to the requested number of seconds. If no event arrives in the time specified by the timeout value, oaa_GetEvent returns the 'timeout' event. In this case, oaa_MainLoop will call the application callback registered for the app_idle CallbackId as defined using oaa_RegisterCallback.

Arguments

NSecs is a decimal number of seconds and fractional seconds to wait before generating the timeout event. The default timeout value which is also the infinite timeout value is 0. When set to this, oaa_GetEvent will block forever until an event arrives (i.e., no timeout).

Remarks

oaa_SetTimeout and timeout values in general are only useful for console-based agent libraries, such as Prolog or the console-based C library. The Java library or windows-based C libraries use threads or other mechanisms to detect input on communication streams without impacting the execution of the main program. Other mechanisms in these languages (e.g. timers in Java) can be used to perform the timeout service implemented by oaa_SetTimeout.

oaa_GetEvent

Declaration

Prolog:	oaa_GetEvent(+LowestPriority, +PollUntilEvents, -Body, -Params)
Java:	Not applicable. See Remarks below.

Description

Return the next event to execute, and the parameters associated with the event. If a timeout value has been set by oaa_SetTimeout (for console-based agent libraries), and no event arrives or is in the event queue by the specified time, the 'timeout' event is returned.

Arguments

LowestPriority is a numeral from 1 (low priority) to 10 (high priority), with 5 being the default priority. oaa_GetEvent returns the first event in the queue which has a priority greater than LowestPriority.

PollUntilEvents is a list of events that should be returned regardless of priority. Use the empty list "[]" to indicate no specific preference or priority (i.e., return an event according to the LowestPriority rule).

Body is a return parameter which is filled-in by oaa_GetEvent with the new event.

Params is a return parameter containing a list of parameters which provide additional information regarding the new event. See the Params description in oaa_PostEvent for the possible values.

Implementation

oaa_GetEvent keeps a queue of incoming events. When oaa_GetEvent() is called any waiting events are read from the input stream and added to the current event queue; the queue is then sorted according to priority, and the the first event in the queue which has a priority greater than the requested LowestPriority parameter is returned.

If the debug flag ComTraceOn has been set for the agent, a trace message describing the arriving event is displayed.

Remarks

In the Java implementation, oaa_GetEvent is private. It is executed within oaa_MainLoop to read an incoming event. The event is delivered to the application by calling the procedure registered for the app_do_event callback.

oaa_Declare

Declaration

Prolog:	oaa_Declare(+Solvables, +CommonPermissions, +CommonParams, +Params, -DeclaredSolvables)
Java:	IclTerm oaaDeclare(IclTerm solvable, IclTerm initialCommonPerms, IclTerm initialCommonParams, IclTerm initialParams)

Description

Register the declaration of new procedure or data solvables for a client or facilitator on its parent facilitator. Inform the parent facilitator of the declaration if the client agent that is registering is a leaf agent.

The Java implementation returns an IclTerm which contains a list in standard form of all solvables successfully declared. The Prolog implementation achieves this through the return parameter DeclaredSolvables.

Arguments

Solvables is a single solvable or a list of solvables, in shorthand or standard form.

CommonPermissions is a list of permissions to be distributed to each solvable in Solvables.

CommonParams ia a list of parameters to be distributed to each solvable in Solvables.

Params may be an empty list or include one or more of the following:

address(X): Where the solvables will exist. X may be either 'self,' 'parent,' or 'facilitator.' Default: 'self'.
if_exists(X): What to do when declaring solvables for self, and some already exist. X may be 'overwrite' or 'append'. 'overwrite' means to discard all existing solvables and replace them with the list provided in Solvables. 'append' means to add the new solvables to the end of the existing solvables list and update any existing solvables with new values provided in Solvables. Default: 'append'.

DeclaredSolvables (Prolog only) is a return parameter containing a list in standard form of all solvables successfully declared.

Declaring Solvables

Solvables are used to define actions or capabilities of an agent (procedure solvables). Solvable declarations are also used to define public data declarations (data solvable). They have a goal part, a list of parameters describing the goal, and a list of permissions for the goal. "Standard form" is written as solvable(Goal, Parameters, Permissions). A number of shorthand forms also exist. Each element can be solvable/3 (Standard form), or solvable(Goal, Params), or solvable(Goal), or just Goal. Here are examples of several ways of defining solvables:

solvable(d(X), [type(data), bookkeeping(true)], [write(true)])
solvable(a(X), [test(check(X))], [])
(a(X) :- check(X)).
a(X)

A boolean parameter with value true can omit the value specification. For example, the parameter lists [bookkeeping(true)] and [bookkeeping] are equivalent.

Parameters

The following parameters may be used when declaring procedural (executable) solvables (listed with default values):

utility(Value) [5] : how "good" at performing the service an agent is. Integer value from 1-10.
type(Data_Procedure) [procedure] : whether solvables is data declaration or procedure solvable.
callback(Functor) [no default] : a local function to call when an incoming request arrives that matches the solvable.
test(TestExpr) [true] : a test expression that the Facilitator evaluates before sending a request to an agent. TextExpr is written in Prolog.
synonym(SynonymHead,RealHead) [no default] : a one-way mapping between one goal and an equivalent form of the goal.

Data solvables (where type(data) is specified) add some additional parameters:

single_value(T_F) [false] : if true, at most one value is present for a data solvable.
unique_values(T_F) [false] : if true, at most one copy of each value is stored.
private(T_F) [false] : if true, solvable only defined locally and not published to Facilitator.
bookkeeping(T_F) [true] : if true, records owner and modification time for each value of the data solvable
persistent(T_F) [false] : if true, data lives beyond the lifespan of the agent which created it. Otherwise, when an agent exits, all of its data is automatically cleaned up.
rules_ok [false] : if true, allows full prolog rules to be stored as data.
if_exists [append] : What to do when declaring solvables for self, and some alreay exist. May be 'append' or 'overwrite'.

Permissions

For the moment, solvable permissions are very simple. Here is the complete list:

call(T_F) [true for procedures, false for data]: Whether the solvable can be executed by other agents.
read(T_F) [false]: Whether data can be read by other agents.
write(T_F) [false]: Whether data can be written by other agents.

Implementation

Client-requested facilitator solvables automatically acquire the permission write(true), and the parameters type(data), rules_ok(false), private(false), and bookkeeping(true).

The CommonPermissions and CommonParams arguments are provided purely for programming convenience. The effect of including an item in these is no different than if that item were explicitly included in the permissions or params list of each element in Solvables.

If called by a leaf or node agent, this procedure assumes the agent is already registered with a parent facilitator.

An attempt to declare a solvable that unifies with (matches) an existing solvable will cause a warning to be printed on standard output of the agent where the solvable exists. In addition, this solvable will not be included in DeclaredSolvables. Use oaa_Redeclare for this purpose.

oaa_Undeclare

Declaration

Prolog:	oaa_Undeclare(+Solvables, +Params, -UndeclaredSolvables)
Java:	IclTerm oaaUndeclare(IclTerm Solvable, IclTerm InitialParams)

Description

Remove an agent's solvables from a client or facilitator, or remove writable data solvables that exist on the parent facilitator. Inform the parent facilitator of the deletion if the client agent that is registering is a leaf agent.

Arguments

Solvables is a single solvable or a list of solvables, in shorthand or standard form. If a solvable is in standard form, only the goal is considered in selecting the solvables to be removed (permissions and parameters are ignored).

Params may be an empty list or include one or more of the following:

address(X): Where the solvables exist. X may be either 'self,' 'parent,' or 'facilitator.' Default: 'self'.
remove_data(T_F): If true, remove all facts for each data solvable in Solvables. Default: false.

UndeclaredSolvables (Prolog only) is a return parameter containing a list in standard form of all solvables successfully removed.

Implementation

If called by a leaf or node agent, this procedure assumes the agent is already registered with a parent facilitator.

An attempt to remove a non-existent solvable will cause a warning to be printed on standard output of the agent where the solvable was supposed to exist. In addition, this solvable will not be included in UndeclaredSolvables.

oaa_Redeclare

Declaration

Prolog:	oaa_Redeclare(+Solvable, +NewSolvable, +Params)
Java:	void oaaRedeclare(IclTerm InitialSolvable, IclTerm InitialNewSolvable, IclTerm InitialParams)

Description

Replace a solvable on a client or facilitator. Inform the parent facilitator of the declaration if the client agent that is registering is a leaf agent.

Arguments

Solvable is a single solvable, in shorthand or standard form. If the solvable is in standard form, only the goal is considered in selecting the solvable to be replaced (permissions and parameters are ignored).

NewSolvable is a single solvable, in shorthand or standard form.

Params may be an empty list or include one or more of the following:

address(X): Where the solvable exists. X may be either 'self,' 'parent,' or 'facilitator.' Default: 'self'.
remove_data(T_F): If true, and Solvable is of type 'data', remove all its assertions. Default: false.

Description

The effect of this procedure is the same as a call to oaa_Undeclare with [Solvable] as its first argument, followed by a call to oaa_Declare with [NewSolvable] as its first argument, except that this procedure guarantees the replacement of Solvable by NewSolvable will be treated as a single operation. That is, no events can be processed between the removal of Solvable and the installation of NewSolvable.

If called by a leaf or node agent, this procedure assumes the agent is already registered with a parent facilitator.

An attempt to replace a non-existent solvable will cause a warning to be printed on standard output of the agent where the solvable was supposed to exist. In addition, the new solvable will not be installed.

Prolog library: This procedure fails if the operation cannot be completed.

oaa_Solve

Declaration

Prolog:	oaa_Solve(+Goal, +InitialParams)
Java:	boolean oaaSolve(IclTerm goal, IclList params, IclList answers)

Description

Request that Goal be solved by one or more agents and the resulting solution(s) returned.

For the Prolog implementation, the solutions are returned by the usual means of unification and backtracking. For the Java implementation and other languages, solutions are returned in a list (the parameter answers).

If no results are available or the agent is not connectected to the Facilitator, the list will be empty and oaa_Solve will return false (Java). If one or more result is available, the list will contain them and oaa_Solve will return true (Java).

It is important to note that requesting a solution does not require that the agent specify or even know of a particular agent to handle the call. While it is possible to specify one or more agents to handle a call (and there are situations in which this is desirable), in general, it is advantageous to leave this delegation task to the Facilitator.

Arguments

Goal is a description of the service (e.g. an action or query) desired. Each goal contains calls to one or more solvables. An example of a a goal is "get_message(MessageNum, Msg)."

Params is a list of 0 or more of the following parameters which are used to qualify how the goal is to be achieved and how results are to be returned.

cache(T_F): Cache all solutions locally in an internal agent database. If good solutions already exist in the cache, use the local values instead of making a distributed request. Default: false.
level_limit(N): Highest number of hierarchical levels to climb for solutions.
address(Addr): Send the request to a specific agent or agents. Addr may be either a symbolic name, or a full address. In addition, for convenience, reserved terms 'self', 'parent', and 'facilitator' may also be used. If Addr is 'self', the agent will solve the goal locally. If no address is specified, solution of the request will be delegated to the Facilitator and routed to agents who have declared that solvable.
reply(Mode): If 'true', reply desired. If 'none', no reply needed. Default: true, except when the call to oaa_Solve is a trigger action, in which case it is none. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
blocking(T_F): If 'true', execution blocks until the solutions are received from the Facilitator. If 'false', execution continues immediately. In this case, the reply events (ev_reply_solved, ev_reply_declared, ev_reply_data_updated, ev_reply_ trigger_updated) can be handled in app_do_event callback. Default: true, except when the call to oaa_Solve is a trigger action, in which case it is false. Note that reply(none) overrides blocking(true).
solution_limit(N): Limits the maximum number of solutions found to N.
time_limit(N): Waits a maximum of N seconds before returning (failure if no solution found in time).
context(C): Passes a context value through any subsequent solves to logically identify them with this solve request. 'C' is any ICL atom or Java String chosen by the programmer.
parallel_ok(T_F): If 'true' (default), multiple agents that can solve the Goal will attempt to work on it in parallel. If 'false', one agent will be selected at a time to solve the goal, until the maximum number of requested solutions (see solution_limit) is found.
reflexive(T_F): If `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
priority(P): P ranges from 1 (low priority) to 10 (high priority) with a default of 5.
flush_events(T_F): Will flush (dispose of) all events of lower priority currently queued at the destination agent. These events are lost, and will not be executed. This parameter should be used with caution! Default: false.
get_address(X): Return a list of addresses of agents that were asked to solve the goal, or one of its subgoals. Upon return from oaa_Solve, "X" is replaced with the list of address for agents to which the request was sent.
get_satisfiers(X): Return a list of addresses (ids) of agents that succeeded in solving the goal, or one of its subgoals. Upon return from oaa_Solve, "X" is replaced with the list of addresses who satisfied the request.
strategy(S): Shorthand for certain combinations of the above parameters. S is one of:
- query = [parallel_ok(true)]
- action = [parallel_ok(false), solution_limit(1)]
- inform = [parallel_ok(true), reply(none)]
Default: query.

Remarks

The cache() parameter must be used with care, as the agent is responsible for maintaining the coherency of his own cache. If a solution is subject to change over time, it is safer to omit the cache parameter.

Note that certain combinations of parameters are inconsistent, and are handled as follows:

reply(none) overrides blocking(true)
reply(none) overrides parallel_ok(false)

All of the above parameters may be used in the "global" parameter list (the second argument to oaa_Solve), when Goal is non-compound. Most can be used in the global list with compound goals. Some of these parameters can also be used in the NESTED parameter lists of compound goals. Uses of these parameters with compound goals are documented elsewhere.

oaa_DelaySolution

Declaration

Prolog:	oaa_DelaySolution(+Id)
Java:	void oaaDelaySolution(String Id)

Description

oaa_DelaySolution is to be called from within a callback procedure for app_do_event. It indicates that solutions to the current goal will not be returned until an explicit call to oaa_ReturnDelayedSolutions vs being returned at the time of the completion of the callback.

The Java implementation returns false if the specified Id is not unique among currently delayed goals.

Arguments

Id is an ICL atom or Java String which will be used to later match solutions to the request.

Examples

Prolog

% when a move request comes in, start the robot moving
%    and delay sending back success or failure until the
%    robot achieves the position (or not).
oaa_AppDoEvent(move(robot, pos(X,Y)), _Params) :-
   start_robot_to(X,Y),
   oaa_DelaySolution(robot_move).

% The robot sends an event that it has achieved the position, so
%    send back an answer to the original request.
oaa_AppDoEvent(moved(robot, pos(X,Y)), _Params) :-
   oaa_ReturnDelayedSolutions(robot_move, [move(robot, pos(X,Y))]).

oaa_ReturnDelayedSolutions

Declaration

Prolog:	oaa_ReturnDelayedSolutions(+Id, +SolutionList)
Java:	boolean oaaReturnDelayedSolutions(int Id, IclTerm SolutionList)/TD>

Description

Return the list of solutions for a delayed request.

The Java implementation returns false if Id can't be found.

Arguments

Id is an ICL atom or Java String Id previously passed to oaa_DelaySolution().

SolutionList is a list of solutions for a goal accumulated since the oaa_DelaySolution() was issued. Each member of the solution list must unify with the original request. The empty list signifies failure in achieving the goal.

Examples

See example under oaa_DelaySolution

oaa_AddDelayedContextParams

Declaration

Prolog:	oaa_AddDelayedContextParams(+DelayId, +Params, -NewParams)
Java:	boolean oaaAddDelayedContextParams(int Id, IclTerm Params, IclTerm NewParams)

Description

Concatenate context parameters from a goal which has been delayed to a parameter list to be subsequently used in an outgoing oaa_Solve request. Because an agent can concurrently manage multiple delayed goals, this procedure is used to identify the specific goal to which the context parameters are to be added and then adds them.

The Java implementation returns true if TBD, and false if TBD.

Arguments

Id is an ICL atom or Java String Id previously passed to oaa_DelaySolution().

Params may be an empty list or include one or more parameters for the new goal to be solved by a soon-to-be-issued oaa_Solve request.

NewParams is the complete list of parameters including both the context parameters from the delayed goal and any new parameters (from Params above).

Examples

Prolog

oaa_AppDoEvent(goal(_X),_Params) :-  
   oaa_DelaySolution(a_goal).

oaa_AppDoEvent(temp_event(Y),_Params) :-
   oaa_AddDelayedContextParams(a_goal, [], P),
   oaa_Solve(sub_goal(Y), P).

oaa_AppDoEvent(final_event(S), _Params) :-
   oaa_ReturnDelayedSolutions(a_goal, [goal(S)]).

oaa_Interpret

Declaration

Prolog:	oaa_Interpret(+ICLExpression, +Params)
Java:	boolean oaaInterpret(IclTerm expression, IclList params, IclList inSolutions)

Description

Interpret an incoming request by first checking if ICLExperssion is a builtin event that is automatically handled by the agent library. If not, pass it to the the app_do_event callback defined for the event.

In Prolog, success, failure and multiple solutions are represented using standard Prolog semantics. In Java, solutions are returned using the return parameter inSolutions. Failure is represented as the empty list "[]." Success is indicated by a list containing one or more solutions to a goal. A single solution example is "[test(succeeds)]" as the result for oaa_Interpret(test(X), []). A multiple solution example is "[a(1), a(2), a(3)]" as the result for oaa_Interpret(a(X), []).

The Java implementation returns false if expression is "false," "fail," or a variable (in the Prolog definition, i.e., leading '_' or capital letter). It returns true otherwise.

Arguments

ICLExpression is a builtin or user defined event.

Params is a list of parameters which provide additional information regarding the event. The contents of Params will vary depending on context. When oaa_Interpret is called on an incoming event, Params will (usually) include from(Sender). Calls generated internally may contain from(self). Additional params may accumulate through recursive calls to oaa_Interpret.

inSolutions (Java only) is a list of 0 (the empty list "[]") or more solutions that are the result from interpreting ICLExperssion.

Implementation

oaa_Interpret implements a simple meta-interpreter for executing complex goals. It is generally used within other LibOaa methods such as oaa_Solve or for the firing of triggers, and infrequently used directly by client agent implementors.

In the Prolog agent library, oaa_Interpret() is capable of handling complex events (e.g. (A, B ; C)) as well as all Prolog builtin primitives. For the moment, in Java (and other languages), only simple events may be interpreted.

oaa_AddData

Declaration

Prolog:	oaa_AddData(+Clause, +Params)
Java:	boolean oaaAddData(IclTerm clause, IclList params)

Description

Add a new fact for a data solvable to a publicly writable or private data solvable of this agent, or to a publicly writable data solvable of another agent.

Both the Prolog and Java implementations of this procedure always succeed (the Java implementation always returns true). Success or failure of the operation can be ascertained by using the get_satisfiers parameter in the request to determine which agents actually completed the request.

Arguments

Clause is the fact to be added to the list of existing data elements for this agent.

Params is a list of 0 or more of the following parameters which are used to qualify where or how the data is to be added.

address(Addr): a list including 'self,' 'parent,' 'facilitator,' and/or the symbolic names or full addresses of other client agents. If no address is specified, the request will be delegated to the Facilitator and routed to agents who have declared that data solvable.
reflexive(T_F): If `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
at_beginning(T_F): If true, add Clause at the beginning of the list of existing data elements. If false, add Clause at the end. Default: false.
single_value(T_F): If true, all clauses for this predicate are removed before adding the new clause. Default: false.
unique_values(T_F): If true, at most one copy of each value is stored. Default: false.
owner(LocalId): If bookkeeping(true) for this solvable, record LocalId as the owner. Default: record the Id for the agent from which the request originated.
get_address(X): Return a list of addresses (ids) of agents that were sent the request. Upon return from this procedure, "X" is replaced with the list of address to which the request was sent.
get_satisfiers(X): Return a list of addresses (ids) of agents that successfully completed the request. Upon return from this procedure, "X" is replaced with the list of addresses who satisfied the request.
reply(Mode): If 'true', generate a reply message when data is being added on a remote agent or agents. If 'none', no reply needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
blocking(Mode) : If true, block until the reply arrives. If false, don't block. In this case, the reply events (ev_reply_data_updated) can be handled in the app_do_event callback. Default: true. Note that reply(none) overrides blocking(true).

Remarks

At present, Clause may be considered synonmous with fact. In future versions of the OAA library, it will be possible to add, remove, or replace rules in addition to facts, hence the use of the more general name for this argument

As a result of adding data, triggers may be fired if any exist where the condition for the trigger matches Clause.

oaa_RemoveData

Declaration

Prolog:	oaa_RemoveData(+Clause, +Params)
Java:	boolean oaaRemoveData(IclTerm clause, IclList params)

Description

Remove an existing fact for a data solvable from a publicly writable or private data solvable of this agent, or from a publicly writable data solvable of another agent.

Arguments

Clause is the fact to be removed from the list of existing data elements for this agent.

Params is a list of 0 or more of the following parameters which are used to qualify where or how the data is to be removed.

address(X): A list including 'self,' 'parent,' 'facilitator,' and/or the symbolic names or full addresses of other client agents. If no address is specified, the request will be delegated to the Facilitator and routed to agents who have declared that data solvable.
reflexive(T_F): If true, the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
do_all(T_F): If true, removes all predicate values that match the Clause. Default: false (removes only the first matching fact)
get_address(X): Return a list of addresses (ids) of agents that were sent the request. Upon return from this procedure, "X" is replaced with the list of address to which the request was sent.
get_satisfiers(X): Return a list of addresses (ids) of agents that successfully completed the request. Upon return from this procedure, "X" is replaced with the list of addresses who satisfied the request.
reply(Mode): If 'true', generate a reply message when data is being removed on a remote agent or agents. If 'none', no reply needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
blocking(Mode) : If true, block until the reply arrives. If false, don't block. In this case, the reply events (ev_reply_data_updated) can be handled in app_do_event callback. Default: true. Note that reply(none) overrides blocking(true).

Remarks

As a result of removing data, triggers may be fired if any exist where the condition for the trigger matches Clause.

oaa_ReplaceData

Declaration

Prolog:	oaa_ReplaceData(+Clause1, +Clause2, +Params)
Java:	boolean oaaReplaceData(IclTerm clause1, IclTerm clause2, IclList params)

Description

Replace an existing fact for a data solvable from a publicly writable or private data solvable of this agent, or from a publicly writable data solvable of another agent. This is done by first removing a data element that matches Clause1, and then adding Clause2.

Arguments

Clause1 is the fact to be removed from the list of existing data elements for this agent.

Clause2 is the new fact to be added to the list of existing data elements for this agent.

Params is a list of 0 or more of the following parameters which are used to qualify where or how the data is to be replaced.

address(X): a list including 'self,' 'parent,' 'facilitator,' and/or the symbolic names or full addresses of other client agents. If no address is specified, the request will be delegated to the Facilitator and routed to agents who have declared that data solvable.
reflexive(T_F): If true, the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
do_all(T_F): If true, replaces all predicate values that match Clause1 Default: false (removes only the first)
at_beginning(T_F): If true, add Clause2 at the beginning of the list of existing data elements. If false, add Clause2 at the end. Default: false. Note that this parameter is applied only if do_all is false.
owner(LocalId): if bookkeeping(true) for this solvable, record LocalId as the owner of Clause2. Default: the agent from which the request originated.
get_address(X): Return a list of addresses (ids) of agents that were sent the request. Upon return from this procedure, "X" is replaced with the list of address to which the request was sent.
get_satisfiers(X): Return a list of addresses (ids) of agents that successfully completed the request. Upon return from this procedure, "X" is replaced with the list of addresses who satisfied the request.
reply(Mode): If 'true', generate a reply message when data is being removed on a remote agent or agents. If 'none', no reply needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
blocking(Mode): If true, block until the reply arrives. If false, don't block. In this case, the reply events (ev_reply_data_updated) can be handled in app_do_event callback. Default: true. Note that reply(none) overrides blocking(true).

Remarks

The effect of this call is the same as that of a call to oaa_RemoveData, followed by a call to oaa_AddData. The difference is that the implementation of oaa_ReplaceData is guaranteed to be atomic; that is, for each agent that is affected by the call to oaa_ReplaceData, nothing can read or write that agent's data store between the occurrence of the replace and add operations.

Clause1 and/or Clause2 may be synonym terms. A synonym is a derived view (in relational database terminology) of an underlying data fact. I.e., one may use synonyms for either or both of Clause1 and Clause2 to affect the replacement of the underlying data. For example, if an agent has declared a data solvable "a(X)" that has three values in its database, a(1), a(2), and a(3), and has also declared b(X) to be synonomous with a(X), you can use oaa_ReplaceData() on b

   oaa_ReplaceData(b(2), b(20), [])
   oaa_Solve(a(X), [])
   Yields       X = 1
                X = 3
                X = 20

Clause1 and Clause2 are not required to have the same functor. Thus, oaa_ReplaceData(a(X), b(X), [do_all(true)]) is a valid request.

Clause1 and Clause2 may share variables. For oaa_ReplaceData(a(X), b(X), [do_all(true)]), "[a(1), a(2), a(3)]" will be replaced with "[b(1), b(2), b(3)]".

As a result of removing Clause1 and adding Clause2, triggers may be fired if any exist where the condition for the trigger matches either or both of Clause1 and Clause2.

oaa_AddTrigger

Declaration

Prolog:	oaa_AddTrigger(+Type, +Condition, +Action, +InitialParams)
Java:	boolean oaaAddTrigger(IclStr Type, IclTerm Condition, IclTerm Action, IclList InitialParams)

Description

Install a trigger on one or more agents which may include self, parent, Facilitator, or remote peer agents as specified by the Parameters.

Arguments

Type is either "comm," "data," "task," or "time."

Condition is a template that specifies under what circumstances the trigger should fire.

For a comm trigger, Condition should have the form: event(FromToAgtId, Content, Params) and be unifiable with some event that is expected to be sent or received by each agent on which the trigger is to be installed.
For data triggers, Condition should have the form data(Item,Data) and be unifiable with a data solvable of each agent on which the trigger is to be installed
For task triggers, Condition is an ICL expression (usually a call of a solvable) that can be interpreted on each agent on which the trigger is installed.
For time triggers, Condition should be in the form: time_expr(FromDateTime, ToDateTime, Recurrent) where FromDateTime and ToDateTime are in the form date(Year,Month-1,Day,Hr,Min,Sec) and Recurrent has the form recurrent(Value,Unit). If the trigger is not a recurrent trigger, the Recurrent field should contain recurrent(0,0).

Action is an ICL expression that defines what is to be executed when the trigger fires which is interpreted once the condition(s) of the trigger have been met. At present, the ICL expression must be a simple goal expressed as either oaa_Solve(Goal, Params) or oaa_Interpret(Goal, Params). In future versions, Action may be a complex goal in the form of (goal1, (goal2 ; goal3), goal 4).

Params may be an empty list or include one or more of the following:

address(X): an optional parameter which specifies an address to which the trigger will be added. X is a list including 'self', 'parent,' 'facilitator,' and/or the symbolic names or address(es) of other client agent(s). Its default value depends on the trigger type.
- For task triggers, the trigger will be installed on all agents with solvables matching the trigger Condition.
- For data triggers, the trigger will be installed on all agents with data solvables matching the trigger Condition. This may include the Facilitator agent, which declares several data solvables.
- Comm triggers should contain the address() parameter specifying on which agent to install the trigger. If no address parameter is given, the default will be 'self', or the local agent.
- Time triggers (and any other user defined trigger types) must contain the address() parameter specifying on which agent to install the trigger. There is no default behavior, so the trigger installation will fail if no address if given.
test(T): specifies an ICL expression T which must succeed in order for the trigger to fire (in addition to a successful match of the trigger's condition and/or its on parameter).
on(Operation): Restricts under what circumstances a trigger is to be selected for firing. Is valid for comm and data triggers, but invalid for task or time triggers (if provided, it is ignored).
- For a comm trigger, Operation may be "receive," "send," a list containing both of these, or a variable. The use of a variable has the same effect as a list containing both send and receive.
- For a data trigger, Operation may be "add," "remove," a list containing both of these, or a variable. The use of a variable has the same effect as a list containing both add and remove.
- This parameter is ignored for time and task triggers because their type implies the operation (i.e., count down a timer, execute a task).
recurrence(R): specifies the duration of the trigger. R may be a positive integer representing the maximum number of times the trigger should fire, 'whenever' meaning the trigger is in effect permanently, or 'when' indicating that the trigger fires once and is automatically removed. The default value is 'when.'
get_address(X): Return a list of addresses (ids) of agents that were sent the request. Upon return from this procedure, "X" is replaced with the list of address to which the request was sent.
get_satisfiers(X): Return a list of addresses (ids) of agents that successfully completed the request. Upon return from this procedure, "X" is replaced with the list of addresses who satisfied the request.
reply(Mode): Tells whether or not to send a reply message when a trigger is being added on a remote agent or agents. If 'true', a reply is desired. If 'none', no reply is needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
blocking(Mode): If true, block until the reply arrives. If false, don't block. In this case, the reply event (ev_reply_trigger_updated) can be handled in the app_do_event callback. Default: true. Note that reply(none) overrides blocking(true).

Implementation

Time triggers are not currently implemented within the agent libraries, but are provided by a separate "alarm" agent, and thus are only available when that agent is connected to the system.

oaa_RemoveTrigger

Declaration

Prolog:	oaa_RemoveTrigger(+Type,+Condition,+Action,+Params)
Java:	boolean oaaRemoveTrigger(IclStr Type, IclTerm Condition, IclTerm Action, IclList Params)

Description

Remove a trigger from one or more agents which may include self, parent, Facilitator, or remote peer agents as specified by the Parameters.

Arguments

The Type, Condition and Action fields to oaa_RemoveTrigger must unify with the corresponding data on the installed triggers to be removed. Please refer to their descriptions above under oaa_AddTrigger.

Params: May be an empty list or include one or more of the following:

address(X): a list including 'self,' 'parent,' 'facilitator,' and/or the addresses of other client agents. Default: see below.
reflexive(T_F): If `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.
do_all(T_F): If true, removes all trigger that match the Condition. Default: false (removes only the first)
get_address(X): Return a list of addresses (ids) of agents that were sent the request. Upon return from this procedure, "X" is replaced with the list of address to which the request was sent.
get_satisfiers(X): Return a list of addresses (ids) of agents that successfully completed the request. Upon return from this procedure, "X" is replaced with the list of addresses who satisfied the request.
reply(Mode): Tells whether or not to send a reply message when a trigger is being removed on a remote agent or agents. If 'true', a reply is desired. If 'none', no reply is needed. Default: true. Note that 'none' is used here instead of false, because we anticipate future use of additional values.
blocking(Mode): If true, block until the reply arrives. If false, don't block. In this case, the reply event (ev_reply_trigger_updated) can be handled in the app_do_event callback. Default: true. Note that reply(none) overrides blocking(true).

Implementation

Time triggers are not currently implemented within the agent libraries, but are provided by a separate "alarm" agent, and thus are only available when that agent is connected to the system.

oaa_CheckTriggers

Declaration

Prolog:	oaa_CheckTriggers(+Type, +Condition, +Op)
Java:	void oaaCheckTriggers(String Type, IclTerm Condition, String Op)

Description

For the given Type, Condition, and Op, determine whether any triggers should be fired, and if so, fire them.

Arguments

Type is either "comm," "data," "task," or "time."

Condition is a template that specifies under what circumstances the trigger should fire. See description under oaa_AddTrigger.

Op defines under what circumstances a trigger is to be checked. The values "send" and "receive" are valid for comm trigger; "add" and "remove" are valid data triggers. For task and time triggers, Op should be a variable (e.g., _Op). This parameter is ignored for these types of trigers because their type implies the operation to be checked (i.e., time expired, task completed).

Implementation

Time triggers are not currently implemented within the agent libraries, but are provided by a separate "alarm" agent, and thus are only available when that agent is connected to the system.

Remarks

oaa_CheckTriggers() is generally used within other LibOaa methods such as and oaa_GetEvent() and infrequently used directly by client agent implementors. It is public to enable programmers to call it as part of implementing task triggers. For instance, if we are writing a mail agent and we have some code which detects the fact that a new mail message has arrived, the programmer would call oaa_CheckTriggers(task, arrives(mail, [for('Adam Cheyer')]), _Op) to see if any triggers fire for this event.

oaa_ClearCache

Declaration

Prolog:	oaa_ClearCache
Java:	void oaaClearCache()

Description

Clear the local cache of solutions established through use of cache() parameter of an oaa_Solve request.

oaa_InCache

Declaration

Prolog:	oaa_InCache(+Goal, -Solutions)
Java:	boolean oaaInCache(IclTerm goal, IclTerm answers)

Description

Retrieve solution(s) from oaa_Solve's cache if the goal we are asking for is properly contained in the cache.

Arguments

Goal is a description of the service (e.g. an action or query) desired.

Solutions is a return parameter which is filled-in with the solution(s) found to goal is the local cache.

Remarks

The Java and other non-Prolog implementations do not correctly handle cases of subsumption. See the section entitled "Prolog-style Queries with Caching" referenced below for a description and example of subsumption.

oaa_AddToCache

Declaration

Prolog:	oaa_AddToCache(+Goal, +Solutions)
Java:	void oaaAddToCache(IclTerm Goal, IclTerm Solutions)

Description

Add the Solutions for Goal to oaa_Solve's cache.

Arguments

Goal is a description of the service (e.g. an action or query) desired.

Solutions is a list of solutions to be added to the local cache.

oaa_CanSolve

Declaration

Prolog:	oaa_CanSolve(+Goal, -AgtList)
Java:	IclTerm oaaCanSolve(IclTerm goal)

Description

Ask the Facilitator for a list of agents which could solve `Goal.' The results may be used with the address(Addr) parameter of oaa_Solve or oaa_AddTrigger.

The Java implementation returns a ICLTerm containing a list of agent addresses; the Prolog implementation achieves this through the return parameter AgentList.

Arguments

Goal is a description of the service (e.g. an action or query) desired.

AgentList (Prolog only) is a return parameter containing a list addresses for agents which have registered solvables that match the given Goal.

Implementation

oaa_CanSolve(+Goal, -AgentList) is implemented as oaa_Solve(can_solve(Goal,AgtList),[address(parent)]).

Examples

Prolog

| ?- oaa_CanSolve(inform(_Type,_Msg,_Args), AgentList).
AgentList = [10,12]

oaa_Ping

Declaration

Prolog:	oaa_Ping(+AgentAddress, +TimeLimit, -TotalResponseTime)
Java:	float oaaPing(IclTerm AgentAddr, float TimeLimit)

Description

Tests whether a given agent is currently responding to requests.

The Java implementation returns the total request/response round trip time (through the Facilitator) in seconds, or -1.0 if a response is not returned in TimeLimit amount of time. The Prolog implementation achieves this through the return parameter TotalResponseTime.

Arguments

AgentAddr is the address of the agent to test.

TimeLimit is the limit (in seconds) on how long to wait for a response.

TotalResponseTime (Prolog only) is a return parameter containing the total request/response round trip time (through the Facilitator) in seconds.

oaa_TraceMsg

Declaration

Prolog:	oaa_TraceMsg(+FormatString, +Args)
Java:	void oaaTraceMsg(String inMessage)

Description

If trace mode of the current agent is set (using oaa_PostEvent(ev_trace_on, [])), display the given message using a method chosen by the client (e.g., to stdout, within a field of a graphical UI, etc.). The Prolog implementation formats Args according to FormatString. The Java implementation displays inMessage directly.

Arguments

Prolog:
FormatString contains formatting parameters from the Quintus Prolog builtin predicate format/2.

Args is the data to display.

Java:
inMessage is the String to display.

oaa_ComTraceMsg

Declaration

Prolog:	oaa_ComTraceMsg(+FormatString, +Args)
Java:	void oaaComTraceMsg(String inMessage)

Description

If comm trace mode of the current agent is set (using oaa_PostEvent(ev_com_trace_on, [])), display the given message. The Prolog implementation formats Args according to FormatString. The Java implementation displays inMessage directly.

Arguments

Prolog:
FormatString contains formatting parameters from the Quintus Prolog builtin predicate format/2.

Args is the data to display.

Java:
inMessage is the String to display.

oaa_Inform

Declaration

Prolog:	oaa_Inform(+TypeInfo, +FormatString, +Args)
Java:	void oaaInform(String TypeInfo, String FormatString)

Description

Send a message to all agents interested in messages of type TypeInfo.

Implementation

oaa_Inform is implemented using oaa_Solve(inform(TypeInfo, Msg), [strategy(inform)]). The Prolog implementation formats Args according to FormatString. The Java implementation displays FormatString directly.

Arguments

Prolog:
TypeInfo is the type of the message to be sent.

FormatString contains formatting parameters as is used by the Quintus Prolog builtin predicate format/2.

Args is the data to display.

Java:
TypeInfo is the type of the message to be sent.

FormatString is the String to display.

Example

When a speech recognition agent detects that the user has finished speaking, this time sensitive information could be transmitted using oaa_Inform(speech, end_of_speech). All user interface or modality fusion agents would then use the information as appropriate.

To provide information that a new user has logged in or arrived, a message such as oaa_Inform(newuser, 'New User ~p', ['David']) could be sent. Given this information, a membership agent could apply policy to determine admission, or a user interface agent update its display accordingly.

icl_ConsistentParams

Declaration

Prolog:	icl_ConsistentParams(+Test, +ParamList)
Java:	Not applicable. See remarks below.

Description

Determine whether the expressions in Test and ParamList are consistent. If so, return success, otherwise failure.

Arguments

Both Test and ParamList may contain either a single ICL expression or list of expressions. If the latter, icl_ConsistentParams will execute all consistency tests.

Note that because icl_ConsistentParams checks consistency as a relation between the two arguments, it doesn't matter which argument specifies the test list and which specifies the parameters to test.

Remarks

It is often used in solvable declarations to define a filter for requests.

It is not feasible to implement icl_ConsistentParams in Java because both Prolog unification and evaluation are used to determine the consistency between Test and ParamList.

Example

A natural language parser agent can only handle English definitions. It's solvable is declared as follows:

        convert(nl, icl,Input,Params,Output) :-
        icl_ConsistentParams(language(english), Params).

If "language(english)" is defined in parameter list of a solve request, the nl agent will receive the request.
If "language(spanish)" is defined in the parameter list, the nl agent will NOT receive the request.
If no language parameter is specified, the nl agent will receive the request.
If "language(X)" is specified, the nl agent will receive the request.

icl_GetParamValue

Declaration

Prolog:	icl_GetParamValue(+Param, +ParamList)
Java:	IclTerm iclGetParamValue(IclTerm param, IclTerm paramList)

Description

Return the value for Param by either looking up the value in the ParamList or using the default value (if it exists).

Arguments

Param must be a partially or fully-instantiated structure having a functor and one or more arguments where the arguments may be either bound values (e.g., priority(5)) or variables (e.g., priority(X)). The atom form (e.g., "priority") is not acceptable.

ParamList is the empty list, or a list of one or more parameters in which to check for Param.

The following is the list of default values for parameters defined for all agents:

from(unknown)
priority(5)
utility(5)
if_exists(append)
type(procedure)
private(false)
single_value(false)
unique_values(false)
rules_ok(false)
bookkeeping(true)
persistent(false)
at_beginning(false)
do_all(false)
reflexive(true)
parallel_ok(true)
reply(true)
blocking(true)
cache(false)
flush_events(false)
recurrence(when)

Examples

1) param : priority(P)
   paramList : [priority(5), param(2)]
   return : priority(5)

2) param : priority(P)
   paramList : [level(5), param(2)]
   return : priority(5) // Default value since not in list

icl_GetPermValue

Declaration

Prolog:	icl_GetPermValue(+Perm, +PermList)
Java:	IclTerm iclGetPermValue(IclTerm perm, IclTerm permList)

Description

Return the value for a permission parameter "Perm" by either looking up the value in the PermList, or using the default value (if it exists).

Arguments

Perm must be a partially or fully-instantiated structure having a functor and one or more arguments where the arguments may be either bound values (e.g., write(falue)) or variables (e.g., write(X)). The atom form (e.g., "write") is not acceptable.

ParamList is the empty list, or a list of one or more parameters in which to check for Param.

The following is the list of default values for permissions defined for all agents:

call(true)
read(false)
write(false)

icl_BasicGoal

Declaration

Prolog:	icl_BasicGoal(+Goal)
Java:	boolean iclBasicGoal(IclTerm goal)

Description

Determine whether an expression is an ICL basic (non-compound) goal, i.e., a functor with 0 or more arguments. If so, return success/true and failure/false otherwise.

Arguments

Goal is the ICL Term to be tested.

Remarks

Basic goals include built-in's as well as solvables.

This is a syntactic test; that is, we're not checking whether the Goal is a declared solvable.

icl_BuiltIn

Declaration

Prolog:	icl_BuiltIn(+Goal)
Java:	boolean iclBuiltin(IclTerm goal)

Description

Determine whether an expression is an ICL built-in goal which can be executed in solvable test expressions, oaa_Interpret, etc. If so, return success/true, or failure/false otherwise.

Arguments

Goal is the ICL Term to be tested.

The current list of ICL builtins is limited to:

A = B
A == B
A \== B
A =< B
A >= B
A < B
A > B
member(+Elt,+List)
memberchk(+Elt,+List)
findall(Var,+Goal,-SolutionList)
icl_ConsistentParams(+TestList,+ParamList)

Remarks

icl_BuiltIn differs significantly from the Quintus Prolog predicate built_in, in that here we do not include basic constructors such as ',' and ';'.

If an agent implements one of the built-ins listed above, oaa_Interpret/2 must be be defined for this goal as well.

icl_ConvertSolvables

Declaration

Prolog:	icl_ConvertSolvables(+ShorthandSolvables, -StandardSolvables) icl_ConvertSolvables(-ShorthandSolvables, +StandardSolvables)
Java:	IclTerm iclConvertSolvables(boolean toStandard, IclTerm inSolvables)

Description

Convert between shorthand and standard forms. of the given list of solvables.

The Java implementation returns the list of converted solvables whereas the Prolog implementation returns the converted list via a return parameter.

Arguments

Prolog

For icl_ConvertSolvables(+ShorthandSolvables, -StandardSolvables)
+ShorthandSolvables is a list of one or more solvables in shorthand form to convert to standard form.
-StandardSolvables is a return parameter contaiing the list of converted solvables.

For icl_ConvertSolvables(-ShorthandSolvables, +StandardSolvables)
-ShorthandSolvables is a return parameter contaiing the list of converted solvables.
+StandardSolvables is a list of one or more solvables in standard form to convert to shorthand form.

Java

toStandard a boolean which distinguishs between the two calling conventions and the function returns. I.e.,

        ShorthandSolvables icl_ConvertSolvables(TRUE, StandardSolvables)
        StandardSolvables icl_ConvertSolvables(FALSE, ShorthandSolvables)

inSolvables is the list of solvables to convert.

icl_GoalComponents

Declaration

Prolog:	icl_GoalComponents(+ICLGoal, -A, -G, -P). icl_GoalComponents(-ICLGoal, +A, +G, +P). icl_GoalComponents(+ICLGoal, +A, +G, +P).
Java:	iclGoalComponents(IclTerm fullGoal)

Description

Prolog: Disassemble (first form above), assemble (second form above), or match against (third form above) the top-level components of an ICL goal. Return success, failure and multiple solutions using standard Prolog semantics.

Java: Disassemble fullGoal into components. Assembly and matching is not supported in the Java implementation The Java implementation returns an array of ICLTerms representing the parts of the goal. I.e.,

array[0] : Address array[1] : Goal array[2] : Param

Arguments

Prolog

ICLGoal as an input parameter it is either a goal to disassemble or match; as an output parameter it is an assembled goal.

A is an address portion of a goal.

G is a goal statement.

P is a parameter list.

Java

fullGoal is an IclTerm which contains the goal to be disassembled.

Remarks

The top-level structure of an ICL goal is Address:Goal::Params where Address and Params are both optional. Thus, every ICL goal either explicitly or implicitly includes all three components.

This may be used with any ICL goal, basic or compound.

When P is missing, its value is returned or matched as []. When A is missing, its value is returned or matched as 'unknown'.

oaa_Id

Declaration

Prolog:	oaa_Id(-Id)
Java:	IclTerm oaaId()

Description

Return the Id of the current agent which was assigned by its Facilitator.

Arguments

Id (Prolog only) is a return parameter populated with the Id for this agent.

oaa_Name

Declaration

Prolog:	oaa_Name(-MyName)
Java:	String oaaName()

Description

Return the symbolic name of the current agent.

Arguments

MyName (Prolog only) is a return parameter populated with the name for this agent.

oaa_LibraryVersion

Declaration

Prolog:	oaa_LibraryVersion(-Version)
Java:	Not applicable. See Remarks below.

Description

Returns the version of the agent library for the current agent.

Arguments

Version (Prolog only) is a return parameter populated with the version number.

Remarks

In the Java implementation, this information is obtained by through the public String oaa_library_version.

oaa_Version

Declaration

Prolog:	oaa_Version(+AgentId, -Language, -LibraryVersion)
Java:	IclTerm oaaVersion(IclTerm agentId, IclTerm Language)

Description

Given an agent's ID, lookup its the language and library version.

The Java implementation returns an ICLTerm containing the library version and populates the argument Language with the language version; the Prolog implementation returns both of these values through return parameters.

Arguments

AgentId the identifier of the agent for which to return the desired information.

Language an ICLTerm populated with the language in which the agent is implemented.

LibraryVersion (Prolog only) is a return parameter populated with the library version number.

Remarks

The default libaray version if unspecified is 1.0.

memberchk_nobind

Declaration

Prolog:

memberchk_nobind(+Elt, +List)

Description

Tests if Elt is a member of List (like Prolog built-in 'memberchk'), but doesn't bind variables in Elt when doing test.

Examples

| ?- memberchk_nobind(a(X), [b(1), a(2), c(3)]).
 
X = _8582 
  
| ?- memberchk(a(X), [b(1), a(2), c(3)]).
   
X = 2

would_unify

Declaration

Prolog:

would_unify(X,Y)

Description

Succeeds if X and Y WOULD unify, but doesn't actually do the unification (no variables are bound by test)

Examples

| ?- would_unify(a(X, X), a(1,1)).
 
X = _8582 
  
| ?- would_unify(a(X,X), a(1,2)).

no

remove_element

Declaration

Prolog:

remove_element(+Elt, +List, -NewList)

Description

Removes the element X from a list.

Remarks

Fails if X is not an element in the list.

call_n

Declaration

Prolog:

call_n(N, Goal)

Description

Calls a goal with the limit N on the number of solutions generated.

Examples

| ?- assert(a(1)). assert(a(2)). assert(a(3)).
 
yes
| ?- call_n(2, a(X)).
    
X = 1 ;
X = 2 ;
no

Glossary

term	A unitary ICL object, which must be of one of the following types: variable - begins with capital letter atom (string) - enclosed in ' marks, or a single word beginning with a lowercase letter number structure - in the form functor(arg1, arg2, arg3...) list - in the form [term1,term2,term3,...]
structure	A term in the form functor(arg1,arg2,arg3,...).
functor	The identifier part of a structure - functor(arg1,arg2,arg3,...).
argument	The non-functor part of a structure - functor(arg1,arg2,arg3,...).
element	An element is a term which is a member of a list - [elt1, elt2, ...].
head	The first element in a list - [head, elt2, elt3, ...].
tail	The list containing all elements after the first element in a list.

CallbackId	Definition (Java)	Description
app_init	boolean oaa_AppInit(IclTerm goal, IclList params, IclList answers)	Called when oaa_Register has completed successfully to signal registration of the client with the Facilitator. No arguments are used; all are null.
app_done	boolean oaa_AppDone(IclTerm goal, IclList params, IclList answers)	If the agent receives a "halt" event, the app_done callback is called before the agent exits. No arguments are used; all are null.
app_idle	void oaa_AppIdle(IclTerm goal, IclList params, IclList answers)	Executing the app_idle callback provides a way for LibOaa to pass control to a client after oaa_MainLoop has been executed. Control is passed when LibOaa is idle, such as during a timeout while waiting for an incoming communication event, or when a user-defined timeout has occurred (see oaa_SetTimeout). app_idle is useful only for Prolog which has a single thread of execution. No arguments are used; all are null.
app_do_event	boolean oaa_AppDoEvent(ICLTerm goal, ICLList params, ICLList answers)	app_do_event is called when a new ICL request has arrived for the client. Users may register either one callback for all new ICL requests, or one callback per solvable. The latter is done when declaring a solvable by using the "callback" parameter (see Declaring Solvables) of oaa_Register or oaa_Declare. All app_do_event parameters are used.
app_on_data_change	void oaa_AppOnDataChange(ICLTerm goal, ICLList params, ICLList answers)	app_on_data_change is called upon any data change event. Users may register either one callback for all data change events or one callback per event. The latter is done when publishing a data declaration by using the "callback" parameter (see Declaring Solvables) of oaa_Register or oaa_Declare. Only the first argument will be used, the remaining two will be null. The first argument indicates the type of data change event that occurred and will be in the form: removed(Data) added(Data) replaced(OldData, NewData) defined(Data, Params) redefined(Data, Params) undefined(Data)

Event	Description
ev_trace_on	Turns tracing mode on
ev_trace_off	Turns tracing mode off
ev_debug_on	Turns debug_mode on (Prolog only)
ev_debug_off	Turns debug_mode off (Prolog only)
ev_com_trace_on	Turns COM-level tracing on
ev_com_trace_off	Turns COM-level tracing off
ev_halt	Shuts down the agent
ev_set_timeout(N)	Changes the current timeout value to N
ev_solve(GoalId, Goal, Params)	Requests that the agent attempt to solve Goal augmented by Params. GoalId is an identifier assigned by the library (LibOAA) for this goal.

Open Agent Architecture (OAA)

Contents

Alphabetical Index

Connection Primitives

Setup Primitives

Client Data Transmission and Database Management Primitives

Sending and Receiving Events

Publishing Services

Requesting and Managing Services

Maintaining Data

Triggers

Cache Management

OAA Utility Functions

Parameter and Capability Management

Agent Data

Prolog Utility Functions

Glossary

Alphabetical Index

com_Connect

Declaration

Description

Arguments

Implementation

Examples

Java

Remarks

See Also

com_Connected

Declaration

Description

Arguments

See Also

com_Disconnect

Declaration

Description

Arguments

Implementation

Remarks

See Also

oaa_IsConnected

Declaration

Description

Arguments

See Also

oaa_Disconnect

Declaration

Description

Arguments

Remarks

See Also

oaa_Register

Declaration

Description

Arguments

Implementation

Examples

Prolog

See Also

oaa_RegisterCallback

Declaration

Description

Arguments

Examples

Prolog

Remarks

See Also

oaa_ResolveVariables

Declaration

Description

Arguments

Implementation

Remarks

Examples

Prolog

oaa_Ready

Declaration

Description

Arguments

Warning!

See Also