Open Agent Architecture (OAA)

Agent Library Reference Manual
Version 2.3.1



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

Open Agent Architecture and OAA are trademarks of SRI International.


Contents

This document furnishes descriptions of the API provided by the libraries used to create components compliant with OAA 2.3.1. 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

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

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:

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

  1. Retrieve host and port from command line arguments
  2. Example:
  3. Retrieve this information from the environment variables OAA_HOST and OAA_PORT (Prolog only).
  4. Use information found in the configuration file setup.pl. Entries must be of the form
  5. 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.

See Also



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).

See Also



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.

See Also



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.

See Also



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.

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.

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.

See Also



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:

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'.

See Also



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.

See Also



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'.

See Also



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 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'.

See Also



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.

See Also



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)".

See Also



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.

See Also



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:

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.

See Also



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.

See Also



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.

See Also



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:

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: 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): Data solvables (where type(data) is specified) add some additional parameters:

Permissions

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

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.

See Also



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:

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.

See Also



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:

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.

See Also



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.

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:

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. 

See Also



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

See Also



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

See Also



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

See Also



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. 

See Also



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.

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.

See Also



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.

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 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.

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 removing data, triggers may be fired if any exist where the condition for the trigger matches Clause.

See Also



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.

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

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.

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.

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

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.

See Also



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.

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:

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. 

See Also



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:

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.

See Also



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.

See Also



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.

See Also



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.

See Also



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.

See Also


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]

See Also



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.

See Also



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.

See Also



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).

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:

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

See Also



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:

See Also



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.

See Also



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:

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.

See Also



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.

See Also



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.

See Also



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.

See Also



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.

See Also



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.

See Also



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

See Also



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

See Also



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.