                Convoy Cluster (tm) Software Demo
                =================================

Following are the installation instructions for the Convoy demo. It is
implemented in Java and is distributed in conjunction with SUN Microsystems
Java run-time V1.1. Same installation file is used on both server and client
computers. Note that this demo is designed to operate with up to thirty two
server computers.

- Run cvydemo.exe self-extracting archive and unpack the demo files on each of
  the client and server computers.
- The following directory structure is created:
        \cvydemo
            \bin
            \classes
                \images
            \lib
                \security
- Change to the 'classes' directory.
- The two command files: 'server.cmd' and 'client.cmd' are used to invoke the
  demo on the server and client computers respectively:

  Server:
  ------
  Run server.cmd command file and pass it a single parameter - the numeric ID
  of the server. For example, you would execute 'server 1' on one server and
  'server 2' on the other. This ID will be included in the reply from the
  server to the client and will be used to select the color for the border
  of the picture. This visually represents the fact that both servers respond
  to the requests and the load is evenly distributed among them.

  Client:
  ------
  Run client.cmd command file and pass it a single parameter - the numeric
  cluster IP address of the server cluster. For example you would execute
  'client 207.115.191.137' if you configured Convoy on the servers to
  respond to 207.115.191.137 as the cluster IP address.

If you started the demo as described above, you should see pictures randomly
appear on the screen with a color border drawn around them. Black means that a
network error has occurred. When request for a new picture is made, destination
square is colored gray until reply arrives from the server, at which time the
picture is drawn in the destination square.

Demo characteristics can be controlled by adjusting the parameters listed
below. Edit client.cmd and server.cmd command files to include parameters and
change their values. Command files contain the following line:

    ..\bin\java <class name> [[<Parameter name> <Parameter value>] ...]

Class name is either NIdemo or NIserver and specifies the Java class to execute.
Class name is followed by a sequence of parameter name/value pairs. Most
parameters (like Port, Requests, ReplySize, RequestSize, etc.) need to have
matching values on all of the client and server instances.

Following is a list of parameters names and their default values:

Name          Default     Description

Requests      16          Maximum number of simultaneous outstanding requests
                          allowed from each client. The value for this
                          parameter should be between 1 and 25.
Delay         1           Delay in milliseconds for processing each request
                          (on the server) or reply (on the client). This
                          parameter simulates computation delays in
                          real-life applications and is used to control the
                          speed of the demo. We suggest that only server delays
                          are changed to adjust the rate with which the
                          images change on the client.
Address       ?           Dot-separated server cluster IP address (client-only
                          parameter).
Port          1000        TCP port on which the server listens for incoming
                          connections.
RequestSize   1           Size of request in bytes.
ReplySize     1           Size of reply in bytes.
DisplayBW     0           0 means display data rate in requests per second.
                          1 means display bandwidth in bytes per second.

For bandwidth-intensive demo you should set DisplayBW parameter to 1 and
adjust the RequestSize and ReplySize parameters as outlined below.

IMPORTANT: You might need to tune the parameters of the demo for optimum
display of the network performance. If the bandwidth showed at the top of
the client window is somewhat low then performance is probably constrained by
how fast pictures can be drawn on the screen. Increasing the size of the
transfer per each request will increase the bandwidth utilization. In order
to adjust the transfer size, you will need to edit client.cmd and server.cmd
command files. They contain the ReplySize parameter which represents the
size of the reply from the servers in bytes. This parameter has to be set
to the same value in both client.cmd and server.cmd command files.

You will need to empirically find the ideal value for the transfer size.
Keeping it too low will make the demo performance graphics bound and
bandwidth values will be very low. Increasing transfer size beyond a
certain point will not increase the bandwidth while the rate of graphic
change will decrease. The ideal point is at the knee of the bandwidth
curve before it starts approaching the asymptote value.

If you have any questions regarding this demo please contact Valence Research's
technical support staff at 503-531-8718 or support@valence.com.


