I-X Parameters List

Updated: Tue Aug  8 16:07:16 2006 by Jeff Dalton

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

  -domain-editor-class=classname

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

  -use-long-ids=boolean            [default true]
  -use-hash-ids=boolean            [default false]
  -allow-random-device=boolean     [default false]

  -send-received-reports=boolean

     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 *

  -initial-html-viewer-home=resource

  -logo-line-1=text
  -logo-line-2=text
  -logo-image=resource

  -frame-size=width"x"height   (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, say, ix.test.TestHandler.

  -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  

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

Both I-P2, I-Test, I-Test, ...

  -test-menu=resource,resource,...

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

  -http-root-directory=pathname

  -http-webapps-directory=pathname

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

    Example:

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Notes:

The "-" is not part of the parameter name; it is just syntax.

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

  -load resource

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.

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

There are two ways to add new issue and activity handlers at run-time.

    1. a command-line argument / props file entry

         additional-handers=className,className,...

    2. An activity with pattern: 

         add-handlers className className ...

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