Introduction
Parameters grouped by class or purpose
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.xmlThere, 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 resourcewhere 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.
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 is essentially a synonym for symbol-name.
For the relationship parameters above, a namelist is a list of agent symbol-names separated by commas.
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.
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.
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.
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.
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.
Use the old issue and activity viewers
Parameters for "classic" issue and activity viewers:
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 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=*.
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.
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.
Defaults to "test-domains/standard-tests.xml".
The symbol-name of the I-Sim agent to use.
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".
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.
See the javadoc for IPC.makeCommunicationStrategy(String strategyName)
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.
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.
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.
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
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.
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.
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
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:
Prints an XML description of the message contents when a message is sent or received by the specified inner strategy.
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".
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.
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).