Installation on Windows NT
		     ==========================


1. Install Java JDK.  See

    http://www.javasoft.com/products/jdk/1.1/index.html

After Java JDK is installed successfully, you should add the Java JDK
`bin' directory to your path setting, so that tools such as `java', `javac',
and `javah' commands can be found and used sucessfully.  Under NT the
path can be change by clicking on the Control-Panel, then the System
Icon and highlighting `Path' under the Environment tab and adding the
appropriate directory.


2. Install WMPI.  See

    http://dsg.dei.uc.pt/w32mpi/

Instructions can be found in the WMPI documentation.  Additional
information can be found at

    http://www.sis.port.ac.uk/~mab/TOPIC/WMPI/Setup/setting-up-wmpi.html

You should ensure that the directory containing the WMPI file
`cvwmpi.dll' is added to your path environment variable.  Otherwise it
will be necessary to copy `cvwmpi.dll' to the directory where you are
running your code.


3. Now, you are ready to install the mpiJava interface.

   step 1.  Unpzip the software (mpiJava.zip) and extract the software
            onto your system.


   step 2.  Add the installation directory to your CLASSPATH. 

	    For example, if you unzip the package in the directory
	    `c:\users\myhome\', then `c:\users\myhome\mpiJava\lib\classes'
            should be appended to the CLASSPATH.

	    Under NT you follow similar steps to those for changing
	    your Path, to append your CLASSPATH.


   step 3.  Append the mpiJava/bin/WMPI to your systems Path
	    environment variable - this directory is where the C
	    interface to WMPI is installed (mpiJava.dll).


                        Using the software
                        ==================

Go to the directory `mpiJava\tests'

To run all the tests on one machine, you need to run the perl script
`NTrunall.pl'. This file is a very basic  perl script that cd's into each
of the tests  sub-directories and runs another basic perl script, see
for example  `NTrunit.pl'. This perl script runs each test code in the
sub-directory. For each code it copies a version of the JNI interface
to WMPI to the approriate name,  compiles the Java test code, creates a
configuration file ($$.pg) and then runs the test. The output from the
tests will appear in a DOS Console windows. It should be a fairly easy
matter to adapt `NTrunit.pl' to run codes on two or more machines.

Running PingPong 
-----------------

Here is an examples of how to run PingPong... 

Open a DOS console 

    cd mpiJava\examples\pingpong 
    javac *.java 
    copy mpiJava\src\wmpi_jni\Release\WMPI.exe PingPong.exe 

Create a configuration file - `PingPong.pg' - it should contain
something like the following...

    mymachine 0 c:\...\mpiJava\examples\pingpong\PingPong.exe 
    anothermachine 0 c:\...\mpiJava\examples\pingpong\PingPong.exe 

to run PingPong 

    PingPong.exe -p4pg PingPong.pg 

or using the dialog box... 

    PingPong.exe -dialog 


               Notes on recompilation of the library
               =====================================


Compiling the native methods under WMPI (mpiJava/src/C)
-------------------------------------------------------

To create a the mpiJava.dll under NT and WMPI: using Microsoft
Development Studio Visual C++ project file
(mpiJava/src/c/WMPI/WMPI.DSP).  To recompile the library it is
necessary to point to local installations of WMPI and JDK.

     Under "include files" add jdk1.1.X/include and jdk1.1.X/include/win32 
     Under "library files" add jdk1.1.X/lib/  (for javai.lib) and the path
         to the WMPI file cvwmpi.lib. 

Thereafter rebuild your library. 

NB: A potential problem is that Microsoft Development Studio seems to
"hardwire" filenames to absolute paths, so if, during recompilation it
reports a missing file delete the existing reference to it and insert a
new reference to it.

The dll library created must be copied into a directory on your PATH or
you must add mpiJava/src/c/WMPI/Release to your PATH. We sugggest that
mpiJava.dll is copied to the directory mpiJava/bin/WMPI and this
directory is added to your PATH.


Compiling the Java into Class file under NT (mpiJava/src/Java)
--------------------------------------------------------------

The easist way to recompile the files is to cd in mpiJava/src/Java/mpi
and from the command line enter javac *.java

Or alternatively if you have Symantec Visual Cafe you can can use that
to read in mpiJava/src/Java/mpiJava.vep and then remake the classes.

A winzip archive of the Java classes (mpiJava.zip) can be found in the
mpiJava/lib/classes directory.


Driver EXE (mpiJava/src/wmpi_jni)
---------------------------------

Introduction
~~~~~~~~~~~~

This directory contains the source code of the a special executable
file that is needed by WMPI so that the JVM can invoke WMPI. This
executable is needed because WMPI expects a filename with an
.exe when a job is started from a DOS console command line. This is a
feature or idiosyncrasy of
WMPI.

The Function of the WMPI EXE interface is to start a MPI job under WMPI
typically something like the following would be entered at the DOS
prompt:

  myJob.exe -p4pg myJob.pg 

myJob.pg would look something like: 

  myMachineName 0 c:\exedirectory\myJob.exe 
  anotherMachineName 1 c:\exedirectory\myJob.exe 

When myJob.exe runs it reads in and parses the command line arguements
and the configuration file (myJob.pg). This process is termed by WMPI
developers as the Big Master (BM). One BM has parsed the command line
and configurato file it then invokes the processes refered to in the
configuration file - c:\exedirectory\myJob.exe and pasess commands to
them via their command line. The job will then run to completion. The
function of WMPI EXE interface is to emulate what would normally happen
if the MPI job was a C or Fortran executable.

The EXE interface has the following functions: 

   1.It satisfies WMPI's need to have file with an EXE extension to
     start a job.
   2.It reports errors that may occur before the MPI Java class is started. 
   3.It invokes the JVM 
   4.It invokes the "main" method in the class that you wish to run. 
   5.It destroys the JVM 


The EXE interface has the following functionality: 

   1.The C standard command line arguement argv[0] (the file name of
     the EXE being run) is assumed to be exactly the same as the name
     ofthe main class the user wants to invoke (with the file extension
     removed). It should be noted that these filename are CASE
     sensitive.

   2.The CLASSPATH used to invoke the JVM is: 
         * For the BM, that set up by the users environment 
	 * For processes spawned by the BM, it is that determined by the
	   environment of the user who installed the WMPI service
	   daemon. It should be noted here problem may occur due to the
	   fact that the CLASSPATH on remote machine may not have been
	   set up to point to the JVM etc. The EXE interface to WMPI
	   endeavours to report these problems.


To overcome the problems mentioned we have added the ability to the EXE
interface to add directories to the CLASSPATH via an initialisation
file - mpiJava.ini. This file will be searched for when the EXE
interface starts up (it looks in . first and then along PATH).  The
file mpiJava.ini is a normal ASCII file which holds the CLASSPATH. The
syntax of the file is:

  CLASSPATH=c:\Langs\Java\HPJava\mpiJava\tests\PingPong;c:\Java\jdk1.1.4\lib 

The EXE interface parses this file and appends the path onto the
environments CLASSPATH. The appended CLASSPATH is passed to the JNI
struct jvmArgs before being used to invoke the JVM.


Compiling the WMPI EXE Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This directory contains the following files... 

  Debug/              -- The MS-VS C++ Debug "release" directory 
  ICON1.ICO           -- Part of the WMPI Dialog box 
  Main.c              -- Main JNI C interface file to WMPI 
  Release/            -- The MS-VS C++ Release "release" directory -
  WMPI_JNI.exe 
  WMPI_JNI.DSW        -- The MS-VS "Workspace" file 
  index.html          -- This HTML file 
  resource.h          -- A header file needed to compile resources un MS-VS
  C++ 
  vwmpi.rc            -- The WMPI Dialog resource file. 

To create WMPI_JNI.exe under NT  using Microsoft Development Studio
Visual C++ project  file (mpiJava/src/c/WMPI_JNI/WMPI_JNI.DSW).  To
recompile the library it is necessary to point to local installation
and JDK.

     * Under "include files" add jdk1.1.X/include and
       jdk1.1.X/include/win32

     * Under "library files" add jdk1.1.X/lib/  (for javai.lib) 

Thereafter rebuild your the WMPI_JNI.exe - you will find it in the
Release directory.

NB: A potential problem is that Microsoft Development Studio seems to
"hardwire" filenames to absolute paths, so, if during recompilation it
reports  missing files, then delete the existing reference to it and
insert a new reference to it.

The WMPI_JNI.exe created must be copied and renamed to the name of the
Java class that contains the "main" of the mpiJava job that you wish to
run under WMPI.

For example with a class called rsend.class:

  copy mpiJava/src/WMPI_JNI/Release/WMPI_JNI.EXE rsend.exe 
  rsend.exe -p4pg configuration.pg 
  

Things that need to be changed in the next release of mpiJava
-------------------------------------------------------------

The JNI Interface to WMPI should be changed from a Win32 Console
Application to a straight Win32 application - this will stop each
mpiJava process starting up a Win32 console on each machine the job
runs on.