Modifying the Task Configuration File

If the MCS service agent and MCS cannot communicate, or if you haven't associated your task with an agent cluster in MCS, your task will get its configuration from the TaskConfigurations.xml file.

TaskConfigurations.xml is used if any one of these conditions are present:

If this	Then this
The MCS service agent service is not running on the client machine.	All requests for a task configuration within a given client Virtual Machine (VM) will use TaskConfigurations.xml to connect with run-time servers.
The MCS service agent is configured to communicate with an MCS system that is not running.	All requests for a task configuration within a given client Virtual Machine (VM) will use TaskConfigurations.xml to connect with run-time servers.
A configuration for a given resource name has not been created in MCS.	TaskConfigurations.xml is used to connect with run-time servers.

If the first two conditions are false, then task configurations are retrieved using the resource name for each task. Within a given client VM some resources may obtain configuration information from the TaskConfigurations.xml file, while others may obtain configuration information from MCS. Information for a single resource name will never be gathered from both MCS and the TaskConfigurations.xml file.

How the Task Configuration File is Used

TaskConfigurations.xml is created automatically the first time a task is run on a remote or client system. When an application that exercises a task is first run, the system checks for the file, and, if it doesn't exist, creates it using the following default values:

<Configurations>
  <Configuration Name = "myResourceName" >
    <Property Name = "serverAddress" Value = "localhost" />
    <Property Name = "serverClass" Value = "com.attachmate.common.eai.ProxyTaskServer" />
  </Configuration>
</Configurations>

where

myResourceName corresponds to the resource name property on the task bean, or the resource attribute in the task element of the connector XML metadata. This name is the same as the task name by default. If you change the task resource name, you need to make a corresponding entry here.
serverAddress specifies the location of the run-time server. The default is "localhost". The default port number for the server is 6700. You can change the port number by adding ":xxxx", (where xxxx is the port number), after the server name.
serverClass is the fully qualified class name of the object to use to interface with Runtime Service for Screens. The default is the RMI proxy. You usually won't need to modify this entry. If other connection mechanisms are provided (in proc, CORBA, SOAP, etc.), these are implemented as different classes, and you specify one of them here.

Each different task has a configuration element. If you change ITask.resourceName property (Task beans) or resourceName attribute in the task file (XML) without adding an entry in TaskConfigurations.xml, a new entry, (using default values), is created automatically the first time you attempt to run the task. This may be the easiest way to "seed" the file. If the defaults are not appropriate, the task will fail, but you can go back and make the necessary corrections in a text editor.

Where the Task Configuration File is Located

By default, TaskConfigurations.xml is located in the directory specified by the system property user.home, which is a platform-specific directory where Java puts per-user data. You can determine the value of user.home for your Java installation by checking the system properties. On Windows systems, the default value is Documents and Settings\user login.

You can specify your own directory for this file by setting the system property "attachmate.home" on the command line that starts the Java VM that runs your task interface objects:

-Dattachmate.home=<myDirectory>

where <myDirectory> is the name of the directory you are specifying.

How you pass command line arguments to the Java VM depends on your environment. The Java VM can be part of a Web server for Servlets and JSPs, in a browser for Java Applets, or a stand-alone process if your tasks are running as part of a Java application. You can also set the system property programmatically from within your application as follows:

System.setProperty("attachmate.home", <myDirectory>);

Your application must make this call before you can run tasks and your application must have the necessary permission to modify system properties.

Configuring Your Tasks with the Task Configuration File

To configure a task with the task configuration file

You can either create the TaskConfigurations.xml file from scratch, or run the task once (it will fail) to create the basic structure, which you can then modify.

Open the TaskConfigurations.xml in a text editor, and make the following modifications:

Do this

Specify a run-time server

Type the address without double slashes or protocol specification. For example, to specify a run-time server named "myServer":

<Property Name = "serverAddress" Value = "myServer"/>

Use a session pool with a name that's different than the NavMap name

Append the session pool name to the server address. For example, to specify a pool named "myPool" on a server named "myServer":

<Property Name = "serverAddress" Value = "myServer/?contextName=myPool"/>

"/?ContextName=" are required delimiters and property identifiers used by the Runtime Service. The slash escapes the question mark, which is modeled after the URL query syntax.


	Associating Tasks with Run-time Servers, Overview