Introduction

The OAA shell agent is used to send ICL messages to an individual agent or to the agent community, generally for debugging purposes, or for monitoring the status of a facilitator and its connected clients. Requests may be entered as strings representing Prolog goals (either as commandline arguments or on stdin). These strings are then used as calls to OAA Prolog library procedures, or as goals to be used in a call to oaa_Solve. In addition, commandline options may be used to turn on or off tracing in the facilitator.

Usage Synopsis

The following message is printed when oaa_shell is called with no arguments.

Command line usage: oaa_shell Option_or_Request*
Standard OAA options:
    -oaa_connect Address, -setup_file Path, -on_connect_exception Action
Options done AFTER executing commandline requests:
    "-s"             Get a single request from stdin, execute it, and exit
Requests (without dashes):
    trace, trace_off,  com_trace, com_trace_off, 
    a call to an OAA 2 Prolog library procedure,
    a goal to be solved.

Return Values

Values returned to the operating system:

    -2: Unable to connect to facilitator
    -1: Error or abnormal condition at exit; not all requests completed
     0, and the last request executed has no solution count: Failure
     1, and the last request executed has no solution count: Success
     0 or greater, and the last request executed has a solution count: 
         the solution count

Examples

To turn on message tracing in the facilitator (where the facilitator's host and port are given in a setup file or environment variables):
```
    % oaa_shell com_trace
```
To turn on message tracing in the facilitator (giving the facilitator's host and port on the command line):
```
    % oaa_shell -oaa_connect "tcp('somehost.ai.sri.com',3600)" com_trace
```

To get a listing of all agents currently registered with the facilitator (library procedure oaa_Solve is called in oaa_shell):

    % oaa_shell "oaa_Solve(agent_data(A,B,C,D,E,F), [])"
      -- A listing of solutions (agent_data facts) is printed --
    % echo $status
      -- Reports the number of solutions that were just printed --

(echo $status works under Unix.)

This is equivalent to the preceding (when the request doesn't specify a library procedure, it is used as a goal in a call to oaa_Solve):
```
    % oaa_shell "agent_data(A,B,C,D,E,F)"
```

To get a listing of all agents currently registered with the facilitator, having the name "database":

    % oaa_shell "agent_data(A,B,C,D,database,F)"
      -- A listing of solutions (agent_data facts) is printed --

This is equivalent to the preceding:

    % echo "agent_data(A,B,C,D,database,F)" | oaa_shell -s
      -- A listing of solutions (agent_data facts) is printed --

To Do

Not yet implemented:

The ability to go into a prompt-and-execute loop.
Pretty-printing of goal solutions.

OAA Shell Agent Overview Page