Manually Configuring the Client Environment

In a default configuration, applications are run or served from the same system as that where the run-time system is installed. However, to run in a distributed environment, you can configure published tasks in MCS to access registered run-time servers on different systems, providing task failover protection and optional load balancing.

If any of the following conditions are present, all client access to the run-time servers is handled through the IMSClientConfig.xml file:

The client environment configurations are set not to use MCS within the file ims_client.properties.
The MCS service agent service is not running on the client machine.
The MCS service agent is configured to communicate with an MCS system that is not running.
A configuration for a given task name has not been created in MCS.

Within a given client VM some resources may obtain configuration information from the IMSClientConfig.xml file, while others may obtain configuration information from MCS. Information for a single task ID is not gathered from both MCS and the IMSClientConfig.xml file.

How the Client Configuration File is Used

IMSClientConfig.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 = "<task_id_name>" >
    <Property Name = "serverAddress" Value = "localhost" />
  </Configuration>
</Configurations>

where

serverAddress specifies the location of the run-time server. The default is "localhost". The default RMI port number for the server is 6900. If necessary, you can change the port number by adding ":xxxx", (where xxxx is the port number), after the server address:
```
<Property Name = "serverAddress" Value = "localhost:8086"/>
```

Location of the Client Configuration File

The IMSClientConfig.xml file is located in the cfg directory, either in the location you specified as a system property (attachmate.home) or in the Java-provided location, user.home. On a Windows system, this is Documents and Settings/user login.

To specify a custom directory for the IMSClientConfig.xml file
Set the system property "attachmate.home" on the command line that starts the Java VM that runs your task interface objects as follows: -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. -or- 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 it must have the necessary permission to modify system properties.

To specify a custom directory for the IMSClientConfig.xml file

Set the system property "attachmate.home" on the command line that starts the Java VM that runs your task interface objects as follows:
```
-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.

-or-
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 it must have the necessary permission to modify system properties.

Configuring Your Tasks using the Client Configuration File

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

To configure a task with the client configuration file

Open the IMSClientConfig.xml in a text editor, and modify it as follows:

To specify

Do this

A run-time server to serve applications from a remote 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"/>

The default port number for the server is 6900. You can change the port number by adding ":xxxx", (where xxxx is the port number), after the server name.


	Configuring Your Run-time Environment
	Associating Tasks with Run-time Servers
	Running Tasks on Run-time Servers
	Configuring Task Failover and Load Balancing