OAA StartIt
version 2.0.3, November 1999
Contents:
The sartup script file (unix_startit or win_startit.bat) is shown below. (Note the Windows syntax, but the parameters to set are the same on UNIX).
set JAVA_LIB_DIR=C:\Progra~1\borland\jbuilder2\java\lib\
java -classpath %JAVA_LIB_DIR%classes.zip;..\jars\swingall.jar;..\jars\oaa.jar;startit\startit.jar;.;..\jars\icebrowserlitebean.jar
startit.StartIt -defaultdir startit\demo\configs\ -autoconnect ex_win.config
In order to run the script, the variable JAVA_LIB_DIR has to decribe the directory where the classes.jar file lies.
Invoking Start-It does not cause any other agents to start up immediately. Rather, its interface provides controls that allow other agents to be invoked.
-no_expect
Start-It takes an optional command line argument -no_expect (under Unix).
If this option is given on startup, Start-It will not try to
make use of the `expect' program, which requires that TCL be installed
on your system. Expect solves some minor
problems with Start-It:
Without `expect', the standard output stream
of agents are not displayed immediately, but rather are buffered. This
may be annoying when trying to trace an agent.
On SGI machines, Start-It cannot kill programs
running from inside an xterm window if `expect' is not used.
-autostart
If the -autostart option is given, all agents controlled by the Start-It
window will automatically be run as soon as Start-It
is ready to do so, as if the user had pressed the big blue START button.
This feature could be useful if you want to
create a login for a particular demo where all agents (including Start-It)
would begin executing as soon as X-Windows initializes.
-project ProjectName
Selects the initial project to be used on startup. For a description
of projects, see the following section.
-oaa_host host_name
The host where the facilitator is running
-oaa_port port_number
The port where the facilitator is waiting for connections
-autoconnect
Automatically connects to the facilitator
-defaultdir
Directory where the configuration files are stored
filename
The last parameter is the configuration file
to be read
Start-It always provides the Display control and the large button labeled Start. The Display control shows which machine will be used to display the windows in which the various agents are invoked (this is not necessarily the same machine on which the agents are run). Clicking in the small box causes a choice list to appear, which can be used to either choose or type in a different display. The default value is ``Local'', which means the machine that Start-It is running on. The Start button causes Start-It to invoke all agents currently being displayed in its main window.
Start-It is capable of maintaining multiple projects, or collections of agents, in a single configuration file. By choosing a project from the Projects menu, all agents belonging to the project become visible in Start-It's main window, and all agents not belonging to the project are no longer displayed. To display the list of all agents defined in the configuration file, the user may select the Global from the Projects menu.
Beneath the Display and Start controls in the main window, there are groups of controls for individual agents. For each agent specified in the configuration file, Start-It provides a status box, a basic menu, and a host selector.
When Start-It has been asked to invoke an agent, the agent's status box is colored either yellow (the agent is initializing but is not yet ready to interoperate), green (the agent is connected to a facilitator and ready to interoperate), or red (the agent has died or is not functioning normally).
An agent's basic menu is accessed by clicking on the large button labeled with the agent's name (such as the button labeled ``Database'' in Figure 3). When this is done, a menu is displayed containing the four commands Hide, Show Options, Start, and Kill. These commands are used as follows:
An agent's controls may be hidden by choosing
Hide. When this is done, the agent's name is placed on the
Applications menu; selecting it from there
causes the controls to be shown again.
Show Options tells Start-It whether or not
to display the agent-specific menus that have been defined for the
agent, if any.
Selecting Start causes the agent to be invoked.
Selecting Kill causes the agent to be terminated.
The Host control is used to specify the machine on which the agent is to execute. Clicking in the small box causes a choice list to appear, which can be used to either choose or type in a different host. The default value is ``Local'', which means the machine that Start-It is running on.
#------------------------------------------------------
# Employee Database Agent
#------------------------------------------------------
appname Database
oaaname employee_db.root
appdir /home/zuma1/OAA/demo.bin
appline ./d2
end
#------------------------------------------------------
# Calendar Agent
#------------------------------------------------------
appname Calendar
oaaname calendar.root
appdir /home/zuma1/OAA/demo.bin
preline setenv ENV_VAR something
appline ./c
onready inform_ui(calendar,
ready)
ondisconnect [inform_ui(calendar, disconnect),
reinit(all)]
end
appname gives the name of the agent as it will appear in Start-It's interface.
oaaname specifies an agent's symbolic
name as represented by the facilitator. These are the same names that are
used internally in the agent's call to go/3,
or overridden using the -oaa_name NAME command line option. Note:
agents written in Prolog append the name of
it's Facilitator to its agent name (eg. `calendar.root'), while agents
written in other programming languages do
not follow this convention (eg. `interface'). In systems that employ a
single facilitator, its name is always 'root'.
appdir is the directory that should be current, on the agent's execution host, when invoking the agent.
preline is a command line executed before
invoking the agent. This section is often useful for setting environment
variables needed by the agent.
appline is the command line to use in
invoking the agent, specifying the executable for the process as well as
any
command line arguments.
projects specifies to which projects
(from among those listed in the `projectlist' definition) the process belongs.
If
projects is not specified, the process
is assumed to belong to all projects in the projectlist. All processes
automatically belong to the project `Global'.
projectlist is a line that must be given
at the head of a configuration file (before the definition of any processes),
specifying all projects defined in the configuration
file. A project can be thought of as a way of partitioning the
processes into groups that can be viewed as
together in Start-It's main window.
onready specifies an ICL goal or list
of ICL goals to be broadcast when the agent is connected and ready to
receive messages.
ondisconnect specifies an ICL goal or
list of ICL goals to be broadcast when the agent has disconnected from
the Facilitator.
The rational for onready and ondisconnect is
that there are times when agents need to perform initialization
handshaking with respect to one another. If
one agent is restarted for some reason, other agents might like to
know this information. Although each agent
could setup individual triggers to detect the coming and going of
agents it is interested in, in some cases
it is much simpler and cleaner to put these project level interactions
directly
in the Start-It config file, letting Start-It
to the work (it knows already who is connected and what their state is).
It is also possible, in the configuration file, to specify agent-specific menus or other interface elements for use in selecting operational parameters for various agents. The interface elements are used to allow the user to specify values for different variables which can be referenced in the appline. Command line variables should be written in the form ${varname}.
The following example allows the user to choose a tty-port (A or B), which is added to the command line of the phone agent.
#------------------------------------------------------
# Phone Agent
#------------------------------------------------------
appname Phone Agent
oaaname phone
appdir /home/zuma1/OAA/demo.bin
appline ./phone ${tty-port}
menu tty-port
TTY Port?
option ttya
TTY-A
option ttyb
TTY-B
end
end
menu: for selecting among fixed choices
toggle: a boolean checkbox
text: a text field which can be entered by
the user.
text-menu: for selecting among a list of predefined
choices, while allowing the user to enter a new choice in a
textfield.
toggle-text-menu: possesses a default value
which can be overridden by using a menu or text field.
Descriptions of each will be given in the following sections.
menu varname
Text To Be Displayed
option return_value1
Option Text 1
line
option return_value2
Option Text 2
default return_default
Default Text
end
The `line' option is used to create separators within the menu, and
is optional. If the `default' field is not specified, the first
option listed will be the default value.
toggle varname
Text To Be Displayed
true-value
Value To Be Returned If TRUE
true-label
Label To Be Displayed when TRUE
false-value
Value To Be Returned If FALSE
false-label
Label To Be Displayed when FALSE
set
end
All parameters for the toggle control are optional. If the `set' parameter
is given, the toggle defaults to have value
`TRUE', `FALSE' otherwise.
text varname
Text To Be Displayed
value Default
Start Value
size
WidthInChars
end
All parameters for the text control are optional. The `value' field provides the initial value contained by the text field, and `size' indicates how wide the text field is in characters.
Variables are expanded ONLY IF they are sourrounded with curly braces in this fashion: ${variable}. If they occur without braces (e.g. $variable) they are treated like any other string, and simply passed verbatim ($ sign and all) to the shell started up by the rsh. They will, of course, get expanded "on the other end" of the rsh, so you should be sure some such shell variable will exist there (either because you know it's defined by the shell itself, or in your .cshrc, or in the app's "preline" directive).
One is ${globalDisplay}, which refers to the contents of the display widget in the top left corner of the startit GUI.
The second is ${Host} (notice capitalization), which refers to the contents
of the "Host:" widget (located next to each
Application Name button on the startit GUI). You may use the form ${application:Host}
to specify an application other
than the current one (see "Specifying The Application Name" below).
${application_name:selector}
Whenever a ":" exists within your variable name, this method of resolving the variable is used exclusively.
application_name is one of the applications in your config file, as specified on an "appline" directive. It may contain spaces, or any other character, except a colon. selector is the name of one of the selector widgets (e.g. toggle, menu, text, toggle-text-menu) as specified by the second argument of one of those directives.
EXAMPLE:
This makes the host entry
of "My Agent" start out to be
the same host as whatever
the "Push To Talk" is set to:
appname My Agent
host ${Push
To Talk:Host}
Not specifying the application name
Whenever there is no ":" in the variable name, the following resolutions are tried in order. As soon as one method is able to resolve a variable name, that name is the one used:
1.Use the value specified by the selector of the given
name in the current application
2.Search the global selectors (currently, this is only
globalDisplay)
3.Search all applications, in order of appearance
4.Resolve as an environment variable (local to the startit
GUI process), using the getenv() system call
5.If all else fails, use the literal value inside the
${} (this is almost certainly not what the user wants, but a warning
message is printed out when this happens)
Note: by convention, since environment variables tend to be all upper case, startit variables (and the selector names they refer to) should be in lower case. The pre-defined startit variables are in mixed case. This is only convention, however. Startit does not actually look at the case to decide which resolution method to use.
# This will echo the host
"Test 1" is running on, since
# "$HOST" doesn't get expanded
by startit at all
appdir /
appname Test 1
appline echo $HOST
end
# This will echo the host
"startit" is running on, since
# startit will expand "${HOST}"
as its own environment var
appdir /
appname Test 2
appline echo ${HOST}
end
# This will echo the contents
of "Test 3"'s "Host:" selector
appdir /
appname Test 3
appline echo ${Host}
end
# This will echo the contents
of "Test 1"'s "Host:" selector
appdir /
appname Test 4
appline echo ${Test 1:Host}
end