I-X Parameters

Contents

Introduction

Parameters grouped by class or purpose

Introduction

This document does not cover the parameters used with specialised utility programs. For that, see the documentation for those programs.

By a "parameter" we mean a value that's assigned to a name when an application begins execution, so that it can be looked up in a table by code in the application. I-X parameters are normally specified as command-line arguments or as entries in a "properties file".

When using the java command, the command-line arguements that are given to the application are the ones that follow the name of the main program class. The arguments are separated by spaces and most have the form -name=value. For example:

   java -cp ix.jar ix.ip2.Ip2 -domain=domain-library/mydomain.xml
There, the main program class is ix.ip2.Ip2 and the one command-line argument that will be accessible in the application is
   -domain=domain-library/mydomain.xml

The "-" is not part of the parameter name; it is just part of the I-X syntax for command-line arguments. (No "-"s are used when paramater are specified in a properties file.)

For boolean-valued parameters, the value is assumed to be true if only the name is given. If the name isn't given at all, the parameter is assumed to have whatever default value the application desires.

-no and -not can negate the following parameter (which is written without the initial "-"). It is equivalent to giving the parameter the value "false" but can be used in cases where it would seem odd to explicitly say "=false". For example,

   -not interactive

A "properties file" of parameter assignments may be loaded by using the command-line argument

   -load resource
where the resource can be a file name or a URL.

N.B. -load is not a parameter. It is syntax that says to load name=value lines from a file or other resource. More than one -load may be specified. Note that in such files a parameter name does not have a "-" in front of it.

A properties file is processed by the load method of the Java Properties class. All-whitespace lines are ignored. Comment lines can begin with # or !. A \ at the end of a line indicates a continued line. Within a line, the escape sequences \t, \n, \r, \\, \", \', \ (a backslash and a space), and \uxxxx are converted to single characters.

Parameters grouped by class or purpose

IXAgent

-debug=boolean, default true
-interactive=boolean, default true
-log-directory=directory-name

If this parameter is given, a log file will be created in the specified diretory when the agent starts up and XML descriptions of significant events (such as messages sent and received) will be written to that file while the agent runs.

-ipc-name=name
-symbol-name=text
-display-name=text

ipc-name is essentially a synonym for symbol-name.

-metal-theme-secondary3=colour
-font-increment=int
-superiors=namelist
-subordinates=namelist
-peers=namelist
-contacts=namelist

For the relationship parameters above, a namelist is a list of agent symbol-names separated by commas.

-external-capabilities=agent:verb,agent:verb,...

For each pair agent:verb, if an issue or activity with that verb appears, an action item will be added that says "invoke agent". The agents are given by their symbol-names.

When such an action item is selected, the corresponding issue or activity is forwarded to the indicated agent with report-back=yes.

-extension-classes=classname,classname,...

Here a class name must be a full Java class name, including the package. Each named class must implement the IXAgentExtension interface. For more, see Agent Extensions.

-use-long-ids=boolean, default true
-use-hash-ids=boolean, default false
-allow-random-device=boolean, default false
-send-received-reports=boolean, default true

Controls whether or not the agent sends a "Received" report when it receives an issue or activity that has report-back="yes". Although this parameter is checked at the I-X agent level, it currently affects only process panels.

The parameters in the IPC section also apply to all agents.

I-P2

-library-directory=pathname
-domain-library=pathname -- only for backward compatibility
-domain=resource,resource,...
-plan=resource,resource,...

A "resource" is a URL, a file-name for an existing file, or the name of a resource that can be obtained from the agent's classpath by a ClassLoader.

-plan-state-to-save=namelist or *
-test-menu=resource,resource,...
Specifies the contents of the "Test" menu in this agent. See Test Menus
-initial-html-viewer-home=resource
-logo-line-1=text
-logo-line-2=text
-logo-image=resource
-frame-size=widthxheight (e.g. 800x400)
-additional-handers=classname,classname,...

Here a class name can be a full Java class name (including package), but classes in the packages that are expected to supply handlers can be given in the "dash-syntax" style used in the XML, e.g. test-handler rather than ix.test.TestHandler.

Handlers may also be added by an activity with pattern:

       add-handlers className className ...
    
The reason for the language difference ("additional-handlers" vs "add-handlers") is that the "additional-handlers" parameter is not an "active" command. It just says what they are.

-domain-editor-class=classname
-issue-viewer-class=classname
-activity-viewer-class=classname
-state-viewer-class=classname
-annotation-viewer-class=classname
-classic=boolean, default false

Use the old issue and activity viewers

Parameters for "classic" issue and activity viewers:

-description-column-width=int
-annotations-column-width=int

-max-menu-items=int

Some menus can handle long lists of items and "chain" to a "More" submenu after some number of items. This parameter gives that number.

I-Plan

I-Plan is much the same as I-P2, but with a different set of initial handlers and with show-options true by default.

I-Plan also tends to force plan-state-to-save=*.

Options

These parameters affect agents that provide options, which currently means I-Plan and I-P2.
-option-directory=pathname
-show-options=boolean

The default is false in I-P2 and true in I-Plan. "option-directory" takes precedence. If an option-directory is specified, show-options is always treated as true.

-option-for-input=name
-filter-duplicate-plans=boolean, default true
-plan-splits-option=boolean, default false

If true, it changes the way the "Plan" command treats options. Instead of changing the plan in the current option, it creates a child of the current option and puts the new plan there.

Planning

Parameters that affect the planning algorithm in any agent that includes a planner:
-step-limit=int
-single-step=boolean, default false
Parameters that affect standalone, GUI-less planners:
-plan=resource
-output=filename
-output-psgraph-data=filename
-owls-out=filename

Plan-checking simulator

-trace=boolean, default true
-shuffle=boolean, default false
-randomize=boolean, default false

I-Plan auto-tester

-test-list=resource

Defaults to "test-domains/standard-tests.xml".

-plan-from-plans=boolean [default false]

I-Sim

-isim-agent-name=text

The symbol-name of the I-Sim agent to use.

I-Serve

-http-server-port=int

Tells I-Serve what port to listen on for the requests it serves. If no port is specified, I-Serve asks for OS for a free port, and the number will be included in "Help" -> "About I-X Server".

-http-root-directory=pathname

Specifies the root directory of a file tree that I-Serve will serve as "static content". (You can, of course, put new files there while I-Serve is running, but the content is in the files rather than generated when a request is received.) The URLs look like this:

http://iserveHost:iservePort/files/...
where iserveHost and iservePort are replaced by the name of the machine that is running I-Serve and the port that I-Serve is using.

LTF (List Task Formalism) parser

-force-numeric-node-ids=boolean [default false]

XML Tree Editor

-document=resource

IPC

-ipc
-ipc=strategyName
-ipc=class

See the javadoc for IPC.makeCommunicationStrategy(String strategyName)

-enqueue-incoming-messages=boolean, default false

If true, tells the I-X agent to place a thread and message queue between the communication strategy and the agent, so that any thread that delivers an incoming message needn't wait for the message to be processed by the agent.

Ordinarily, a thread that delivers a message must wait until the message has been fully processed before its call to the agent's message-receiving method returns. If, during that time, the thread is needed for sending messages, or if it has locked an object that is needed for sending messages, an attempt to send a message will hang. This is something that might happen, for example, when a panel receives an issue or activity that has report-back=yes and attempts to send a "Received" report.

Most comm strategies use threads in a way that naturally avoids this problem, so in practice this parameter is almost never used.

-rename-variables-in-input=boolean, default true

Tells it to rename any "?name" variables in patterns in incoming issues and activities so that they don't conflict with any existing variables in the receiving agent.

Default/simple and XML communication strategies

-run-name-server

Tells the agent to run a name-server in addition to what it normally does. The name-server can also be run as a separate, stand-alone agent.

-name-server
-name-server=host:port
-no name-server

Tells the agent whether to use a name-server to look up the addresses of other agents, and if so what host and port to connect to. By default, a name-server will be used.

The host:port defaults to localhost:5555

-host=hostname

Used to tell the agent what to call the machine it is running on when the default name would not work when used on other machines. This parameter can also be used to specify a (dot-separated) numeric IP address as the host name. (See also ns-use-ip-addrs, below.)

The default is the name returned by

      InetAddress.getLocalHost().getCanonicalHostName()
    
which should usually be right.

-port=int

The port number used to connect to the agent in order to send it a message. The agent registers its host and port with the name-server and then listens on that port.

-ns-use-ip-addrs=boolean, default false

Tells the name-server to record numeric IP addresses extracted from the connections agents make to the name-server instead of using the host-names those agents provide. This is for "emergency" use when hostname lookup isn't available or doesn't work correctly.

Note that this parameter must be given to the name-server (if it's stand-alone) or to the agent that runs the name-server. It does not have any effect on other agents.

For this to work for agents on the same machine as the name-server, they have to be using an as-if-remote addr for the name-server, not "localhost". So they cannot use the localhost:5555 default for the "name-server" parameter. (Otherwise the IP addr the name-server extracts from the connection will be the one for localhost.)

Examples:

Running the name-server:

      etc/nameserver -ipc=xml -ns-use-ip-addrs
    

Running an agent that registers with the name-server:

      etc/ip2 -ipc=xml -ipc-name=myagent \
              -name-server=somehost.someplace.org:5555
    

Parameterized communication strategies

Some communication strategies take other strategies as parameters. The syntax is

     strategy = name | name:strategy,strategy,...

A parameterized strategy typically provides a "wrapper" around "inner" strategies specified by its parameters. The ones provided are:
tracing:strategy

Prints an XML description of the message contents when a message is sent or received by the specified inner strategy.

separate:stategy

Creates a dummy I-X agent for the inner strategy to use. This protects the main I-X agent from some operations a comm strategy might perform, such as changing the agent's symbol-name. "separate" is often used together with "dispatching".

dispatching:strategy,strategy,...

Allows different inner strategies to be used for communicating with different agents. One of the arguments must be prefixed by "default:". Strategies are assigned to agents as follows. If a message is received from an agent A via strategy S, then A gets S as its strategy; otherwise a tab in the I-Space tool can be used to assign strategies explicitly.

Examples:
     tracing:xml
     dispatching:jabber,default:xml,tracing:xml
     dispatching:jabber,xml,default:tracing:xml
     dispatching:separate:jabber,default:kaos
The notation for comm strategy combinations is fairly general, but not quite to the point of allowing parens for grouping. For example,
     dispatching:tracing:jabber,default:tracing:xml
works, but
     tracing:dispatching:jabber,default:xml
doesn't, because the tracing strategy gets parameters dispatching:jabber and default:xml.

Some strategy combinations won't work semantically despite being valid syntax. For example, you can't do

     dispatching:xml,simple
because they both expect a name-server on the same port (but with different syntaxes for its messages).


Jeff Dalton <J.Dalton@ed.ac.uk>