.LP
"Data transport" refers to the method used to transfer data between processes.
Data transport mechanisms can be local or remote.  Local transport mechanisms
include shared memory, files, pipes, and streams;  remote transport mechanisms
include sockets, tli, and rpc.  With the use of remote data transport, the
ability to get input from and output to remote machines is implemented, and
distributed processing is made possible.
.LP
"Distributed processing" means the ability to specify remote machines on which
to execute individual Khoros programs.  The capability to do distributed
processing is implemented via employment of the remote data transport
mechanisms.  With distributed processing,  one needs a method to execute jobs
remotely, as well as a mechanism to transport data back & forth from the
remote machine.  A remote daemon, "phantomd", is started on the remote machine,
takes requests to execute a job, and transports data involved with that job
using the remote data transport mechanisms.
.LP
Note that Patch 3 to Khoros implements a "beta" version of data transport /
distributed processing; the capability will be refined, improved and extended
in future Khoros releases.  One limitation of this first version of data
transport / distributed processing involves whether or not a transport 
mechanism provides \fIpermanent data storage\fP.  By their nature, some 
transport mechanisms provide permanent data storage, while others do not.  
Permanent data storage is offered by transport mechanisms such as shared memory
and files;  it is not provided by sockets, pipes, or streams.  When permanent 
data storage is not available, the scheduler used by \fIcantata\fP will be 
unable to execute a network of glyphs unless it starts \fIat the very 
beginning\fP, where initial input is provided in a permanent form.  Thus, when
using distributed processing, which is implemented via a non-permanent data
transport mechanism (sockets) you must click on the "RESET" button and run 
the network completely through every time.  We realize that this limitation 
is inconvenient and restrictive;  in future versions of Khoros, the scheduler 
used by \fBcantata\fP will be improved so as to eliminate this problem.
.LP
Transport mechanisms currently used by the \fBcantata\fP visual language are:
.IP shm:
Shared Memory (local transport / permanent storage)
.IP file:
Standard Unix file (local transport / permanent storage)
.IP socket:
Socket transport  (remote transport / no permanent storage)
.LP
Before distributed processing may be utilized, the KHOROS_HOSTS environment 
variable must be set properly, and the ".rhosts" or ".rhosts.bk" file must be 
made available at the top level directory of the account on which you are 
running Khoros.  Also, to enable distributed processing, a Khoros "phantom"
daemon must be started on each machine which is to execute jobs remotely.
.LP
The KHOROS_HOSTS environment variable simply specifies a file
(by default, ".khoros_hosts") in which all computers which are available for
remote data transport are listed.  
.LP
In addition to setting the KHOROS_HOSTS environment variable properly, it is
essential that you have a ".rhosts" file set up properly before you can use
the distributed processing capabilities of Khoros. The ".rhosts" file contains
a list of host computers.  This file allows a user who has an account on the
local machine to log in from a remote host without supplying a password; more
importantly with respect to the use of distributed processing, it allows the
user to start a process on that remote machine.   To simplify matters, it is
easiest to set up the ".rhosts" file and the ".khoros_hosts" file at the same
time.  They will look identical, except that the ".rhosts" file will have the
addition of the applicable login name appearing after each machine name.
Note: some sites do not allow ".rhosts", so you can use ".rhosts.bk", and
the "phantom" daemon will move ".rhosts.bk" to ".rhosts" temporarily.
.LP
Once the KHOROS_HOSTS environment variable is set, and the ".rhosts" file is
added to the top level of your account, you may use the data transport and 
distributed processing capabilities of Khoros via \fBcantata\fP.  You must 
first use the "Workspace" pulldown menu to pop-up the "Attributes" subform.  
On the bottom left of the "Attributes" subform is the option, "Enable Remote 
Execution".  Set this logical to "Yes".  Now, all glyphs representing Khoros 
Programs will appear with a network symbol in the middle.  Clicking on this 
network symbol will bring up a list of machines. This list of machines is 
called the network browser, and the contents of the network browser is 
dictated by the machines that you listed earlier in your ".khoros_hosts" file 
(or other file specified by KHOROS_HOSTS).  If there is not a ".khoros_hosts" 
file, the initial list of hosts will only include the local machine.  You can
interactively add machine names via the network browser.  Selecting the desired 
machine will cause that program to be run on the specified machine.
.LP
Before programs can be executed on remote machines, a daemon must be started
on that remote machine to run Khoros programs on behalf of the local machine.
Cantata will attempt to start these daemons for you, automatically;  however,
if \fBcantata\fP has problems starting these daemons, you may have to start them
yourself.   Starting the daemons is a simple process; it can be done in one
of two ways.  The first way is to log on to each machine on which programs 
will be executed, and run the \fBphantomd\fP program directly.  Suppose we are 
on machine A, and will be using the distributed processing capability to 
execute programs on machines B, C, and D.  Before attempting to execute 
programs on the three remote machines, we must log on to each of machines 
B, C, and D, and execute:
.br
% phantomd
.br
.LP
The second way to start the distributed processing daemons on the desired
remote machines is to use the \fBphantom\fP shell script on the
local machine, once for each remote machine that is to be used for program
execution.  In this case, we would execute, on machine A:
.br
% phantom machineB
.br
% phantom machineC
.br
% phantom machineD
.sp
.LP
Note that when distributed processing is to be used via
\fBcantata\fP, \fBcantata\fP will remote shell to the machines in question,
and execute the \fBphantomd\fP program for you.  However, if \fBcantata\fP fails
for some reason to start the daemons properly, you will have to use one of the
two above-mentioned methods to start the daemons on the desired remote machines
yourself.  In any case, it is required
that both the KHOROS_HOSTS environment variable and the ".rhosts" file are set
properly before the daemons can be started.  Daemons started in this way have
a 1/2 hour time-out limit set.  Thus, if more than one half hour elapses before
distributed processing is used, you must re-start the daemons again.
If you would like to change the time-out limit, you may use the
[-timeout \fItime\fP] option to either \fBphantom\fP or \fBphantomd\fP, where
\fItime\fP is provided in minutes.
.LP
There are two conventions which
dictate what type of data transport mechanism is to be used, and whether a
routine should be executed on a remote machine.  If no data transport
mechanism is explicitly specified, the Khoros transport and distribution
routines will negotiate the transport mechanism automatically.  However,
if you would like to dictate the data transport mechanism yourself,
then you must follow the two transport specification conventions.
The first convention is used to specify a data transport mechanism:
.br
.in +1i
identifier=token
.in -2i
.LP
Where \fIidentifier\fP is one of the data transport mechanisms listed earlier,
such as "shm", "file" or "socket".
.LP
The \fItoken\fP is the type of identifier for that transport.  For a file, it is
simply the filename.  For shared memory, it is the shared memory key.  For
a pipe, it is the input & output file descriptors, as in "pipe=[3,4]".  For a
socket, it is the number of the socket, as in "socket=5430".
.LP
The second convention is used to specify a remote machine for distributed
processing; it specifies where a token is located.  For instance,
if you want to retrieve a regular file from a remote machine, then the
syntax is:
.in +1i
file=filename@machine
.in +1i
or
.in -1i
filename@machine
.in -1i
.LP
This causes the Khoros I/O routines to look thru the internal list of data
transport mechanisms and select the first available remote transport mechanism.
In the currently available list, this will be "socket".  If a specific remote
transport mechanism is desired, then the following should be used:
.in +1i
filename@socket=machine
.in -1i
.LP
Multiple machine routing is also allowed.  This means that if you cannot
directly access a file from your local machine, but you can access the file
via the machine "gateway", then you may use the following syntax to retrieve
the file:
.in +1i
filename@machine@gateway
.in -1i
.LP
Almost all combinations are allowed, but it is important to remember that
\fIlocal transport mechanisms CANNOT be used with distributed processing\fP.
For instance, the following specification will result in an error:
.in +1i
filename@stream=machine
