















The National Institute of Standards and Technology

                      (NIST)

  Parallel Applications Development Environment

                      (PADE)

                  User's Manual


                Judith E. Devaney

                  Robert Lipman
                    Minwen Lo

               William F. Mitchell
   Computing and Applied Mathematics Laboratory


                   Mark Edwards

                  Justin Turner
                 Charles W. Clark

                Physics Laboratory

            PADE -- Major Release 1.0
                  March 4, 1995













                            Abstract


This  manual  describes the  Parallel  Applications Development
Environment  (PADE)  developed  at  the  National Institute  of
Standards and Technology (NIST).
   What is PADE?
PADE  is a  flexible,  customizable environment  for developing
parallel  applications that  use  the Parallel  Virtual Machine
(PVM)  message-passing  library.    It  provides  an integrated
framework  for all phases  of development  of a message-passing
parallel  application:   editing,  compilation,  execution, and
performance  monitoring  and enhancement.     The  PADE package
consists  of an  intuitive  graphical user  interface,  a suite
of  PVM utilities,  and extensive documentation  in PostScript,
ASCII, and HTML formats.
   How to get PADE
via the World-Wide-Web:
http://physics.nist.gov/ResOpp/hpcc/pade.html
is  the PADE  home page,  upon  which current  information will
be  maintained.   This is the  recommended approach  to the ftp
archive.
by anonymous ftp:
ftp://gams.nist.gov/pub/pade/
contains the release  of the PADE corresponding to this manual,
as a  file named nist_pade.1.0.x.tar.gz.   The integer x denotes
the  number of  updates  to the  original  1.0.0 release.    No
new  features will  be  added in  any of  these  updates.   New
features  will be  added only  in future major  releases.   New
major releases  will be numbered 1:2; 1:4;:::  and each will be
accompanied with  a new version of this  manual.  by electronic
mail:  pade@cam.nist.gov
is the  email address for questions and  comments about the use
of the PADE. Bug reports may be sent here as well.







   How to use this manual
This manual is  intended to provide a comprehensive description
of  PADE,  from design  concept  through implementation,  which
should enable  the user to perform  actions ranging from simple
operation of the program to modification of its source code.
   However, most  users who want  to use PADE  as a development
tool need not read  this manual in a systematic way.  Operation
of  PADE  via  the  graphical  interface  should be  relatively
intuitive,  so users in  locations where PADE  has already been
installed may  wish to start  by running the  tutorial of Chap.
4.   This exercise uses one  of the elementary example programs
provided in the PVM  package, and thus may offer an easy inroad
to  PVM usage  by the  novice.    Chap.   5  can  be used  as a
reference  for any button,  menu, or  window encountered during
use.
   Those working at sites where PADE has not yet been installed
can install  it following the directions  given in Section 2.5.
No special system privileges are required, though certain other
programs,  described in Chap. 2,  must also run  on the machine
that runs PADE. None of the programs that are essential for the
PADE to run require root privileges, however.
   Pronounciation of the acronym
Some eminent  scientists sprinkle their  speech with foreign or
foreign-sounding  phrases, and  in  emulation of  this practice
we  have  adopted a  pronounciation  of  PADE  ("pah-DAY") that
incidentally   honors  the  French   mathematician  Henri  Pad'e
(1863-1953).   This  is to be  understood as  the default value
of a  preference that may be configured  by the user, like many
other  features of PADE.  However, those who  telephone NIST to
ask how they can get paid may engender a misunderstanding.
   Usage license
The PADE  software and its documentation  have been produced as
part of  work done by the U.S.  Government, and are not subject
to U.S. copyright.
   The mention of specific products, trademarks, or brand names
in PADE  documentation is for  purposes of identification only.
Such  mention  is  not to  be  interpreted  in  any  way as  an
endorsement or certification  of such products or brands by the
National Institute of Standards and Technology.







                               1














Contents



1  Introduction to the NIST PADE                              6
   1.1 Why PADE was developed  . . . . . . . . . . . . . . .  6
   1.2 The virtual development console. . . . . . . . . . .   7
   1.3 How the PADE Works  . . . . . . . . . . . . . . . . .  9
     1.3.1The Anatomy of a PVM Application . . . . . . . . .  9
     1.3.2Operations of the PADE During Parallel Development  12

2  PADE Installation and System Requirements                 13
   2.1 System Requirements. . . . . . . . . . . . . . . . .   13
     2.1.1Systems tested to date . . . . . . . . . . . . . .  14
     2.1.2PADE version numbers . . . . . . . . . . . . . . .  15
   2.2 Contents of the PADE package  . . . . . . . . . . . .  16
   2.3 PADE component descriptions. . . . . . . . . . . . .   18
     2.3.1PADE Interface . . . . . . . . . . . . . . . . . .  18
     2.3.2Pvmmake and NIST CAML utilities  . . . . . . . . .  18
     2.3.3The NIST PADE User's Manual  . . . . . . . . . . .  19
     2.3.4PADE Examples  . . . . . . . . . . . . . . . . . .  19
   2.4 Fulfilling the system requirements  . . . . . . . . .  19
     2.4.1The UN*X commands  . . . . . . . . . . . . . . . .  19
     2.4.2Other standard programs  . . . . . . . . . . . . .  20
   2.5 PADE Installation. . . . . . . . . . . . . . . . . .   22
     2.5.1Installation on the development host . . . . . . .  22
     2.5.2Installation on the other VM hosts . . . . . . . .  25
3  Pvmmake                                                   28
   3.1 Capabilities and Software Components of Pvmmake. . .   28
   3.2 Running Pvmmake. . . . . . . . . . . . . . . . . . .   29
     3.2.1The Pvmmake Config File  . . . . . . . . . . . . .  29
     3.2.2Telling pvmmake to Transfer a File . . . . . . . .  31
     3.2.3Telling pvmmake to Issue a Command . . . . . . . .  32
   3.3 Troubleshooting. . . . . . . . . . . . . . . . . . .   32
     3.3.1The wc error . . . . . . . . . . . . . . . . . . .  32




                               2







4  Running the PADE: A Tutorial                              33
   4.1 Starting the PADE. . . . . . . . . . . . . . . . . .   35
   4.2 Starting the Virtual Machine  . . . . . . . . . . . .  38
   4.3 Entering Setup Information  . . . . . . . . . . . . .  38
     4.3.1Entering host names  . . . . . . . . . . . . . . .  38
     4.3.2Entering host commands . . . . . . . . . . . . . .  39
     4.3.3Entering files using the Setup Files Window  . . .  40
     4.3.4Entering files using the Tree View Window  . . . .  41
     4.3.5Saving the setup information . . . . . . . . . . .  42
   4.4 Building the Parallel Application. . . . . . . . . .   43
     4.4.1Viewing the pvmmake config file  . . . . . . . . .  43
     4.4.2Running pvmmake  . . . . . . . . . . . . . . . . .  43
   4.5 Running the Parallel Application  . . . . . . . . . .  46
     4.5.1Running the application in an xterm window . . . .  47
     4.5.2Running the application using pvmmake  . . . . . .  48
     4.5.3Other pvmmake config files . . . . . . . . . . . .  50
5  The PADE User's Reference                                 52
   5.1 Before the PADE is Invoked  . . . . . . . . . . . . .  52
     5.1.1Environment Variables  . . . . . . . . . . . . . .  52
     5.1.2Helper Programs  . . . . . . . . . . . . . . . . .  53
   5.2 The Main Window and Its Menus and Buttons. . . . . .   54
     5.2.1The Setup Button . . . . . . . . . . . . . . . . .  54
     5.2.2The Run Menu . . . . . . . . . . . . . . . . . . .  55
     5.2.3The PVM Menu . . . . . . . . . . . . . . . . . . .  59
     5.2.4The Monitor Menu . . . . . . . . . . . . . . . . .  63
     5.2.5The Help Menu  . . . . . . . . . . . . . . . . . .  63
     5.2.6The Exit Button  . . . . . . . . . . . . . . . . .  67
   5.3 Entering Info in the Setup Window. . . . . . . . . .   67
     5.3.1General Description  . . . . . . . . . . . . . . .  68
     5.3.2The Add Host Button  . . . . . . . . . . . . . . .  70
     5.3.3The Add Hosts from Hostfile Button . . . . . . . .  71
     5.3.4The Modify Host Button . . . . . . . . . . . . . .  71
     5.3.5The Delete Host Button . . . . . . . . . . . . . .  72
     5.3.6The Setup Files Button . . . . . . . . . . . . . .  72
     5.3.7The Tree View Button . . . . . . . . . . . . . . .  72
     5.3.8The Open File Button . . . . . . . . . . . . . . .  72
     5.3.9The Save File Button . . . . . . . . . . . . . . .  73
     5.3.10The Done Button  . . . . . . . . . . . . . . . . .  73
   5.4 The Setup Files Window  . . . . . . . . . . . . . . .  74
     5.4.1General Description  . . . . . . . . . . . . . . .  74
     5.4.2The Add Entry Button . . . . . . . . . . . . . . .  76
     5.4.3The Copy Entry Button  . . . . . . . . . . . . . .  77
     5.4.4The Duplicate Entries from Host Entry Button . . .  77



                               3







  5.4.5The Modify Entry Button  . . . . . . . . . . . . .  78
  5.4.6The Global Replace Entries Button  . . . . . . . .  78
  5.4.7The Delete Entry Button  . . . . . . . . . . . . .  78
  5.4.8The Edit File Button . . . . . . . . . . . . . . .  78
  5.4.9The Save and Cancel Buttons  . . . . . . . . . . .  79
5.5 The Tree View Window  . . . . . . . . . . . . . . . .  79
  5.5.1General Description  . . . . . . . . . . . . . . .  79
  5.5.2The Tree View Buttons  . . . . . . . . . . . . . .  81
  5.5.3The Context-Sensitive Message Area . . . . . . . .  83
  5.5.4The Tree View Canvas . . . . . . . . . . . . . . .  84




































                            4














List of Figures



   2.1 The PADE directory structure  . . . . . . . . . . . .  17

   5.1 The PADE main window  . . . . . . . . . . . . . . . .  55
   5.2 The RUN main menu. . . . . . . . . . . . . . . . . .   56
   5.3 The PVM main menu. . . . . . . . . . . . . . . . . .   58
   5.4 The MONITOR main menu. . . . . . . . . . . . . . . .   62
   5.5 The MAN menu under the HELP main menu. . . . . . . .   64
   5.6 The WWW menu under the HELP main menu. . . . . . . .   65
   5.7 The PADE setup window. . . . . . . . . . . . . . . .   69
   5.8 The PADE setup files window. . . . . . . . . . . . .   75
   5.9 The PADE tree view window. . . . . . . . . . . . . .   80
























                               5














Chapter 1



Introduction to the NIST PADE



This  chapter  provides   an  overview  of  the  NIST  Parallel
Applications  Development Environment (PADE).  It describes the
motivation  for  its  development  and  basic  aspects  of  its
functionality.


1.1 Why PADE was developed

The goal  of PADE is to facilitate  the development of parallel
applications that run  on a heterogeneous virtual machine, i.e.
a machine composed  of independent computers (its nodes), which
may  be of different  types.   This is a  mode of computational
parallelism  that is growing  in popularity, due  in large part
to  the development of  message-passing libraries,  such as the
PVM program, which  allow such a machine to be constructed from
ordinary workstations that are connected to a network.
   The  perceived  need  for  an  application like  PADE  arose
during the early  ventures of a NIST scientific workgroup while
developing  code for  a  network of  workstations  of different
types.   The complexity  of such development,  compared to that
which  takes  place on  a  single  computer,  begins  to become
apparent  even  for  the  simplest  type  of  application:    a
so-called  "embarrasingly parallel" code  that does essentially
the  same  thing  on all  nodes  of  the  virtual machine,  and
requires  very  little communication  between  nodes.    Such a
code will  have components that  reside on the  file systems of
different  computers with  different  operating systems;  these
components  will have  to  be compiled  on  each node,  usually
with  differing compiler directives  and options;  the compiled


                               6







versions  must be run  on each node;  and the  input and output
streams must be managed on each node.
   Consider the basic  operations that arise in the development
cycle of such a program:

 1.  Editing source files (potentially a different set of files
     for each node on the virtual machine).

 2.  Transferring  sets  of  source  files  between  nodes,  as
     appropriate.

 3.  Compiling  each  set of  source  files  on  each node  (in
     a  heterogeneous   environment,  the   compiler  for  each
     architecture or even each node may be slightly different).

 4.  Executing the updated program.

Steps  two and  three can  become quite  time consuming  as the
number of  nodes increases, even if  the variation of operating
systems between  nodes is relatively  minor (e.g.   if they are
different  variants of  Unix).   Also,  keeping track  of which
source files require  editing in step one can also become quite
cumbersome.   Thus, even  "embarrassing" applications induce an
accounting burden  that grows with  the number of nodes.   When
one  moves beyond  embarrassment  to applications  that involve
significant  communication between  nodes, the  difficulties of
maintaining program coherence during the process of development
can become quite daunting.


1.2 The virtual development console

The basic  concept of PADE is to  provide a development console
for  the  virtual  machine,  so  that  all  essential  parallel
development  tasks can  be carried out  at a  central location.
This  central location, the  development host,  is the computer
where  all source files  for the parallel  application are kept
and  is where  PADE is  executed.    PADE provides  a graphical
interface  to the  operations  of the  virtual machine.    PADE
allows the  following tasks to be  performed on the development
host, with transparent access to the other nodes of the virtual
machine:




                               7







  o  Defining  the  virtual  machine,   i.e.,  identifying  the
     computers  that will  run  the various  components  of the
     parallel application;

  o  Organizing the application source files;

  o  Editing  source  code   appropriate  to  each  host  while
     retaining all  source files  in a  common location  on the
     development host;

  o  Building   the   parallel   application   with  a   single
     command,  operations  that are  launched  by  this command
     include  sending  files  to   all  nodes  of  the  virtual
     machine (optionally  including makefiles)  and issuing the
     appropriate compile command on each node;

  o  Reviewing compilation and execution output in a scrollable
     window;

  o  Executing  the application  on the  virtual  machine, with
     or without  the aid of parallel  debuggers and performance
     monitors;

  o  Accessing online help


      --  this manual;

      --  introductory PVM man pages;

      --  the PADE World-Wide-Web (WWW) home page;

      --  the Guide to Available Mathematical Software (GAMS).


   A graphical interface is  an essential aid for keeping track
of  the application,  as it  enables one  to visualize  how the
various  parts of  the application  are distributed  across the
virtual machine.   The current relaease  of PADE offers a "tree
view"  representation of the  virtual machine,  which shows the
nodes and  their associated program  files on a two-dimensional
diagram.  Many  of the file and command management actions that
are required during  application development can be carried out
by  familiar "click  and drag"  operations  on objects  in this


                               8







diagram, which simplifies much routine administrative work that
would otherwise distract the programmer's attention.
   Parallel application  development is an  evolving art, whose
future  needs are  difficult to  envisage.   We  have therefore
designed  PADE to be  extensible and configurable  by the user.
This  has been  done by  building  PADE from  standard software
components.   These  components all have  open definitions, are
freely  and widely available  over the Internet,  and have been
relatively  robust  over time.    Many  of  them  will probably
already  have  been installed  on  a workstation  in  a typical
scientific  or  engineering   environment.     If  any  of  the
components  are not installed,  the user user  can install them
without having root privileges


1.3 How the PADE Works

Central to  the operation of  a program like PADE  is a vehicle
for  passing messages  between nodes,  i.e.,  a message-passing
library.   PADE is based upon  the widely used Parallel Virtual
Machine  (PVM)  message-passing library  developed  at  the Oak
Ridge  National  Laboratory.    Indeed,  it  is  appropriate to
regard  PADE as  a  PVM application,  in  that it  utilizes PVM
calls for  all communication between  processors of the virtual
machine.  Since  these calls are of a character that appears to
be generic to message-passing libraries, implementation of PADE
in alternative  message-passing software should  be possible by
straightforward modification of the source code of PADE (and of
the core utility pvmmake, which is described in Chapter 3).
   To understand how PADE  works, it is probably best to review
some of the typical features of a PVM application.

1.3.1 The Anatomy of a PVM Application

The  PVM  software   enables  a  user  who  holds  accounts  on
several networked computers  to write applications in which the
collection  of computers  perform parts  of the  application in
parallel.   This group of computers  can be considered, for the
purposes  of programming, as  a virtual machine  (VM). All that
is required of  the computers is that they can communicate with
each  other over (at  least) a  TCP/IP connection.   If  all of
these machines are  part of the Internet, then this requirement
is  already satisfied.   Each  computer on the  virtual machine
will somtimes be referred  to as a node and somtimes as a host.


                               9







These two terms will be used interchangibly in this manual.
   The  VM  can consist  of  nodes  that are  identical.    For
example,  an IBM SP2 computer  consists of a  number of RS/6000
processors  whose communications  hardware is much  faster than
the  ordinary TCP/IP  links on  the Internet.   Such  a machine
will be  called a homogeneous  virtual machine.   Other virtual
machines can consist  of many different processor types.  These
virtual machines  will be referred  to as heterogeneous virtual
machines.    The  PADE  is most  effective  in  aiding parallel
development on the latter type of virtual machine.
   An example VM could consist of the following machines:

  o  mithrandir.nist.org -- An IBM RS/6000 running AIX;

  o  galadriel.nist.org -- An Intel i486 running Linux 1:0:9;

  o  shadowfax.nist.org -- A  SUN SparcStation 20 running SUNOS
     4:1:3;

  o  elrond.nist.org --  A Silicon  Graphics Onyx  running IRIX
     5:2;

This  heterogeneous VM will  be used  as an ongoing  example in
this  manual for illustrating  many aspects  of PADE operations
and usage.
   A  working  PVM application  on  a  virtual  machine several
consists  of two  parts.    First, the  VM  must be  created by
installing the PVM software on each of the computers comprising
the  VM. How  this is  done is  well beyond  the scope  of this
manual and will hereafter be assumed to have already been done.
The  basic software  consists  of two  programs:   (1)  the PVM
daemon (pvmd3)  and (2) the PVM console (pvm).   The PVM daemon
can  be started with  a hostfile which  is a  file containing a
list of the computers  that make up the VM. The PVM daemon will
then start  similar daemons on  the other hosts  listed in this
file.  The  PVM console is an interactive program which enables
the  user to  (among other  things) add  hosts to,  monitor the
status of, and list the jobs running on the VM.
   The second  item needed to create  a working PVM application
is  a set  of files  containing  source code  (written in  C or
FORTRAN)  that has  been  instrumented with  PVM calls.    Some
subset of  these source files will be  compiled on a given host
of  the VM  to create  a binary  that is  the component  of the
entire PVM  program for that host.   The subset of files needed


                               10







to create this executable may vary from host-to-host.  This may
be the case for several reasons some of which include

  o  the portion of the task to be performed by the application
     allotted to  a particular  host is different  from another
     for load-balancing reasons (some  hosts may be faster than
     others);

  o  non-portability of the code;

  o  host-specific code optimizations;

  o  a  different makefile  (if the  make  program is  used) is
     required  for compilation  on  each host  since  there may
     be different  compiler names,  library paths,  and include
     paths.

The  creation of the  binary on a  given host  will require the
transfer of files to that host and the launching of the compile
command.
   A simple  example of a  PVM application  is the master/slave
program  suite provided  with the  PVM distribution.    In this
example, a facilitator  program is launched on one of the nodes
of  the VM.  This  program first  queries  the user  as  to how
many copies  of the co-facilitator program to  launch.  It then
launches  them alloting one  to each node  on the  VM until all
nodes are running at  least one.  When a co-facilitator program
finishes,  the facilitator program  launches a new  copy of the
co-facilitator until  the total number  of facilitator programs
launched  equals  the  number specified  by  the  user.    Each
co-facilitator program receives some data from the facilitator,
does  some calculations,  passes some  information to  the next
node  in line,  sends some  data back  to the  facilitator, and
exits.   The  facilitator program  accepts this data  from each
co-facilitator and writes it to standard output.
   An example  parallel program  is provided with  the standard
PADE  distribution and is  a variation  on the the  PVM example
described  above.    The  PADE  example  program  will  be used
extensively  in  the  PADE  tutorial  found  in  Chapter 4  for
illustrating  the use  of the  PADE and is  referred to  as the
manager/worker example.





                               11







1.3.2 Operations of the PADE During Parallel Development

The two ways in  which the PADE aids the parallel developer are
by helping to keep track of which source files must be sent and
compiled on  which hosts and by actually  sending the files and
issuing the  compile commands.  In  the PADE development model,
the  developer keeps  all source  files on  a single  host (the
development  host) and is  required to  enter the names  of the
hosts, the  files needed to build the  binary on each host, and
the commands  required to build the binary on  each host.  This
information is  referred to in  the rest of this  manual as the
setup information.
   Once the  setup information has been  entered, the developer
begins   the   edit/transfer/compile/execute   cycle  described
earlier.   In  the edit phase,  the PADE  enables the developer
to  modify any  file described  in  the setup  information with
a  user-specified editor.   The  PADE enables the  developer to
complete  the transfer  and compile  phases in one  step.   The
PADE  uses  the  PVM  program  pvmmake  (provided  in the  PADE
distribution) to perform these  steps.  This program can send a
file to  any host and issue  any command on  any host and takes
its orders  from a pvmmake "config file".   The PADE translates
the setup information into pvmmake commands and writes a config
file.    It  then executes  pvmmake  with this  config  file to
affect  the transfer and  compilation.   The developer launches
these  operations with a  click of  the mouse.   The  PADE also
exhibits the  results of the compilations  on the various hosts
in a display window that can be scrolled through at leisure and
saved if desired.  In the execution phase, the PADE enables the
developer to launch the application being developed and to view
the output in a display window.















                               12














Chapter 2



PADE Installation and System Requirements



This chapter provides a description of the systems on which the
PADE runs,  PADE software components,  supporting software used
by the PADE but not included, and PADE installation.


2.1 System Requirements

The  NIST PADE is  designed to execute  on workstations running
the  UN*X operating  system  and its  variants.    Most  of its
functionality consists  of executing other standalone programs.
These programs therefore  define the basic system requirements,
which can be summarized as follows:

  o  PADE needs to run on only one node of the virtual machine,
     called the development host.  Communication among nodes is
     handled by  a message-passing library (PVM),  and the only
     requirement upon the other nodes is that they support that
     library.   Operation of  the PADE takes  place entirely on
     the development host.  The pvmmake utility, which performs
     all essential file transfers  and command executions, must
     be installed on all nodes of the VM, however.

  o  The  development   host  must  run   basic  UN*X  commands
     (including  in  particular man,   col,  and wc),  and  the
     X-windows windowing  system.    In addition,  it essential
     that  the development  host  run  the  following programs,
     which are freely available over the Internet:




                               13







      --  PVM (version 3.0 or later)

      --  Tcl/Tk (version  7.3 of  Tcl, version  3.6 of  Tk, or
          later)


  o  Obtaining  PADE's  full  functionality  requires that  the
     development host  run the following  programs, also freely
     available over the Internet


      --  XPVM

      --  Mosaic, or any other X-Windows-based WWW browser



Information  on  how  to get  these  programs  is  contained in
Section 2.4 below.
   A  key tenet  of the  PADE design  concept  is that  it must
enhance the utility  of the underlying message-passing library,
and  thus it must  be accessible to  any user  of that library.
Thus,  like  all  the  programs  itemized  above,  PADE can  be
installed  by  any user;  no  system  privileges  are required.
However,  the  installer will  need  to know  the  locations of
certain system resources, as described in Section 2.5.

2.1.1 Systems tested to date

The  development team has  run PADE on  the following operating
systems and computers to date:

  o  NeXT OS 3.1/NeXT Motorola 68040

  o  NEXTSTEP 3.2/Intel Pentium

  o  AIX 3.2.5/IBM RS/6000

  o  IRIX 5.2/Silicon Graphics Onyx

  o  SunOS 4.1.3/SUN SparcStation 20

  o  Linux 1.0.9/Intel 80486



                               14







This list  is presented to  indicate the range  of testing that
has  taken place,  not  as a  guarantee  of performance  on any
particular system.  We would appreciate reciving information on
usage on other systems.   Send electronic mail to the following
address.

pade@cam.nist.gov

It  should  be kept  in  mind that  the  functionality  of PADE
depends  upon that of  the other programs  mentioned above, and
the recommended first step in troubleshooting is to verify that
they are properly implemented on the development host.

2.1.2 PADE version numbers

This manual describes  the motivation, installation, and use of
version 1:0:x  of the PADE program.   PADE version numbers have
the general  form z:y:x where  x, y, and  z are integers.   The
number  z:y labels  a major  release version of  the PADE  if y
is  an even integer.   For  example, the  current major release
version is 1:0 and  the next major release will be version 1:2.
Major development  versions of the PADE  are labeled by numbers
in  which y  is an  odd integer.   These  versions of  the PADE
are distributed internally  at NIST and are not released to the
public.  A major  release of the PADE can be considered to be a
stable version.  No new features will be added to a given major
version once it has  been released.  The only changes that will
be made to such a version, after its release, will be bug-fixes
that have been reported  by users.  The integer x appended to a
major release  version number (e.g., z:y)  is the minor version
number for that major release and indicates the number of times
that  release has been  updated.   For example,  a PADE version
labeled 1:0:6 will  have had six patches applied to the initial
(1:0:0) release of major version 1:0.
   Each major  version of  the PADE  will have  a corresponding
version  of  the   NIST  PADE  User's  Manual  devoted  to  it.
The  manual will  not  be updated  for  different minor-version
releases, however.   The manual only describes the features and
capabilities of a given major version and these will not change
in later  releases of the same major  version.  Any information
that  a user  may require  because of changes  made in  a minor
release will  be documented in a  RELEASE-NOTES file located in
the top PADE directory.  This file is described below.
   New   major  versions   of   the  PADE   will   be  released


                               15







periodically.  A new major version will be released for several
reasons some of which include the following.

  o  A major change has been made in the user interface.

  o  New features or capabilities have been added.

  o  Changes  have  been made  in  the  PADE  so  that it  will
     interoperate with new versions of Tcl/Tk or PVM.

  o  Support is added for a new message-passing library.


2.2 Contents of the PADE package

The    PADE   package    is   supplied    as   a    tar   file,
nist_pade.1.0.x.tar.gz,  that  has  been  compressed  with  the
GNU gzip utility.  The package can be obtained by following the
instructions on the PADE WWW page

http://physics.nist.gov/ResOpp/hpcc/pade.html

For those without access to a WWW browser, the PADE package can
be obtained by anonymous ftp at

ftp://gams.nist.gov/pub/pade/nist`pade.1.0.x.tar.gz

Unpacking  this  file creates  a  directory  structure  that is
depicted  in Fig. 2.1.    This directory structure  consists of
the top  directory (entitled nist_pade) and four subdirectories
pade, caml_utils, pade_doc, and examples.
   The  top nist_pade directory  contains  the  following three
(ASCII) files.

  o  RELEASE-NOTES  --  this  file  describes  any  changes  or
     additions to  the PADE package  that did not  make it into
     this manual.

  o  INSTALL  -- a  brief  guide to  installation  of  the PADE
     package.

  o  MANIFEST -- a complete listing of all files that should be
     found in the package.



                               16







The rest of the PADE package has four prinicipal components:

 1.  PADE Interface  -- A set  of Tcl/Tk  scripts that together
     implement  the graphical  user  environment  of  the PADE.
     These scripts are contained in the pade subdirectory under
     the top PADE directory.

 2.  Pvmmake  and  NIST CAML  utilities  --  Pvmmake  is a  PVM
     program  written in  C  that performs  the  essential file
     transfer  and  compilation  functions  of  the  PADE.  The
     utilities  pvmstat,   pvmtidy,   and  pvminituser  perform
     various  PVM-related  housekeeping  functions  within  the
     PADE. These  programs were  developed by staff  members of
     the Computing and Applied Mathematics Laboratory (CAML) at
     NIST. They are located in the caml_utils subdirectory.

 3.  The NIST PADE  User's Manual --  This document provided in
     both PostScript and ASCII paper formats as well as an HTML
     version that is accessible from the PADE Help menu.  These
     documents are located in the pade_doc subdirectory.

 4.  PADE Examples  -- A  set of sample  files to  aid the user
     in following the  manager/worker example described in this
     manual.   A PADE setup script that  must the edited by the
     user is  also  included.   These  files  are found  in the
     examples subdirectory.

When  the file is  successfully unpacked, the  PADE source code
will occupy the directory structure depicted below.











           Figure 2.1:  The PADE directory structure





                               17







2.3 PADE component descriptions

In this section, the functions of the several components of the
release package are described.

2.3.1 PADE Interface

The  graphical   user  interface  presented   by  the  PADE  is
implemented  in  a set  of  scripts which  are  written  in the
Tcl/Tk  language.   These scripts require  the Tcl/Tk windowing
shell program  (i.e., wish)  in order to  run.   Version 7.3 of
Tcl  and version 3.6  of Tk  are required  for the PADE  to run
successfully.    A detailed description  of the  PADE interface
is  provided in Chapter  5 and tutorial  for using  the PADE in
parallel development is given in Chapter 4.


2.3.2 Pvmmake and NIST CAML utilities

The  programs pvmmake, pvmstat,  pvmtidy,  and pvminituser were
developed  in  the   NIST  Computing  and  Applied  Mathematics
Laboratory  to facilitate  general PVM development.    They are
quite  useful  as  stand-alone  applications.     One of  them,
pvmmake,  is absolutely essential  for the PADE  to perform its
basic operations.  They perform the following tasks.

  o  pvmmake  -- The  pvmmake  program provides  both  the file
     transfer and  command execution capabilities  of the PADE.
     It is  a PVM program that  can be used  on its own.   This
     program  is  described  in  detail  in  Chapter 3.     The
     prospective PADE  user is encouraged to  read this chapter
     carefully as a  full understanding of pvmmake command-file
     syntax is important for effective use of the PADE.

  o  pvmstat --  The pvmstat program  returns information about
     the status of the  user's virtual machine, whether PVM has
     been started, and the current configuration of the virtual
     machine.  It consists of a single C program.

  o  pvmtidy -- The  pvmtidy program enables  the user to clean
     up hopelessly  lost PVM  daemons and user  processes after
     PVM is  halted ungracefully.    It consists of  two script
     files and one C program.



                               18







  o  pvminituser -- The pvminituser  program enables a PVM user
     to build the correct PVM file structure in his or her home
     directory.  It consists of a single script.

2.3.3 The NIST PADE User's Manual

This  manual which is  provided in PostScript,  ASCII, and HTML
versions.    The PostScript  and ASCII  versions are  ready for
immediate printing.   The  HTML version can be  accessed by the
user from within the PADE.


2.3.4 PADE Examples

The  examples  subdirectory  contains  files  that support  the
manager/worker example in  this manual.  These supporting files
include  the source  code for this  PVM application  along with
pvmmake  config  files and  sample  output.    A  setup script,
pade_setenv, is also  included to aid  the user  in setting the
environment  variables and path  directories needed  to get the
PADE started.


2.4 Fulfilling the system requirements

We describe here the specific nature of the system requirements
enumerated in  Section 2.4 above, and  provide some guidance as
to how they can  be fulfilled if they are not already supported
on the development host.

2.4.1 The UN*X commands

Several   commands  that  are   supported  in  most,   but  not
necessarily  all, variants  of UN*X  are executed by  PADE. The
user  should verify  that these commands  are available  on the
development host:

  o  man and col -- PADE executes the man program piped through
     the  col program  in  order to  display  man pages.    The
     col  program filters  reverse  line feeds  from  its input
     and is  used  for proper  formatting of  man pages  in the
     display window.  These  programs are included in most UN*X
     operating systems.



                               19







  o  wc -- The  word count (wc) program  is executed by pvmmake
     to  determine PVM  packing  information  when transferring
     files.   This program  is included in  most UN*X operating
     systems.  The user  should note carefully the last section
     in Chapter 3 with regard to the wc program.

  o  use of  man pages  -- PADE  provides online access  to man
     pages that  provide basic  descriptions of PVM.  These man
     pages are provided with  the standard PVM distribution and
     therefore can be accessed by the man program by augmenting
     the MANPATH environment variable.


2.4.2 Other standard programs

As summarized  in Section 2.1 above, PADE  requires a number of
external  programs to exercise  its full functionality.   These
programs  will be  well-known to  most experienced  UN*X system
administrators.  We do not provide documentation for them here,
nor  does  the PADE  install  package provide  any  support for
installing them.  However, for the sake of completeness we give
here the locations of their Internet repositories.

  o  PVM  --  The   Parallel  Virtual  Machine  message-passing
     library is  a  software system  that enables  a collection
     of heterogeneous  computers to be  used as  a coherent and
     flexible  concurrent computational  resource.     The most
     recent version as of this writing is 3.3.6.  This software
     can be obtained by anonymous ftp to


     ftp://www.netlib.org/pvm3


     Installation of this software  on all nodes of the virtual
     machine is essential.

  o  Tcl/Tk --  Tool  Command Language  (Tcl) is  an embeddable
     scripting  language  written  by  John Ousterhout  of  the
     University of California at Berkeley.   ToolKit (Tk) is an
     X11 toolkit that  provides the Motif look  and feel and is
     implemented in Tcl.   Both of these programs are available
     by anonymous ftp at the following site.



                               20







   ftp://ftp.cs.berkeley.edu/ucb/tcl


   PADE currently runs  under Tcl version  7:3 and Tk version
   3:6.

o  XPVM -- XPVM  is a graphical console  and monitor for PVM.
   It  provides  a graphical  interface  to  the  PVM console
   commands  and  information,  along  with several  animated
   views to  monitor the  execution of  PVM programs.   These
   views  provide information  about  the  interactions among
   tasks in  a parallel PVM  program, to  assist in debugging
   and performance  tuning.   XPVM is  available by anonymous
   ftp from the address.


   ftp://www.netlib.org/pvm3/xpvm


   This  program  is  also  a  Tcl/Tk  application  and  will
   definitely be  compatible with  the PADE  only if  it runs
   under the same versions of Tcl and Tk.

o  World-Wide-Web browser  -- PADE's  on-line help  and local
   manual browsing  capabilities require  a program  that can
   interpret  hypertext  markup  language  (HTML) and  access
   documents  on   the  World-Wide-Web.      There  are  many
   WWW  browsers,  and  PADE can  be  configured  to  use any
   that  run  under X-windows.     Two  common browsers  are:
   Mosaic, produced by  the National Center for Supercomputer
   Applications  (NCSA),   is  available   at  the  following
   address:


   ftp://ftp.ncsa.uiuc.edu/pub/Mosaic ,


   and   Netscape,   produced   by   Netscape  Communications
   Corporation, is available at


   ftp://ftp.mcom.com  .




                             21







     Both Mosaic and  Netscape can also  be found on unofficial
     mirror sites, such as the following.


     ftp://sunsite.unc.edu/pub/packages/infosystems/WWW/clients


     Mosaic is set as  PADE's default WWW browser; instructions
     on reconfiguring this preference are contained in Chap. 5.
     Mosaic and  Netscape are the  only WWW  browsers that have
     been tested with the PADE.


2.5 PADE Installation

This section  describes the installation of  PADE on the user's
virtual machine.   The installation  procedure divides into two
major tasks:   (1) installation of the  PADE interface and NIST
CAML  Utilities on the  development host,  and (2) installation
of the  NIST CAML Utilities  on all other hosts  of the virtual
machine.   For  all hosts on  the VM  including the development
host, the  procedure for installing the  NIST CAML Utilities is
the same.   It is recommended that the user install the PADE on
the development host (i.e.,  the host where the user intends to
keep parallel-appplication source files) first and then install
the utilities on the other hosts.

2.5.1 Installation on the development host

Unpacking the PADE source files

The PADE  source for major  version 1:0 is contained  in a file
named

nist`pade.1.0.x.tar.gz ,

where  x is the  minor version  number as described  in Section
2.1.2.  This file can be unpacked in any directory in which the
user has write  privileges; the installation can be carried out
in any directory.  Unpacking this file is done with the command

gunzip < nist`pade.1.0.x.tar.gz _ tar -xvf -




                               22







This  command  will create  the  directory  structure described
at  the beginning of  this chapter  and unpack the  PADE source
files into  these directories.   Once the PADE  source has been
unpacked,  the user  should  change to  the nist_pade directory
and  check that  all files  that are supposed  to be  there are
actually  present.   The MANIFEST file,  found in  the top PADE
directory contains a  complete listing of all files that should
be present.

Installation of the PADE interface and NIST CAML Utilities

Once  the source  is  unpacked,  the rest  of  the installation
consists of the following steps.

  o  Installation  of  the PADE  interface  --  The  first line
     in the  main PADE  Tcl script  must be  edited so  that it
     points to the Tk windowing  shell program wish.  This file
     is located  in the  pade subdirectory  under the  top PADE
     directory and has  the name pade.   The first line of this
     script must have the form:


     #!<directory-path-to-wish>/wish -f


     where  the  angle-brackets   expression  above  should  be
     replaced by  the absolute  pathname of the  directory that
     contains  the wish  program.    Note:   some  systems will
     misbehave  in confusing  ways  if the  first  line  of the
     script file  is longer  than 32  characters, so  beware if
     the  full path  name of  the  wish binary  is  longer than
     27 characters.   If  this happens,  the user  can create a
     symlink in the nist_pade/pade directory to the wish program
     as follows


     ln -s <directory-path-to-wish>/wish ./wish


     and then alter the script to read


     #!<directory-path-to-the-symlink>/wish -f



                               23







   where  the angle-brackets  expression  should  be replaced
   with the absolute pathname of the directory where the pade
   is located.   If wish  cannot be found, it  is likely that
   the Tcl/Tk software  is not installed.   The PADE will not
   run unless the Tcl/Tk software is present.

o  Installation of  the NIST  CAML Utilities  -- Installation
   of  the utilities  on  the development  host  requires six
   steps.    These  steps are  also  required  for installing
   the utilities on  the other nodes  of the virtual machine.
   For the  other nodes,  however, some  additional packaging
   and file-transfer  steps  are required.    Installation of
   the  utilities on  other nodes  is  addressed in  the next
   section.  The activities for installation of the utilities
   on the development host for  a user who does not have root
   privileges are as follows.


    1.  Change to  the caml_utils  subdirectory under  the top
        PADE directory.

    2.  Edit the file pvminituser.   Set the variable PVMHOME
        in this  file  to the  absolute pathname  of  the top
        directory of the installed PVM software.

    3.  Type the following command at the UN*X prompt.


        pvminituser


        This command will create a PVM directory structure in
        the user's home directory with symlinks to the actual
        place where  the  PVM binaries  are located.    Note:
        This step should  be omitted if the  PVM software has
        been installed by  the user rather than  in a central
        location by  a system  administrator.   If  this step
        is performed, the user  should additionally reset the
        PVM_ROOT environment variable.  For UN*X shells csh or
        tcsh execute the following command.


        setenv PVM`ROOT $HOME/pvm3



                             24







          For UN*X shells sh, ksh, or bash execute the command.


          export PVM`ROOT=$HOME/pvm3


      4.  Edit the  file Makefile.aimk.    Set  the environment
          variable  PVMDIR  in   this  file   to  the  absolute
          pathname of  the top directory  of the  installed PVM
          distribution (the pathname as in the previous step).

      5.  Type the following command at the UN*X prompt.


          aimk


          This  command   will   create  architecture-dependent
          executables in an ARCH subdirectory  of the caml_utils
          directory, where ARCH is  the host architecture name,
          e.g., SUN.

      6.  Type the following command at the UN*X prompt.


          aimk install


          This command will install the NIST CAML Utilities, by
          default, in the  directories' files  in the following
          directories:


          $PVM`ROOT/bin and $PVM`ROOT/bin/$PVM`ARCH


          Note:   System administrators  will probably  want to
          replace bin with lib in the Makefile.aimk script.


2.5.2 Installation on the other VM hosts

The  NIST CAML Utilities  must also  be installed on  the other
nodes of  the virtual machine.   The only  extra steps that are


                               25







required to perform  these installations, after installation on
the development host is complete, consist of the following.

  o  Repacking  the  NIST  CAML  Utility  source files  on  the
     development host.

  o  Transferring the source files to each host of the VM.

  o  Unpacking the utility source files on each host.

Once these steps  have been done, installation of the utilities
proceeds  in  exactly the  same  way as  was  described  in the
previous subsection.

Repacking the source files

To  repack the source  files perform the  following steps while
logged in to the development host.

 1.  Change to the top directory of the PADE distribution.

 2.  Issue the following command at the UN*X prompt.


     tar -cvf caml`utils.tar caml`utils


     This command will create a tar file called


     caml`utils.tar


Transferring the source files

Transfer the file

caml`utils.tar

to each  of the other  hosts on the virtual  machine using ftp.
If a  group of hosts have a  common filesystem, then the source
need only be transferred to one host of this group.




                               26







Unpacking the source files

On  each  host to  which  the utility  source  files  have been
transferred,  unpack  the files  (in any  directory)  using the
command

tar -xvf caml`utils.tar

This command will create  a caml_utils subdirectory in whichever
directory the tar file  was unpacked.  Installation of the NIST
CAML  Utilities on this  host can  now proceed as  described in
Subsection 2.5.1.


































                               27














Chapter 3



Pvmmake



This chapter  discusses the function  and operation of pvmmake,
the  utility  that mediates  all  communications  made  by PADE
between  the development  host and other  nodes of  the virtual
machine.   The  actions of  pvmmake usually take  place without
the  need  for  attention by  the  user.    However,   if there
is  a  problem during  the  file-transfer  or command-execution
operations performed by  pvmmake, an understanding of the (very
simple) pvmmake command syntax is essential for determining the
problem.  The  reader is enouraged to read through this chapter
carefully.


3.1 Capabilities and Software Components of Pvmmake

Pvmmake   is   a   PVM   application,   which   uses  the   PVM
message-passing library to perform two basic operations:

  o  File transfer --  Pvmmake can send  an arbitrary text file
     from one arbitrary host to another arbitrary host.

  o  Command execution -- Pvmmake  can issue an arbitrary shell
     command on  an arbitrary host.   Thus  pvmmake can execute
     UN*X  commands  and  shell  scripts  as well  as  compiled
     programs.    Furthermore,  the output  of  these commands,
     scripts, or programs can be piped back to be viewed on the
     node where pvmmake was launched.

The fact that pvmmake performs just these two basic operations,
makes  the program very  flexible, powerful,  and very  easy to


                               28







use.   The PADE can be viewed as  being essentially a shell for
running pvmmake.
   The  pvmmake  utility  consists  of  two executables:    the
pvmmake  binary and  the targets  binary.   (In order  to avoid
confusion,  the term  pvmmake will  denote the  entire parallel
application  consisting  of the  pvmmake  and  targets binaries
located on  all nodes of  the VM). Both of  these binaries must
reside on every node of the virtual machine for pvmmake to run.
The three source files

  o  pvmmake.c

  o  targets.c

  o  jlib.h

only are required to build pvmmake binary and targets.


3.2 Running Pvmmake

When pvmmake  is launched from  the command line  it launches a
copy of the targets  binary on each node of the virtual machine
and then  reads and performs all of  the commands listed in the
pvmmake  config file.   Note that  if pvmmake  cannot start the
targets program on all nodes of the virtual machine (which must
already be running), it prints an error message and exits.
   The syntax for starting pvmmake is as follows

pvmmake [-f pvmmake`config`file]

If  pvmmake   is  launched  without   the  optional  file  name
parameter,  then the  program looks  for a default  config file
named pvmmake.config.   If it does  not find this file, pvmmake
prints an error message  and exits.  The PADE essentially works
by processing  the information entered in  the Setup Window and
writing  a pvmmake  config  file.    The user  can  then launch
pvmmake to execute the commands contained in this file.

3.2.1 The Pvmmake Config File

The pvmmake  config file can  be created with  an ordinary text
editor.    Thus pvmmake  can be  used in  parallel applications
development  by  those  users who  do  not  have  access  to an


                               29







X-Windows environment.   The syntax of  commands in the pvmmake
config  file is  quite  simple and  is best  illustrated  by an
example.   The example  config file presented  here was written
by the PADE and comes from the manager/worker example described
earlier.   The example config file is  given below and has been
edited for formatting's sake.


#  PVMMAKE configuration file written by PADE

#--------------------
#  broadcast FILES to galadriel.nist.org

manager.c
galadriel.nist.org manager.c

worker.c
galadriel.nist.org worker.c

makefile.galadriel
galadriel.nist.org makefile.galadriel

#--------------------
#  broadcast COMMANDS to galadriel.nist.org

@ galadriel.nist.org make -f makefile.galadriel +errors

#--------------------
#  broadcast FILES to shadowfax.nist.org

manager.c
shadowfax.nist.org manager.c

worker.c
shadowfax.nist.org worker.c

makefile.shadowfax
shadowfax.nist.org makefile.shadowfax

#--------------------
#  broadcast COMMANDS to shadowfax.nist.org

@ shadowfax.nist.org make -f makefile.shadowfax +errors



                               30







#--------------------
#  broadcast FILES to elrond.nist.org

manager.c
elrond.nist.org manager.c

worker.c
elrond.nist.org worker.c

makefile.elrond
elrond.nist.org makefile.elrond

#--------------------
#  broadcast COMMANDS to elrond.nist.org

@ elrond.nist.org make -f makefile.elrond +errors


The above example  is discussed in the next two subsections and
in more detail in the PADE Tutorial given in Chapter 4

3.2.2 Telling pvmmake to Transfer a File

The  syntax for the  pvmmake file-transfer  command consists of
two elements.  These elements are

  o  The  full  path   name  of  the   local-host  file  to  be
     transferred.

  o  One or  more  lines each  containing two  items:   (1) the
     name of  a host  to which  the file  must be sent  and (2)
     the  file's  location on  that  host.     These two  items
     must be  separated  by whitespace.    This list  of remote
     hosts/locations must be terminated by a blank line.

Note  that  local-host  refers to  the  computer  on  which the
pvmmake binary was  launched; remote-host refers to any node of
the virtual machine.
   The  general  file-transfer  syntax  can  be  summarized  as
follows.

file`name`on`local`host
remote`host`1     filename`on`remote`host`1
remote`host`2     filename`on`remote`host`2


                               31







...               ...
remote`host`N     filename`on`remote`host`N
<BLANK LINE>

Note that  any line in the  config file that  begins with the #
character  is considered  to be  a comment.   A  comment cannot
take  the place of  a blank  line in the  above.   For example,
in  the beginning  of the  above config  file, the  three files
manager.c,  worker.c,  and  makefile.shadowfax  are transferred
from  the development  host  mithrandir.nist.org to  the remote
host galadriel.nist.org.

3.2.3 Telling pvmmake to Issue a Command

The syntax  for telling pvmmake to issue  a command on a remote
host has the following form:

@ remote`host command`1; command`2;...command`N [+errors]

The first  character on the  line must be  the @ symbol.   This
is  followed by the  name of the  host on  which the command(s)
are to  be issued which  is, in  turn, followed by  one or more
commands separated  by semicolons.   For example,  in the above
makefile,  the first  command issued  is the "make"  command on
galadriel.nist.org.   An  optional argument +errors  is used to
tell  pvmmake  to send  any  output generated  by  the commands
issued back to the host on which pvmmake was launched.


3.3 Troubleshooting


3.3.1 The wc error

On some  hosts, pvmmake has difficulty  finding the wc program.
Pvmmake uses  this program (for packing  purposes) to count the
number of lines  in a file that is to  be transferred.  If this
error occurs, pvmmake will so indicate and exit.  In this case,
the user should either put a copy of the wc program in the same
directory  as the pvmmake  binary or  create a symlink  in this
directory to the actual location of the wc program.





                               32














Chapter 4



Running the PADE: A Tutorial



This chapter is  devoted to guiding the user through an example
in which the PADE is used to compile the manager/worker example
PVM  program that  is provided  with  the PADE  package.   This
chapter  assumes that the  user has  successfully installed the
PADE  and that  the user  can start  a viable  virtual machine.
Instructions on  how to install  the PADE package  are given in
Chapter 2.  The user is encouraged to work through this example
using the online  PADE manual by altering the files provided in
the example  subdirectory appropriately so  that they will work
on the user's virtual machine.
   The files  located in  the examples  subdirectory associated
with the manager/worker example are the following.

  o  manager.c --  A slightly modified version  of the master.c
     program provided with the PVM software.

  o  worker.c --  A  slightly modified  version of  the slave.c
     program provided with the PVM software.

  o  makefile.mw   -- A  generic makefile  that can be  used to
     compile  the  manager.c and  worker.c  source  files.    A
     modified copy  of this  makefile will  be needed  for each
     node of the user's virtual machine.

  o  pade_setenv  -- A script that  can be executed  to set some
     of the environment variables  and directory paths that are
     needed in order  for the PADE  to run.   This file assumes
     the user is running either the csh or tcsh UN*X shell.



                               33







  o  pade_export --  A script similar to  pade_setenv except that
     it assumes the user is running either the sh, ksh, or bash
     UN*X shell.

  o  mw  -- An  example PADE  setup  file used  to  compile the
     source files.

  o  mw.pvmmake -- The pvmmake config file corresponding to the
     mw setup file.

  o  mw_make_clean -- An example PADE  setup file used to remove
     the executable  and  object files  created on  all virtual
     machine  nodes during  compilation  of  the manager/worker
     example program.

  o  mw_make_clean.pvmmake --  The  pvmmake  config  file corre-
     sponding to the mw_make_clean setup file.

  o  mw_run  -- An example PADE  setup file used  to execute the
     compile manager/worker program using pvmmake.

  o  mw_run.pvmmake -- The pvmmake command file corresponding to
     the mw_run setup file.

   The manager.c and worker.c source files need not be modified
by  the user.   The  user will need  to make  several copies of
makefile.mw,  one for  each node  on  the virtual  machine, and
modify each  appropriately.  The user  will also need to modify
either  the pade_setenv  or pade_export files prior  to invoking
the PADE.  If the user is  not running either sh  csh, tcsh, or
bash,  then a file similar  to one of these  but containing the
correct  commands will  be needed.   The  PADE setup  files and
corresponding pvmmake  files are provided  only as examples and
will not be needed by the user.
   The tutorial comprising the  rest of this chapter contains a
step-by-step description of how the PADE is used to compile the
manager/worker PVM  program on an example virtual  machine.  It
was  wriiten under the  assummption that the  user would follow
each step (performed  as appropriate for the user's own virtual
machine) while referring to either the paper or the online copy
of the  PADE manual.   Not all of the features  of the PADE are
exhibited in this tutorial, however, and the user is encouraged
to read the more the PADE in the PADE User's Reference given in
Chapter 5.


                               34







4.1 Starting the PADE

Before  starting the  PADE  to follow  this  example,  the user
must make some  choices and also perform some setup operations.
First, the  user must decide which host  of the virtual machine
will be  the development host.   Next, the  user must decide on
the  directory in  which the  source files  will be  kept.   It
is  suggested, for  this example,  that the  examples directory
under  the PADE top  directory be used.   Finally,  the various
environment variables and directory paths must be set.
   The choice of development host is essentially one that makes
development  of programs most  convenient for  the user.   Note
that  the development host  need not  even be the  computer the
developer  actually sits in  front of.    If it is  possible to
use  the xhost  program to  display the  output of  an X-Window
application,  run  on  the development  host,  (e.g.  the PADE)
on  another  machine,  then that  machine  can be  used.    The
development host however, must be a node of the virtual machine
because this host is  defined to be the one on which the source
code for all hosts  resides and it will be the machine on which
pvmmake looks for the source code.
   The most  important operation  to be  performed by  the user
before  the  PADE  is started  is  the  setting  of environment
variables  and directory paths.   A  file is  provided with the
PADE distribution  in the examples directory  to help with this
task.  An example of this file given here

#
# PADE`SETENV -- This file is used to set various
# environment variables and directory paths needed by
# the PADE program.  The syntax of the commands in
# this script assume that the user is running either
# the csh or tcsh UN*X shells.  If the user is running
# either the sh, ksh, or bash UN*X shells, he or she
# should use the PADE`EXPORT script.
#
# NOTE: Some of the environment variables and directory
#       paths set in this script may be set elsewhere,
#       (e.g., in the user's .cshrc file).  If this is
#       case, they need not be set here -- even if
#       they are labeled REQUIRED.
#
# Set the PADE`HOME environment variable -- REQUIRED,
# the PADE WILL NOT START without it!


                               35







#
setenv PADE`HOME <put path-to-nist`pade/nist`pade/pade here>
#
# Set the EDITOR environment variable -- OPTIONAL, however,
# the first time the user tries to edit a file, the PADE
# will query the user for the name of a valid editor (full
# path name allowed) if this variable is not set.
#
setenv EDITOR <replace this with your favorite editor>
#
# Set the PVM`ROOT environment variable -- REQUIRED for
# normal PVM execution.  The PADE will start but the user
# will not be able to start PVM (version 3.3 or higher) and
# the PADE will not be able to perform its normal operations.
#
setenv PVM`ROOT <replace with the PVM`ROOT directory>
#
# Set the PVM`ARCH environment variable -- REQUIRED for
# normal PVM execution. The variable is neeeded for the
# same reasons as given for PVM`ROOT.
#
setenv PVM`ARCH <replace with your PVM`ARCH>
#
# Set the XPVM`ROOT environment variable -- OPTIONAL, this
# variable is only needed if the user intends to invoke
# XPVM.
#
setenv XPVM`ROOT <replace with the XPVM`ROOT directory>
#
# Set the TCL`LIBRARY environment variable -- REQUIRED, the
# PADE main window will appear but without any functionality.
#
setenv TCL`LIBRARY <replace with the TCL`LIBRARY directory>
#
# Set the TK`LIBRARY environment variable -- REQUIRED, the
# PADE main window will appear, but without any functionality
#
setenv TK`LIBRARY <replace with the TK`LIBRARY directory>
#
# Add the PVM executable directory to the PATH, if necessary.
#
set PATH=($PATH $PVM`ROOT/bin/$PVM`ARCH)
#
# Add the XPVM executable directory to the PATH, if necessary.


                               36







#
set PATH=($PATH $XPVM`ROOT/src/$PVM`ARCH)
#
# Add the PADE`HOME directory to the PATH, if necessary.
#
set PATH=($PATH /new/mark/nist`pade/pade)
#
# Some people may want to add the PATH to pvmd3 and pvm.
#
set PATH=($PATH $PVM`ROOT/lib/$PVM`ARCH)
#
# End of PADE setup file
#

The  user should now  edit this file  (which is  located in the
examples directory  under the name  pade_setenv).   Once this is
done, the  commands in this  file should be executed.   This is
done using the command

source pade`setenv

Equivalently,  the pade_setenv file can  be made  an executable
script and invoked by typing its name.
   With these variables  set, the user can  now invoke the PADE
by typing its name  at the command prompt.  The PADE will first
read  environment variables  and then search  the path  for the
standalone programs that  it can potentially execute.  The user
should  see the following  message in  the window in  which the
PADE was invoked

Welcome to PADE (1.0.0)

Checking environment variables

Checking commands

The  PADE  will then  proceed  with a  list  of  the standalone
program that it was unable to find by searching the directories
in the user's PATH.  After this, the PADE main window (which is
pictured in Fig. (5.1)) should appear.






                               37







4.2 Starting the Virtual Machine

The first  action the user should take  after invoking the PADE
is to start  the PVM console.  The  console may be started with
a  hostfile if the  virtual machine  is not already  running or
without  one if  the VM  has not  been  started.   The  user is
strongly encouraged to keep the xterm window containing the PVM
console open as long  as the PADE is running.  One advantage of
this  is that,  if the  user executes the  parallel application
under  development and  the program hangs,  then the  PADE will
hang.   The only  way to remedy  this in many  situations is to
halt the  VM. This can be  done from the  PVM console simply by
typing halt at the prompt.
   To start the PVM console from within the PADE choose the PVM
console  menu-entry from the  PVM menu in  the main window.   A
PADE Question  dialog box will  appear (if no  PVM hostfile has
been previously chosen) asking whether the user wishes to start
PVM with  or without a hostfile.   The  user should then choose
appropriately  whereupon an  xterm window should  appear unless
there is  trouble starting PVM. If there  is, the user may want
to run the pvmtidy utility.  Choose the pvmtidy menu-entry from
the PVM menu in the  PADE main window.  The PADE will launch an
xterm window  in which  pvmtidy is run.   After  this, the user
should try  to start the PVM  console again.   If this is still
not successful,  there may be something  more serious wrong the
the user's virtual machine.   Consult the PVM man pages in this
case (some  of which can be accessed  from the PADE Help menu).
Hereafter,  it will be  assumed that the  user's VM  is in good
working order.


4.3 Entering Setup Information

4.3.1 Entering host names

The  next  step  in using  the  PADE  to  compile  and run  the
manager/worker  example program  is to enter  the file-transfer
and command information into the PADE Setup window.  Choose the
Setup button in the PADE main window.  This will cause the PADE
Setup Window to appear.  This window is shown in Fig. (5.7).
   The first task that must  be performed is to enter the names
of the hosts of  the user's virtual machine into the PADE Setup
Window.  It  is essential that these names match those known to
PVM. The user  can determine these names by entering the "conf"


                               38







command at the PVM console prompt.  An example of the result is
as follows.

pvm> conf
4 hosts, 1 data format
       HOST            DTID     ARCH   SPEED
mithrandir.nist.org   40000     RS6K    1000
galadriel.nist.org    80000     SUN4    1000
shadowfax.nist.org    c0000     SUN4    1000
elrond.nist.org      100000    SGIMP    1000
pvm>

Now  the user should  carefully copy  the names found  this way
into the Setup window.   To do this, select the Add Host button
in this window.   The PADE Add Host  Window will appear.  Enter
the first host name exactly as it appears in the list exhibited
in the PVM console window.  It is possible to enter the command
for this host at this time.  For the purposes of this tutorial,
however,  entering host  commands will  be deferred to  a later
step.   Now the user should choose the  Save button in the PADE
Add Host Window.   The window will exit  and the host name just
typed in that window  will now appear as the first entry in the
PADE Setup Window.  This procedure should be repeated until all
hosts listed  in the PVM console window  are also listed in the
Setup Window.

4.3.2 Entering host commands

Now that all the  hosts have been entered, the user can proceed
to  enter  the host  commands.    The  commands  to  be entered
for  a  particular  host will  be  those  necessary  to compile
the  manager.c and  worker.c programs.    In this  example, the
general  procedure  for compiling  these  programs  will  be to
change to  the remote-host directory in  which the source files
are  located and  to issue  the "make" command.    The makefile
appropriate to the  particular host will have already been sent
as part  of the file-transfer phase of  the process of building
the  parallel application.    On  the example  virtual machine,
described in  Chapter 1, Section 1.3,  the commands required to
build manager.c and  worker.c on the host shadowfax.nist.org (a
SUN4) would be as follows.

cd ~edwards/pvm3/bin/SUN4; make -f makefile.shadowfax



                               39







The commands for  the other three hosts will be essentially the
same except that  the path name to the PVM executable directory
will differ as well as the name of the makefile.
   The user should now  enter commands similar to the above for
each host appropriate to  his or her virtual machine.  To enter
the  commands to  be executed  on a  particular host,  the user
should first  highlight an entry in the  Host list in the Setup
Window by clicking on  it with the left mouse button.  The user
then selects the Modify  Entry button at the top of the window.
This will cause  the Add Host window to appear.   The host name
text-entry box  will already have  the host name entered.   Now
the user should enter the appropriate change-directory and make
commands in the Host  commands text-entry box.  Then choose the
Save  button in  the Add  Host Window.   Repeat  this procedure
for  all other hosts  on the  virtual machine.   Note  that the
development host is  treated no differently than any other host
even  though the  files that  will  be transferred  only entail
copying them from one place on the disk to another.

4.3.3 Entering files using the Setup Files Window

Now  the  names of  the  files that  must  be  transferred from
development host to remote host must be entered for each remote
host.    This subsection  will describe how  this will  be done
using  the PADE  Setup Files Window.    In this  example, three
files will  be transferred to  each host.   They are manager.c,
worker.c,  and makefile.*,  where  the makefile  name extension
indicates for which host the makefile is appropriate.
   To enter the files to be transferred to a given remote host,
the user selects this host from the Host list in the PADE Setup
Window and  then selects the  Setup Files button at  the top of
the  window.   This will cause  the PADE Setup  Files Window to
appear.  This window  is pictured in Fig. (5.8).  To create the
list of  files to be transferred to  this remote host, the user
selects the  Add Entry button at  the top of the  window.  This
causes the PADE  Add File Window to appear.   Now the user must
enter  the full path  name of the  location of the  file on the
development  host.   The easiest  way to  do this is  to choose
the  File Browser button.    Change the directory  displayed by
the file  browser to the directory  where manager.c is located,
highlight this  file in the file browser  list and click the OK
button.   The file browser will exit and  the full path name of
manager.c will  be entered in the Local  file text-entry box in
the Add  File Window.   Now the  user must enter  the full path


                               40







name of  the intended location of manager.c  on the remote host
associated  with this  Setup Files Window  (the remote  host is
listed at  the top of  the Setup Files  Window currently open).
The  remote-host location  for the manager/worker  example must
be  the PVM  binary directory.   This  directory is  always the
following directory.

$PVM`ROOT/bin/$PVM`ARCH

Once  the text-entry  box  has been  filled in,  the  user then
chooses the Save button.  The Add File Window will exit and the
file list will contain an entry containing the information just
entered in the form

<local file> --> <remote file> .

   To create two more entries in this list, the user highlights
the existing  entry and selects the Copy  Entry button twice in
succession.   These entries are modified by highlighting one of
them  and choosing the  Modify Entry button.    The PADE Modify
Entry  Window will  appear.   This window  is identical  to the
Add  File Window  except that  text is  already entered  in the
text-entry  boxes.   The  user should  modify these  entries as
appropriate  to transfer  the worker.c  file and  the makefile.
When  the  file list  is  complete the  user  chooses  the Save
button.  The Setup Files Window will exit.

4.3.4 Entering files using the Tree View Window

The  user now enters  similar informaton  for all of  the other
hosts on  the virtual machine.  A  convenient way of doing this
is to  use the Tree  View Window.   This window  is pictured in
Fig. (5.9).   When the user chooses the Tree View button in the
Setup  Window the Tree  View window will  appear.   If the user
has  been following  this example,  several large  circles will
be displayed  on a large  canvas -- each  representing one host
on  the virtual machine.   One  of these hosts  will have three
rectangles  attached to it  -- each  rectangle representing one
file that is to be sent to the host associated with the circle.
The user can  very quickly add the manager.c and worker.c files
to  the other hosts  as follows.    The user first  chooses the
Duplicate button  at the top  of the window and  then clicks on
the manager.c rectangle.   A copy of this rectangle will appear
attached to the same circle.


                               41







   Repeating this  operation several times results  in n copies
of the manager.c rectangle.   Where n is the number of hosts in
the  user's virtual  machine.   This set  of operations  can be
repeated  with the worker.c  and makefile  rectangles.   At the
end there  should n copies  of the three basic  programs -- all
attached  to a  single circle.   The  user can  then distribute
these  files to the  other circles  (hosts) by using  the mouse
to drag  the various rectangles  to their proper places.   Note
that, in order to attach a rectangle to a new circle, the mouse
arrow  point should lie  within the new  circle (while dragging
the rectangle) when the  mouse button is released.  Once all of
the files  are distributed, the  user must then  modify each of
them to  ensure that all  host-specific information is correct.
To modify  a file, choose  the Modify button at  the top of the
window and  then click on the appropriate  rectangle.  The PADE
Modify File  Window will appear  as was described above.   When
all entries have been  modified, the user then chooses the Save
button and the Tree View Window will exit.
   Note that  any files specified using  either the Setup Files
Window or the Tree View  Window need not exist on the disk.  To
create these files, the user can invoke the preferred editor by
using the  Edit File button found in  the Setup Files Window or
in the Tree  View Window by duplicating an existing file entry,
modifying  the name,  and  double-clicking this  new rectangle.
Note  that the  user must edit  each host-specific  makefile by
changing such  things as the include and  library paths as well
as any other host-specific information that may be required.

4.3.5 Saving the setup information

Once  all of  the  hosts, host  commands,  and files  have been
entered  to the  user's  satisfaction, the  information  can be
saved to  a file.  To  do this, the user  chooses the Save File
button at the bottom of the PADE Setup Window.  This causes the
file browser  window to appear.   The user  then either chooses
a file  that is already present  on the disk  or types the name
of  a new  file in  the File name  box near  the bottom  of the
file browser  window.  The user can  also change to a different
directory if  necessary.   It is recommended that  all files be
saved in  the same directory as the source  files, however.  If
the  user chooses  an already  existing  file, a  PADE Question
dialog box  will open asking for  confirmation to overwrite the
file.
   Note that,  at this point,  the PADE will  create two files.


                               42







The  first  file saves  the  setup information  under  the name
specified  by the user.   The  second file is  a pvmmake config
file  that contains  commands telling  pvmmake to  transfer the
files  and issue the  host commands  as specified in  the setup
information just  entered by the user.   The  name of this file
is  the same as  that specified by  the user to  save the setup
information with an added pvmmake extension.  Thus, if the user
saves  the setup  info to  the  file setup_info,  the  PADE will
create  (or overwrite) this  file and  will also create  a file
named setup_info.pvmmake.
   Once the user has saved the setup information to a file, the
user can  either modify the  information or choose  to exit the
Setup Window.   The Setup Window is exited by choosing the Done
button at the bottom of the window.  When the user is satisfied
with the  setup info as entered, the next  step is to build the
application.


4.4 Building the Parallel Application

4.4.1 Viewing the pvmmake config file

To  compile  the  manager/worker  example,  the  user must  run
pvmmake.  Before  doing so, however, it is strongly recommended
that the  user view the  pvmmake config file to  make sure that
the host commands and file transferred are correct.  An example
pvmmake  config file  appropriate  to the  present  example and
relevant to the virtual machine described in Chapter 1 is given
in Chapter 3, Section 3.2.
   To  view the  current  pvmmake  config file  (which  will be
based on  the setup info just entered)  choose the List pvmmake
config  file from  the Run  menu in the  PADE main  window.   A
display window  will open which contains the  config file.  The
user should  look at this file carefully  to make sure that the
commands are correct.   Choose the Done button at the bottom of
the window to close it.


4.4.2 Running pvmmake

To run pvmmake, choose  the Run pvmmake entry from the Run menu
in the PADE  main window.  This will  cause the mouse prompt to
change  from an arrow  to a watch  indicating that  the PADE is
busy.   The PADE  main window may  resize and some  of the text


                               43







on the  canvas may momentarily  disappear.  This  is normal, if
somewhat inelegant.   Soon, a display  window will appear which
contains the output of the pvmmake run.
   A representative  sample of this output,  run on the example
virtual  machine  is  shown  below.     Note that  the  example
virtual  machine  has four  nodes  but the  output  shown below
transfers files and issues  commands on only three nodes.  This
illustrates that  it is not  necessary to use all  nodes of the
virtual machine.

Reading in configuration file: mw.pvmmake
Your virtual machine configuration is:
262144 mithrandir.nist.org RS6K 1000
524288 galadriel.nist.org SUN4 1000
786432 shadowfax.nist.org SUN4 1000
1048576 elrond.nist.org SGIMP 1000

Spawning one process on each machine:
spawned 1 process on mithrandir.nist.org with tid 262148
spawned 1 process on galadriel.nist.org with tid 524289
spawned 1 process on shadowfax.nist.org with tid 786433
spawned 1 process on elrond.nist.org with tid 1048578


FILE BROADCAST:
The file to be broadcast is manager.c
...Broadcast to 3 machines: mithrandir.nist.org \
                            galadriel.nist.org \
                            shadowfax.nist.org

broadcasting to tid 262148 (mithrandir.nist.org)
...file to be opened on mithrandir.nist.org is manager.c
broadcasting to tid 524289 (galadriel.nist.org)
...file to be opened on galadriel.nist.org is manager.c
broadcasting to tid 786433 (shadowfax.nist.org)
...file to be opened on shadowfax.nist.org is manager.c


FILE BROADCAST:
The file to be broadcast is worker.c
...Broadcast to 3 machines: mithrandir.nist.org \
                            galadriel.nist.org \
                            shadowfax.nist.org



                               44







broadcasting to tid 262148 (mithrandir.nist.org)
...file to be opened on mithrandir.nist.org is worker.c
broadcasting to tid 524289 (galadriel.nist.org)
...file to be opened on galadriel.nist.org is worker.c
broadcasting to tid 786433 (shadowfax.nist.org)
...file to be opened on shadowfax.nist.org is worker.c


FILE BROADCAST:
The file to be broadcast is makefile.mithrandir
...Broadcast to 1 machines: mithrandir.nist.org

broadcasting to tid 262148 (mithrandir.nist.org)
...file to be opened on mithrandir.nist.org is
makefile.mithrandir


FILE BROADCAST:
The file to be broadcast is makefile.galadriel
...Broadcast to 1 machines: galadriel.nist.org

broadcasting to tid 524289 (galadriel.nist.org)
...file to be opened on galadriel.nist.org is
makefile.galadriel


FILE BROADCAST:
The file to be broadcast is makefile.shadowfax
...Broadcast to 1 machines: shadowfax.nist.org

broadcasting to tid 786433 (shadowfax.nist.org)
...file to be opened on shadowfax.nist.org is
makefile.shadowfax



COMMAND RESULTS:
@ mithrandir.nist.org cd ~edwards/pvm3/bin/RS6K; \
                  make -f makefile.mithrandir +errors

 cc -c -I/mithrandir/nist/edwards/pvm3/include manager.c
 cc -c -I/mithrandir/nist/edwards/pvm3/include worker.c
 cc manager.o -L/mithrandir/nist/edwards/pvm3/lib/RS6K \
        -lpvm3 -lgpvm3 -o manager


                               45







 cc worker.o -L/mithrandir/nist/edwards/pvm3/lib/RS6K \
        -lpvm3 -lgpvm3 -o worker


COMMAND RESULTS:
@ galadriel.nist.org cd ~edwards/pvm3/bin/SUN4; \
                   make -f makefile.galadriel +errors

 cc -c -I/home/galadriel/edwards/pvm3/include manager.c
 cc -c -I/home/galadriel/edwards/pvm3/include worker.c
 cc manager.o -L/home/galadriel/edwards/pvm3/lib/SUN4
              -lpvm3 -lgpvm3 -o manager

 ld: manager.o: `main: multiply defined
 ld: manager.o: internal error: symbol not found
 *** Error code 4
 make: Fatal error: Command failed for target `all'


COMMAND RESULTS:
@ shadowfax.nist.org cd ~edwards/pvm3/bin/SUN4; \
                      make -f makefile.shadowfax +errors

 gcc -c -I/home/galadriel/edwards/pvm3/include manager.c
 gcc -c -I/home/galadriel/edwards/pvm3/include worker.c
 gcc manager.o -L/home/galadriel/edwards/pvm3/lib/SUN4
               -lpvm3 -lgpvm3 -o manager
 gcc worker.o  -L/home/galadriel/edwards/pvm3/lib/SUN4
               -lpvm3 -lgpvm3 -o worker

 ********** ALL PROCESSES HAVE EXITED **********.

Note  that the compile  failed on  the galadriel.nist.org node.
The user  is provided with whatever  information that is output
when the commands are executed on each host.


4.5 Running the Parallel Application

Once the manager/worker  program has compiled successfully, the
next order-of-business  is to run it.   This can be done within
the PADE in two different methods.  These are as follows.




                               46







  o  xterm -- The PADE can be used to launch the newly-compiled
     parallel  application in  an xterm  window.    This method
     useful  when the  application  requires  interactive input
     at  the  terminal   and  when  the   user  does  not  wish
     to  save  anything  the  application  writes  to  standard
     output.   Furthermore, unless the  user's xterm window has
     scrollbars, any output written  in the window that scrolls
     out of view

  o  pvmmake -- The user can  create a pvmmake config file that
     issues the  run command.   This  method is  more useful in
     situations  that are  complementary to  the  xterm method.
     If the  output of the  application that is  written to the
     screen  is important  to the  user  and if  no interactive
     input  is  required,  then  running  with  pvmmake is  the
     preferred method.  Interactive program can actually be run
     this way if the input to the program is redirected.

Both  methods  of running  the  manager/worker  application are
described below.

4.5.1 Running the application in an xterm window

To launch the  compiled parallel application in an xterm window
requires two steps.   First, the executable binary must be set,
and second, it must be launched.
   The  binary   is  set  by  selecting   the  PVM  application
menu-entry  from  the   RUN  menu  in  the  PADE  main  window.
Selection  of this  entry causes  the  file browser  to appear.
The  user then selects  the appropriate  PVM binary file  to be
launched.    Note  that the  parallel application  can  only be
launched from the development host using this method.
   Once  the appropriate  binary  has been  set,  the  user can
launch  this program in  an xterm  window by selecting  the Run
menu-entry  within  the  Run  menu  in  the  PADE main  window.
Selection  of  this  button  opens  an  xterm  window  and  the
application  is launched.    The  user can  then repond  to any
requests by the  parallel program for terminal input.  Anything
written to  standard output by the program  will also appear in
this window.   When the program run ends, the xterm window will
stay on  the screen for one hour  unless manually closed by the
user.
   To run the manager/worker  example program, the user chooses
the  manager  executable which  should  be located  in  the PVM


                               47







binary  directory when  the file  browser window  has appeared.
Then choose the Run  menu-entry.  The xterm window will appear.
A sample session is shown below.

How many worker programs (1-32)?
10
I got 700.000000 from 4
I got 100.000000 from 1
I got 500.000000 from 3
I got 300.000000 from 2
I got 1700.000000 from 9
I got 900.000000 from 0
I got 1500.000000 from 8
I got 900.000000 from 5
I got 1100.000000 from 6
I got 1300.000000 from 7

The response to the question must be supplied by the user.

4.5.2 Running the application using pvmmake

To  run the compiled  parallel application using  pvmmake a new
pvmmake  config file must  be created.   This  config file will
consist of  only one host -- the development  host.  There will
be  no files associated  with this  host and only  one command.
This command will be to launch the parallel program.
   To  run the  manager/worker example  using this  method, the
user  again chooses the  Setup button  in the PADE  main window
to  call the  Setup window.    Delete  any information  that is
currently  in this  window.    Now select  the Add  Host button
and  enter the name  of the development  host in  the Host name
text-entry box.  In the Host command box enter the following.

cd $PVM`ROOT/bin/$PVM`ARCH; manager < manager.input

Now select  the Save button in the Add  Host Window; the window
will exit.   Next select the Save File  button and save the new
setup information to a file.  Finally select the Done button to
exit the Setup Window.
   The  last task  that must  be performed  by  the user  is to
create  a  file  called  manager.input  to  be  located in  the
directory specified  in the command given  to pvmmake and shown
above.    This can  be  done outside  of the  PADE environment.
This file  should contain only a number.   The number of worker


                               48







programs the user desires to be spawned by the manager program.
   To  run the  parallel  application using  pvmmake,  the user
chooses the Run pvmmake  menu-entry in the Run menu in the PADE
main window.   It is recommended that the user view the pvmmake
config  file  before running  pvmmake.    Once  the application
has been  launched using pvmmake, a  display window will appear
containing output similar to the following.

Reading in configuration file:
/mithrandir/nist/edwards/test`pade/ms`run`with`pvmmake.pvmmake

Your virtual machine configuration is:
262144 mithrandir.nist.org RS6K 1000
524288 galadriel.nist.org SUN4 1000
786432 shadowfax.nist.org SUN4 1000
1048576 elrond.nist.org SGIMP 1000

Spawning one process on each machine:
spawned 1 process on mithrandir.nist.org with tid 262154
spawned 1 process on galadriel.nist.org with tid 524294
spawned 1 process on shadowfax.nist.org with tid 786437
spawned 1 process on elrond.nist.org with tid 1048586

COMMAND RESULTS:
@ mithrandir.nist.org manager < manager.input +errors

 How many worker programs (1-32)?
 I got 6100.000000 from 31
 I got 2900.000000 from 15
 I got 2700.000000 from 14
 I got 2500.000000 from 13
 I got 2300.000000 from 12
 I got 2100.000000 from 11
 I got 1900.000000 from 10
 I got 1700.000000 from 9
 I got 5900.000000 from 30
 I got 5700.000000 from 29
 I got 5500.000000 from 28
 I got 5300.000000 from 27
 I got 5100.000000 from 26
 I got 4900.000000 from 25
 I got 300.000000 from 2
 I got 3100.000000 from 0
 I got 1100.000000 from 6


                               49







 I got 700.000000 from 4
 I got 900.000000 from 5
 I got 500.000000 from 3
 I got 100.000000 from 1
 I got 1500.000000 from 8
 I got 1300.000000 from 7
 I got 4700.000000 from 24
 I got 4500.000000 from 23
 I got 3900.000000 from 20
 I got 3700.000000 from 19
 I got 3500.000000 from 18
 I got 3300.000000 from 17
 I got 4100.000000 from 21
 I got 4300.000000 from 22
 I got 3100.000000 from 16

********** ALL PROCESSES HAVE EXITED **********.

The  user can  save  this output  and/or scroll  through  it at
leisure.

4.5.3 Other pvmmake config files

It  is useful, in  the development  process, to  create and use
other  pvmmake config  files for  other purposes.    An example
of  this is a  "make clean" config  file.   A sample  of such a
config file is  provided in the examples subdirectory under the
name mw_make_clean.pvmmake.   This config file contains commands
instructing  pvmmake to  issue  "make clean"  commands  on each
host.    Users who  inspect the  sample makefile  provided with
the  PADE distribution will  notice a "clean"  directive at the
bottom.
   To create  a "make clean"  example, choose  the Setup button
from the  PADE main window.   The Setup Window should reappear.
Note  that every  invocation of this  window subsequent  to the
first  will be filled  in with  the setup information  from the
most recent saved setup  file.  The PADE does not have a "clear
setup info"  feature as yet (but may in  future releases).  The
fastest way to clear all information is to invoke the Tree View
Window and delete  the files from each host one-by-one and then
select the  Save button in this window.   The Setup Window will
then have only a  list of hosts along with their commands.  The
user  then modifies each  of these  hosts and changes  the host
commands to the something similar to the following.


                               50







cd <replace with PVM executable directory>;
make -f <replace with host-specific makefile name here> clean

The  "clean" directive  in the  sample makefile  simply removes
the  manager.o, worker.o, manager,  and worker  files that were
created during the compilation.
   Many  other routine  functions  can  be automated  in  a way
similar to  the "make clean" example described  above.  In this
sense, the PADE can be used creatively for more tasks than just
parallel program development.




































                               51














Chapter 5



The PADE User's Reference



This  chapter contains a  description of every  button and menu
found  in the  PADE program.    It is  intended as  a reference
for those  users who don't  like to read manuals  and for those
who do.   Users  who prefer to  jump in and try  a program will
probably want  to start with Chapter 4 in  which can be found a
step-by-step tutorial  using the manager/worker example program
that  comes bundled with  the PADE  source code.   Each  time a
button or menu  is encountered which is unfamiliar to the user,
the user can look it up in this chapter.


5.1 Before the PADE is Invoked

The  NIST  PADE  will  not  run  unless  some  (at  least  one)
environment  variables have  been set.   Furthermore,  the PADE
relies  on several "helper"  programs (not  unlike NCSA Mosaic)
so  that its full  functionality can be  realized.   The helper
programs  referred to here  do not include  X-Windows, PVM, and
Tcl/Tk which are essential  for the PADE to run.  Rather, these
programs enrich  the parallel programming  environment that the
PADE provides but are  not needed for the PADE to execute.  The
required environment variables  and helper programs that can be
used by the PADE are described below.

5.1.1 Environment Variables

The  user can  use several  environment  variables in  order to
customize  the PADE  programming  environment.    The following
variables are read by the PADE.


                               52







  o  PADE_HOME -- The directory path to the place where the PADE
     Tcl/Tk code  resides.   This environment  variable must be
     set or the PADE will not run.

  o  PVM_ROOT  --  The path  to  the  top of  the  PVM directory
     structure.  This  environment variable is identical to the
     variable of the same name required by PVM.

  o  PVM_ARCH -- The  same as the PVM variable of the same name.
     Examples include RS6K, SUN4, and LINUX.

  o  XPVM_ROOT  -- The  path to  the top  of the  XPVM directory
     structure.  This  environment variable is identical to the
     XPVM variable of the same name.

  o  EDITOR --  The name  of the  user's favorite  text editor.
     Note that the full pathname  of the editor variable can be
     specified here, e.g., /dir-not-in-path/editor.

  o  HOME -- The  path to the  user's home directory.   This is
     the usual environment variable set by most shells.

  o  PATH -- The user's search path.

When  the PADE is  launched it  reads in the  above environment
variables.    If the  PADE_HOME  variable is  not set,  the PADE
prints  an error message  and exits.   It is  also important to
include the following entries in the PATH environment variable.

  o  $PVM_ROOT/bin/$PVM_ARCH  --   This  path   points   to  the
     directory where PVM looks for executables by default.

  o  $XPVM_ROOT/src/$PVM_ARCH  --   This  path  points   to  the
     directory where the xpvm executable is located.

5.1.2 Helper Programs

There are  two main helper  programs that can be  used with the
PADE. These are

  o  World-Wide-Web  browser --  there  are  two  browsers that
     are currently  supported by  the PADE  -- NCSA  Mosaic and
     Netscape.  The Help  menu in the main PADE window contains
     several entries which automatically invoke a WWW-browser.


                               53







  o  XPVM  --   This  program  enables  the   user  to  isolate
     bottlenecks and bugs in an application.

Later  releases of  the PADE will  provide automatic  access to
other  helper  programs such  as  Paragraph  and Xab.     It is
possible for the  user to manually configure the PADE to access
these programs in the current release.


5.2 The Main Window and Its Menus and Buttons

If  the environment  variables  have been  set,  when  the PADE
is  launched the  PADE Main  Window will appear.    This window
contains a  row of six buttons  at the top  along with a canvas
exhibiting  the NIST  and PADE  logos  together with  the words
Parallel  Applications Development  Environment at  the bottom.
This window is pictured in Fig. (5.1).  The titlebar on the top
border of the window has the words "PADE - Release x.xx".  This
is sometimes important  if more than one version of the program
is present (e.g., because of an upgrade).
   The six buttons across the  top of the window consist of the
Setup  button, the Run  menu button,  the PVM menu  button, the
Monitor menu button, the Help menu button, and the Exit button.
All buttons  except Setup and Exit  reveal pull-down menus when
clicked with the left mouse button.
   Each of  the six  buttons in  the PADE  main window  will be
discussed  in turn below.   The  Setup button  leads to another
entire set  of windows which  allow the user to  enter all file
and command information about the current parallel application.
These  windows  will be  described  in later  sections  of this
chapter.

5.2.1 The Setup Button

The  Setup button  is the  leftmost  button at  the top  of the
main PADE  window.  When  this button is  clicked with the left
mouse button,  the PADE Setup window appears.   In this window,
the user  enters all information  about the current application
relevant  to which  files must  be  transferred to  which hosts
and  what commands are  to be  executed on  these hosts.   This
information can be  entered directly in the Setup window or the
user can invoke the  Tree View window which can be invoked from
the  Setup window.    These windows will  be described  in much
detail later in this chapter.


                               54
































               Figure 5.1:  The PADE main window


5.2.2 The Run Menu

The Run  menu button is the second button  from the left at the
top of the main  PADE window.  When this button is clicked with
the  left mouse button,  the Run pulldown  menu appears.   This
menu  is pictured  in Fig.  (5.2).   The  entries in  this menu
allow the user  to perform two major operations:  (1) executing
pvmmake  and (2)  executing the parallel  application currently
under  development.   There are five  entries in  the Run menu.
These entries are

  o  pvmmmake config  file --  enables the  user to  select the
     pvmmake  configuration file  to  be used  when  pvmmake is
     launched.  When this  menu-entry is selected, a dialog box
     appears.  This dialog box  is divided into two parts.  The
     top part  consists of  a text-entry  box preceeded  by the


                               55
































            Figure 5.2:  The RUN main menu


words Enter pvmmake  config file:.   The user is requested
here to enter the fully-qualified path name of the pvmmake
config file  needed.   On  the bottom  of this  dialog box
are  four buttons.    These  buttons are  the  Clear, File
Browser, Done, and Cancel  buttons.  These buttons perform
the following functions


 --  Clear -- Erase any text in the text-entry box.

 --  File  Browser  --  Invoke  a  file  browser/selection
     window allowing the user to select the needed pvmmake
     config file using the mouse.

 --  Done -- With this button, the user indicates that the
     required file has  been entered.   Note  that, if the


                          56







        file name  entered does  not exist,  this information
        will appear stating this.   To  re-enter a file name,
        the user must  reselect the pvmmake  config file menu
        entry in the Run menu.

    --  Cancel -- Selecting this button causes the dialog box
        to disappear with no pvmmake  config file having been
        selected.


   Note that  if there  is a  file currently selected  as the
   pvmmake  config file,  its  name  appears  in  the pvmmake
   config file menu-entry.

o  List pvmmake  config file -- Selection  of this menu-entry
   causes a  window to  appear in  which the  current pvmmake
   config file  is displayed.    The user can  scroll through
   this file to ensure that the correct pvmmake commands will
   be executed.  There  are two buttons at the bottom of this
   display window.  They are


    --  Save --  Selection  of this  button  causes  the file
        browser window to  appear, the user can  enter a file
        name in which the contents  of the display window are
        saved.

    --  Done --  Selection of this  button cause  the display
        window to disappear.


   Experience shows that this  display window is quite useful
   in  guarding  against  incorrect  pvmmake  commands  begin
   executed.    Users are  encouraged  to always  examine the
   pvmmake config file before launching pvmmake.

o  Run pvmmake  --  This menu  entry launches  pvmmake.   Any
   output  that pvmmake  would  normally write  to  stdout is
   collected by the PADE  and displayed in a window identical
   to that used to display the pvmmake config file.

o  PVM application  -- This  menu entry  enables the  user to
   indicate  to  the PADE  the  command  used  to launch  the
   parallel  application currently  under development.    Its


                             57







   selection causes the file browser window to be invoked.

o  Run --  This  menu entry  enables the  user to  launch the
   application  being  developed.     The application  to  be
   launched must have been  previously selected using the PVM
   application menu-entry.   Selection of  this entry opens a
   new xterm window in  which the previously selected command
   is executed.   When  the application has  ended, the xterm
   window remains on the screen  for an hour unless closed by
   the user  and then  exits.   Launching the  application in
   an xterm window enables  the user to interactively provide
   input to  the  application.   If  such interaction  can be
   avoided, there is another  method by which the application
   can be launched which may  be more desirable.  This method
   is described in Chapter 4.



























               Figure 5.3:  The PVM main menu



                             58







5.2.3 The PVM Menu

The PVM  menu (pictured in  Fig. 5.3) consists  of ten entries.
The  major  operations available  to  the user  from  this menu
include  configuring and executing  PVM and  XPVM and executing
the  NIST  CAML utilities  pvminituser,  pvmstat,  and pvmtidy.
Each entry is described in turn below.

  o  PVM console -- This  menu-entry enables the user to launch
     the PVM console program in  an xterm window.  The user can
     select a PVM hostfile  (using the Pick Hostfile menu-entry
     described below).    The PVM  hostfile contains a  list of
     the hosts  comprising the user's  virtual machine.   If no
     hostfile is currently selected,  then selection of the PVM
     console menu-entry  causes a dialog  box to appear.   This
     dialog box  consists of  a message  box starting  with the
     words No  hostfile has been  set on the  top and  a row of
     four buttons on the bottom.  These buttons are


      --  Edit Hostfile  --  This button  enables  the  user to
          edit a  hostfile.    The  user  can  then  select the
          hostfile with  the  Set  Hostfile  and  Start button.
          This is  convenient if  the user  wishes to  create a
          new PVM hostfile  or change an  already existing one.
          Selecting the Edit  Hostfile button  invokes the PADE
          Edit File window  which consists of  a text-entry box
          preceeded by the  words Enter file name:   and having
          three buttons across  the bottom.   These buttons are
          as follows.


            * File  Browser -- Invokes  the File Browser window
              for hostfile selection.

            * Edit  -- Invokes an instance of the user's editor
              launched  in  an  xterm window.     If  an editor
              has  already been  selected, this  button will be
              labeled  with  the name  of the  selected editor.
              If  no  editor has  previously been  selected, an
              extra  text-entry box  is appended to  the top of
              the  PADE Edit File window in  which the user can
              specify the editor.



                               59







          * Cancel  -- Selection  of this button  cancels the
            user's request to start the PVM console.


    --  Set Hostfile  and Start --  Invokes the  File Browser
        window so that the user  can select the PVM hostfile.
        Once selected,  the PADE  immediately starts  the PVM
        console with  the  selected hostfile.    If  the file
        selected with the browser is invalid, the PVM console
        will start PVM only on the development host.

    --  Start Without  Hostfile --  This button  launches the
        PVM console without a hostfile.   The virtual machine
        will consist  only of  the  development host  in this
        case.

    --  Cancel -- Cancels the user's request to start the PVM
        console.


o  PVM  daemon --  Runs  the  PVM daemon.     If  no hostfile
   has been  previously  selected, then  the same  dialog box
   appears as described above when the PVM console button was
   selected.

o  xpvm -- This  button launches the XPVM  application.  Note
   carefully that,  if XPVM is  launched, it will  start up a
   virtual machine unless one already  exists.  The PADE will
   look for  a .xpvm_hosts  file in the  user's home directory
   (indicated by the HOME environment  variable).  If it does
   not find this file, a PADE Question box will appear.  This
   dialog box consists of a message box at the top containing
   a message  beginning with  the words  No ~/.xpvm_hosts file
   exists.   The  bottom of  the box contains  three buttons.
   These buttons are


    --  Edit ~/.xpvm_hosts -- Selecting this button enables the
        user edit or create  a xpvm_hosts  similar to the Edit
        Hostfile button in the dialog box associated with the
        PVM console menu-entry.

    --  Start Without  ~/.xpvm_hosts  -- Selecting  this button
        launches XPVM without an .xpvm_hosts file.


                             60







    --  Cancel --  Selecting this  button cancels  the user's
        request to launch XPVM.


   The  user should  use caution  when  starting XPVM  with a
   .xpvm_hosts file so  as not to collide with the regular PVM
   hostfile.

o  pvminituser -- Selecting  this menu-entry invokes the NIST
   CAML  utility  pvminituser.    This  program  will set  up
   the correct  PVM  directory structure  in the  user's home
   directory.   This utility is especially  useful if PVM has
   been installed  by the  system administrator in  a central
   location on any  of the hosts on the  virtual machine.  If
   the PADE  does not find  this program in  the user's PATH,
   the menu-entry is disabled.

o  pvmstat --  This menu-entry invokes the  NIST CAML utility
   pvmstat.   This program returns the  status of the virtual
   machine.   If the PADE  does not find this  program in the
   user's PATH, the menu-entry is disabled.

o  pvmtidy --  This menu-entry invokes the  NIST CAML utility
   pvmtidy.   This  program remove  all spurious  pvmd.* file
   from the nodes  of the user's virtual  machine in case PVM
   does not  shut  down gracefully.    If  the PADE  does not
   find this  program in the  user's PATH,  the menu-entry is
   disabled.

o  Pick  Hostfile  -- This  menu-entry  enables  the  user to
   select the  PVM hostfile  that will  be used when  the PVM
   daemon or  console is started.   Selection  of this button
   causes the  PADE file  browser window to  appear.   If the
   user hits  the Cancel button  in the browser,  the browser
   exits but also the PADE  assumes that no hostfile has been
   selected.

o  Edit Hostfile --  This menu-entry is used  to edit the PVM
   hostfile selected.  If  no hostfile has been selected, the
   PADE Edit File window appears.   In this release, the Edit
   File window appears even if a hostfile has been selected.

o  List Hostfile  -- This menu-entry  is used  to display the
   selected PVM  hostfile in  a List  Output window.    If no


                             61







   hostfile has  been previously selected,  the menu-entry is
   disabled.

o  Write Host List  to Hostfile --  This menu-entry gives the
   user the  option  of performing  the setup  operations for
   the application currently  under development in advance of
   starting the  virtual machine.   At  the end  of the setup
   procedure (after  the  Setup window  is closed),  the user
   can  create a  PVM  hostfile that  is  appropriate  to the
   setup information.   If no setup  has been performed, this
   menu-entry is disabled.



























             Figure 5.4:  The MONITOR main menu







                             62







5.2.4 The Monitor Menu

The PADE Monitor menu enables the user to configure the PADE to
launch a  custom parallel applications  monitor program such as
Paragraph or Xab3 in an xterm window.  This menu is depicted in
Fig. 5.4.  The entries in this menu are as follows.

  o  xab3 --  Selection of this menu-entry  invokes an instance
     of the PVM application monitor xab3.

  o  User-defined monitor:  -- This menu-entry enables the user
     to specify a  custom program to be  launched from an xterm
     window.   Selection of  this entry invokes  the PADE Entry
     window.   This window consists of a  text-entry box at the
     top preceeded by  the words Enter monitor  command:  and a
     row of four buttons on the bottom.  These buttons are


      --  Clear -- Erase any text in the text-entry box.

      --  File Browser -- Invoke the file browser to select the
          custom program to be executed.

      --  Done -- Accept the entered command and exit.

      --  Cancel -- Ignore the entered command and exit.


     Note  that  if  either  the  Done  or Cancel  buttons  are
     selected  when there  is no  text  in the  text-entry box,
     the PADE  assumes  that no  user-defined program  has been
     specified and disables  the Run user-defind monitor button
     described next

  o  Run user-defined  monitor --  This menu-entry  enables the
     user to  execute the  previously selected  custom program.
     Selection of this  program invokes an  instance of a xterm
     window in which the custom program is launched.


5.2.5 The Help Menu

The PADE Help menu provides the user with two methods to obtain
help.   Help is available  through (1) local  man pages and (2)


                               63
































       Figure 5.5:  The MAN menu under the HELP main menu


the  World-Wide-Web.   The user can  find help on  a variety of
topics.  The main topics that the PADE Help menu focuses on are
PADE operations  and PVM. In  this section, the  entries of the
Help menu are discussed in detail.
   The PADE Help menu consists  of five entries.  These entries
are as follows.

  o  Man Pages -- This menu-entry provides the user with access
     to online man  pages covering subjects  related to PVM and
     to the  Guide to  Available Mathematical  Software (GAMS).
     Moving  the  mouse arrow  over  this  menu-entry  causes a
     cascaded menu  to appear;  selection of  an entry  in this
     cascaded  menu  causes  the  appropriate  man page  to  be
     displayed in a  List Output window.   The submenu consists
     of four entries described next.   The Help menu along with
     this cascaded submenu are pictured in Fig. (5.5).


                               64































 Figure 5.6:  The WWW menu under the HELP main menu


--  pvm_intro   --  A  man   page  containing   a  general
    introduction to the  PVM software  plus a description
    of all of environment variables read by PVM.

--  pvm (console) -- A man  page containing a description
    of the PVM console program.

--  pvmd3 (daemon) -- A man page containing a description
    of the PVM daemon program.

--  gams  --   A  man  page   describing  the   Guide  to
    Available Mathematical  Software  on-line cross-index
    of available  mathematical and  statistical software.
    This  man  page  will  probably  disappear  in  later
    releases because  the preferred  method  of accessing
    GAMS is through the WWW.



                         65







o  WWW --  This menu-entry  provides the  user with  links to
   help  via the  World-Wide-Web.    Moving  the  mouse arrow
   over this  menu-entry  causes a  cascaded menu  to appear;
   selection of an entry  in this submenu invokes an instance
   of the user-specified  WWW-browser whose default home-page
   has been  redirected  appropriately to  the submenu-entry.
   The number and type of entries in this submenu will change
   over time except for the first two.  They are


    --  PADE -- Provides a link to the NIST PADE home-page.

    --  PADE Manual --  Provides a  link to  the local online
        PADE manual


   The PADE Help menu along with the WWW cascaded submenu are
   shown in Fig. (5.6).

o  WWW browser  is:   -- The  menu-entry enables the  user to
   specify the  preferred World-Wide-Web browser.   There are
   two WWW browsers that are supported in this release of the
   PADE. They  are NCSA  Mosaic and  Netscape.   Selection of
   this entry causes  a PADE Entry  box to appear.   This box
   consists of a text-entry  box preceeded by the words Enter
   WWW browser command  on the top and a  row of four buttons
   on  the bottom.     The user  should  enter  the preferred
   WWW browser  in the  text entry  box.   Note that,  if the
   browser is not  located in a directory  in the user's PATH
   environment variable, the fully qualified path name should
   be entered.    The buttons  along the  bottom of  the PADE
   Entry are


    --  Clear -- Clear text from the text-entry box.

    --  File Browser -- Invoke the file browser window.

    --  Done  -- Accept the WWW browser choice and exit.

    --  Cancel -- Cancel WWW browser choice and exit.


   The default WWW browser for the PADE is Mosaic.


                             66







  o  Confirmation dialog  is:   -- This menu-entry  enables the
     user to  turn off  some of  the extra  confirmation dialog
     boxes that appear  when certain windows  (such as the PADE
     Setup  window) exit.    Selection  of  this  entry toggles
     Confimation dialog either on or off.

  o  Report bugs  to:   -- This menu-entry  conveys information
     about  where to  send  bug reports  on  the  PADE. Nothing
     happens when this entry is selected.

5.2.6 The Exit Button

The  rightmost  button in  the  PADE Main  Window  is  the Exit
button.  This button enables the user to exit the PADE. If this
button is selected a PADE Question box appears for confirmation
of  exit if the  Confimation dialog  toggle switch in  the PADE
Help menu is set to on.  Otherwise the PADE exits immediately.


5.3 Entering Info in the Setup Window

The  PADE Setup  Window and  its  subwindows (mainly  the Setup
Files and the Tree View windows) are referred to in this manual
as  the Parallel Applications  Management (PAM)  portion of the
PADE software.   It is here that the  tools to manage a complex
parallel application being developed on a heterogeneous virtual
machine are  provided.   Using the Setup window,  the user can,
at  a glance  or with the  click of  a mouse  button, determine
what source files are required to build the PVM executable on a
given host and what commands are needed to create the binary.
   To provide the  PADE with the required information necessary
for  building the  application being  developed, the  user must
specify the following basic information.

  o  Host list -- The user must provide the PADE with the names
     of the  hosts which compose  the virtual  machine on which
     the application is  being developed.   Note carefully that
     the names  of the  hosts provided  MUST match  those given
     to PVM when  the VM is started,  including the presence or
     absence of  the host's domain name.   The  simplest way to
     do this is  to start the PVM console  and issue the "conf"
     command at the  console prompt.   The console will respond
     with a list of the names of the VM hosts as they are known
     to PVM.  These names  must match  the names listed  in the


                               67







     PADE Setup window host list.  If they do not, when pvmmake
     is invoked it  will fail to spawn  the targets program and
     will exit.  Conversely,  if the user receives this message
     after executing pvmmake, the  Setup window host list names
     should be carefully  compared with those  given by the PVM
     console.

  o  Host commands --  The user must provide  the PADE with the
     commands required, on each host, to compile the executable
     binary on  that host.    Multiple commands are  allowed if
     they are separated  by semicolons.   It is most convenient
     to  use the  make  program on  all  hosts on  which  it is
     available.    An  example of  this  is given  in  the PADE
     Tutorial provided in Chapter 4.

  o  Setup Files  -- The  user must  provide the PADE  with the
     names and locations of  the source files to be transferred
     from  the development  host to  each  host in  the virtual
     machine.   Note that the  locations of these  files on the
     development host and on the remote host must be specified.

   This  section  contains  detailed  descriptions  of all  the
buttons and windows found in the PADE Setup Window, Setup Files
Window, and Tree View  Window.  The descriptions below may seem
inordinately many.  The user should keep in mind, however, that
only the three  essential pieces of information described above
are needed  and that most of the  buttons are there to minimize
the amount of typing the user must do.

5.3.1 General Description

The  PADE Setup  Window consists  of  a row  of six  buttons at
the  top of the  window, a  message box  containing two listbox
titles,  two side-by-side, scrollable listboxes,  a message box
displaying the  current setup file,  and a row  of three button
along the  bottom.  This  window is pictured in Fig.  5.7.  The
six buttons are as follows.

  o  Add Host

  o  Add Hosts from Hostfile

  o  Modify Host



                               68




































               Figure 5.7:  The PADE setup window


  o  Delete Host

  o  Setup Files

  o  Tree View

The listbox on the  left, entitled Host list is used to display
the names  of the hosts comprising  the user's virtual machine.
The  listbox on  the  right,  entitled Host  commands,  is used
to  display the command(s)  to be  executed on the  host listed
directly across  from the command in the host  list.  The three
buttons at  the bottom of the window  consist of the Open File,


                               69







Save File, and Done buttons.
   The left  four buttons along  the top of the  window aid the
user in  creating, modifying, and deleting  entries in the Host
list and  Host commands listboxes.   The  rightmost two buttons
(i.e., Setup  Files and Tree View) each  invoke a new window in
which can be entered the source files for each host.

5.3.2 The Add Host Button

The Add Host button  in the PADE Setup Files Window enables the
user to enter new  hosts in the list of hosts kept by the PADE.
When  the user selects  this button,  the PADE  Add Host Window
appears.   This window consists of a  text-entry box on the top
preceeded by the text Host name:, another text-entry box in the
middle preceeded by the  text Host commands:, and a row of four
buttons along  the bottom.  These  buttons consist of the Clear
Name, Clear Commands, Save, and Cancel buttons.
   The Host name  text-entry box enables the  user to enter the
name of the new host.   Note that this name must match the name
of the  corresponding host as  listed when the  user issues the
conf command in the  PVM console program.  It is safe practice,
when  using the  PADE, to  start the  virtual machine  ahead of
entering anything in the PADE Setup Window and, in addition, to
invoke the  PVM console ahead of  time.  If  these names do not
match, then pvmmake will likely fail when invoked by the PADE.
   The Host  commands text-entry box enables  the user to enter
the commands  that must be  issued on the remote  host in order
to compile  the source files  there.  Multiple  commands may be
entered here as long as they are separated by semicolons.
   The row  of buttons  along the bottom  of the  PADE Add Host
Window perform the following functions.

  o  Clear Name -- Clear all text from the Host name text-entry
     box.

  o  Clear Commands  -- Clear all  text from  the Host commands
     text-entry box.

  o  Save -- Accept the information  in the Add Host window and
     exit.

  o  Cancel -- Cancel the request to add a new host to the host
     list.



                               70







Selecting the Save  button affects several changes in the Setup
window.  The text in the Host name text-entry box is entered as
a new item  in the Host list and the  text in the Host commands
text-entry box  is entered as  a new item in  the Host commands
list.   Note that, if the Save  button is selected and there is
no text in the Host name text-entry box, then the effect is the
same as if the Cancel button had been selected.

5.3.3 The Add Hosts from Hostfile Button

The Add  Hosts from Hostfile button enables  the user to read a
list of hosts from a  file and add them to the Host list all at
once.  The most common file that can be used in this way is the
PVM hostfile  that was used to start  PVM (whether by daemon or
by console).   This  is a safe  way of ensuring  that the names
in the Host list  match those given to PVM. Note, however, that
nothing  will appear in  the Host commands  list opposite these
new entries.  This button will only be available for use if the
user has previously selected  a PVM Hostfile in the PVM Menu in
the PADE Main Window before invoking the PADE Setup Window.


5.3.4 The Modify Host Button

The  Modify  Host   button  enables  the  user  to  modify  any
information attached  to an already-existing  entry in the Host
list.    To use this  button,  the user selects  a host  in the
Host list  by clicking on the host  with the left mouse button.
The  entry will  then be  highlighted.   The user  then selects
the  Modify Host  button.    The PADE  Add Host  Window already
described above will then  appear.  This window is the same one
as appears when the Add Host button is selected except that the
information pertaining  to the highlighted  host appears in the
two text-entry  boxes.  The  user can then  modify this text as
desired.    Choosing the  Save button will  cause the  Add Host
window to exit and  the modified text will replace the old text
in the  highlighted entry.   As above, if the  text in the Host
name  text-entry box is  cleared and the  Save button selected,
then the  highlighted entry remains unchanged.   If no host has
been selected  at the time the Modify  Host button is chosen, a
message appears in the  message box at the bottom of the window
indicating that  a host must first be chosen.   The Modify Host
button  is most  convenient for  adding commands  to a  list of
hosts reading in from a PVM hostfile.


                               71







5.3.5 The Delete Host Button

The  Delete Host  button enables  the user  to remove  an entry
from the  Host list.   Note that,  if an entry  is removed, the
attendant  commands and files  information is  removed as well.
To  perform this  operation, the  user first highlights  a host
in the  Host list and then  selects the Delete Host  button.  A
PADE Question dialog box appears asking for confirmation of the
deletion and  the user must  select yes to  affect the removal.
If no host in the Host list is highlighted when the Delete Host
button is  chosen, a message appears in  the message box at the
bottom of the window indicating that this must be done.

5.3.6 The Setup Files Button

The  Setup Files  button enables  the user  to invoke  the PADE
Setup Files Window.   This window is used by the PADE to accept
information about  which source files are  to be transferred to
a particular  host.  As this  window is host-specific, the user
must  highlight a  host in  the Host  list before  choosing the
Setup Files button.  If no host is highlighted when this button
is chosen,  a message appears in the  message box at the bottom
of the window reminding the user to do so.  If the Host list is
empty, this button is  disabled.  The PADE Setup File Window is
described in detail in the next section.


5.3.7 The Tree View Button

The Tree  View button enables the user  to invoke the PADE Tree
View Window.   The Tree  View Window is one  of the most unique
features of the PADE. This window enables the user to add hosts
to the Host list,  add files to the files list for a particular
host, move files  between hosts, modify hosts, and delete hosts
in a completely graphical environment.  The Tree View button is
disabled unless  there is at least one  entry in the Host list.
The PADE Tree View  Window is discussed in detail later in this
chapter.

5.3.8 The Open File Button

The Open File button enables the user to read setup information
from a file on the disk.  Choosing the this button, invokes the
file  browser window enabling  the user to  select a previously


                               72







saved setup file.   Setup files are created when a user chooses
the Save File button discussed next.

5.3.9 The Save File Button

The  Save File  button enables  the user  to save  the contents
of  the  PADE Setup  Window.    This  information  includes the
Host  list,  the  Host  commands  list,  and all  host-specific
lists  of  source  files.    Choosing  this  button  causes two
files  to  be  written.     If  the user-specified  save  setup
filename  is save_setup  then both  this file  and a  file named
save_setup.pvmmake are  created.    If  either  of  these files
already exist on disk,  then a PADE Question dialog box appears
warning the user about this and asking if these files should be
overwritten or the request canceled.
   The pvmmake  file created  deserves some  discussion.   This
file contains  commands that are  determined by the information
contained in the Setup window.  They are as follows.

  o  Files  to Transfer  --  All entries  in  the  source files
     list for  each host  are translated into  commands telling
     pvmmake to  transfer the  files from the  development host
     to the  remote host.   The source  files list  for a given
     host is found in the  Setup Files window when invoked with
     the particular  host selected.   The Setup  File window is
     discussed in detail below.

  o  Commands to  Execute -- All  entries in  the Host commands
     list are translated into commands telling pvmmake to issue
     them on the remote host.

An example  of this file can  be found in  the PADE Tutorial in
Chapter 4.


5.3.10 The Done Button

The  Done button  enables  the user  to end  the  setup process
and  close the Setup  Window.   If  any changes have  been made
since the  last time the Save File  button was selected, a PADE
Question dialog box  appears reminding the user that the latest
work  has not  been saved  and asking for  confirmation.   This
happens regardless of whether the Confirmation dialog switch in
the PADE Help  main menu is on or off.   If the latest work has


                               73







already been  saved, a confirmation dialog  box appears or does
not appear depending on the setting of this switch.


5.4 The Setup Files Window

The  PADE  Setup   Files  Window  enables  the  user  to  enter
the  locations of  all  source files  needed to  build  the PVM
executable  on a  particular host.    There  are two  pieces of
information  about a given  source file whose  destination is a
particular remote host.  These are as follows.

  o  Development  host location  --  The  fully  qualified path
     name of  the source file  on the development  host must be
     specified.   In  the PADE  model of  parallel development,
     all source  files for  all hosts are  kept on  one host --
     the  development host.     When the  time  comes  to build
     the  application,  the appropriate  files  are transferred
     from the  development host to the  remote host.   Thus the
     location  of the  file  on the  development  host  must be
     specified.

  o  Remote host location  -- The fully  qualified path name of
     the source file on the remote host must also be specified.
     With these two  pieces of information,  pvmmake is able to
     affect the transfer of the source file.

The Setup File  window contains these two pieces of information
for all of  the source files associated with a particular host.
This window is described in detail below.

5.4.1 General Description

The PADE Setup Files  Window consists of a row of seven buttons
along  the top  of the  window, a  message area  underneath the
buttons,  a  File  list  listbox  below this,  another  message
window, and two buttons on the bottom.  This window is pictured
in Fig. 5.8.   The top row of  buttons consist of the following
buttons

  o  Add Entry

  o  Copy Entry



                               74
































            Figure 5.8:  The PADE setup files window


  o  Duplicate Entries From Host

  o  Modify Entry

  o  Global Replace Entries

  o  Delete Entry

  o  Edit File

The  message area underneath  the buttons displays  the name of
the host to which the File list below it refers.  The File list
contains the development-host- and remote-host-locations of all
source files  to be sent to  the remote host by  pvmmake.  Each
line of this list has the form



                               75







/dev-host-path/dev-host-file --> /rem-host-path/rem-host-file.

At the bottom are the Save and Cancel buttons enabling the user
to accept or reject any changes made in this window.

5.4.2 The Add Entry Button

The  Add Entry button  enables the  user to add  another source
file  to the  list for  the  selected remote  host.   Selecting
this button  causes the PADE Add  File Window to  appear.  This
window consists  of three frames separated by  bold lines.  The
top  frame contains  a text-entry  box  preceeded by  the words
Local file:   and below  this is a  row of three buttons.   The
buttons are  the Clear, Fill  with last path,  and File Browser
buttons.   The middle frame contains a text-entry box preceeded
by  the words  Remote  file:   on the  top  and two  buttons on
the bottom.   They  are the Clear  and the Fill  with last path
buttons.   The bottom  frame consists of two  buttons, the Save
and Cancel buttons.
   The  text-entry box  in the  top frame  enables the  user to
enter the  development host location  of the source  file to be
added to the File list.  The functions of the three buttons are

  o  Clear -- Clear text in the Local file text-entry box.

  o  Fill with  last path  -- If the  Add File  Window has been
     invoked previously  while the Setup Files  window has been
     open, selecting  this button will fill  the text-entry box
     with the path  used in the previous  invocation of the Add
     File Window.   This  button is disabled  unless the window
     has been invoked more than once.

  o  File Browser --  Selection of this  button causes the file
     browser window  to appear so  that the user  can select an
     already existing local file.

The  text-entry box  in the  middle frame  enables the  user to
enter the remote-host-location  of the source file to be added.
The functions  of the two  buttons are essentially  the same as
those of  the same name  located in the  top frame.   Note that
there is no file  browser button here because the PADE does not
(yet!)   support browsing on remote hosts.   The buttons in the
bottom frame perform the following functions.



                               76







  o  Save --  Accept the  information entered  in the  Add File
     window and exit.  Note  that nothing is saved to a file in
     this operation.

  o  Cancel -- Do not accept  the information in the window and
     exit.

5.4.3 The Copy Entry Button

The  Copy  Entry  button  enables  the  user  to  duplicate  an
already-existing entry in the File list.  The user selects such
an  entry by clicking  on it with  the left  mouse button which
causes  the entry  to be  highlighted.   Selection of  the Copy
Entry  button at this  point will add  a copy of  this entry to
the  bottom of  the File list.    Note that,  if the  button is
selected when no entry is highlighted, a message will appear in
the message area located just below the File list.


5.4.4 The Duplicate Entries from Host Entry Button

The  Duplicate Entries  from Host  button  enables the  user to
add to  the File list  the entire source file  list attached to
another host.   Selection  of this button causes  the PADE Copy
Window  to appear.    This window  consists of  four areas:   a
message  area at  the  top containing  the words  Host  list, a
listbox containing  a list of the host  names identical to that
given  in the  Host  list in  the  PADE Setup  Window,  a frame
containing two radio buttons labeled Local and remote and Local
only, and  a frame on the bottom containing  an OK button and a
Cancel button.
   To  add all  the  files  from a  particular  host,  the user
highlights the host with the left mouse button and then selects
either of the two radio buttons and then chooses the OK button.
If the Local and remote radio button is selected, then both the
locations of  the file on  the development host  and the remote
host  are copied into  the Setup  Files Window.   If  the Local
only button is chosen,  then only the locations of the files on
the development host  are copied and the user must modify these
entries in the Setup Files Window.






                               77







5.4.5 The Modify Entry Button

The  Modify  Entry  button  enables  the  user  to  change  the
information  about a particular  source file given  in the File
list.  To  modify the information about a source file, the user
highlights  the appropriate  entry in  the  File list  with the
mouse and  selects Modify Entry  button.  This  causes the PADE
Modify  File Window  to appear.   This  window is  identical to
the  Add File Window  described above and  already contains the
information from the selected entry in the text-entry boxes.

5.4.6 The Global Replace Entries Button

The Global  Replace Entries button enables  the user to replace
any substring  found in the text in  the File list with another
string.   Clicking this  button causes the  PADE Global Replace
Window  to appear.    The  window  consists of  three  areas, a
text-entry box  on the top in which  the user enters the string
to be  replaced, another text-entry box in  the middle in which
the user enters the  new string, and Save and Cancel buttons on
the bottom.


5.4.7 The Delete Entry Button

The Delete  Entry button enables  the user to  delete any entry
from  the File  list.    The user  highlights  the entry  to be
deleted with  the mouse and selects  the button.   Note that no
confirmation box  will appear regardless of  the setting of the
Dialog confirmation switch in the PADE Help Menu.

5.4.8 The Edit File Button

The Edit  File button enables the user to  edit any file in the
File  list.   The user selects  the desired entry  in this list
with the mouse and  clicks the Edit File button.  The file that
will be  edited is that  specified on the development-host-side
of the  File list entry.   Selection of  this button causes the
PADE  Edit File  Window to  appear.    This window  has already
been  described earlier  in connection  with the  Edit Hostfile
menu-entry in the PVM menu in the PADE Main Window.





                               78







5.4.9 The Save and Cancel Buttons

Located along the bottom  of the Setup File Window are Save and
Cancel  buttons.   These buttons enable  the user  to accept or
reject the  changes made in the Setup Files  Window.  Note that
choosing the Save button  does not cause any file to be written
to disk.   Only the Save button in the PADE Setup Window causes
any files to be written.


5.5 The Tree View Window

The most  unique feature of  the PADE is the  Tree View Window.
This  window enables the  user to  add, duplicate,  modify, and
delete any  host or file in  the application setup information.
In  addition, the user  can obtain setup  information about any
file or host with  the click of a mouse button.  Note, however,
that all the operations  that can be performed in the Tree View
Window can  also be performed  using the Setup  File Window for
each  host.    Some operations,  such  as moving  files between
hosts, are much more convenient using the Tree View Window.

5.5.1 General Description

The Tree  View Window consists of  three major areas.   The top
frame contains a row of ten button that are labeled as follows.

  o  Add Host

  o  Add File

  o  Duplicate

  o  Modify

  o  Delete

  o  Columns

  o  Rows

  o  Help

  o  Save


                               79

































             Figure 5.9:  The PADE tree view window


  o  Cancel

The  second frame  is  a message  box containing  a  summary of
instructions on  how to move  and edit files and  how to scroll
the  canvas.   This  frame also  serves as  a context-sensitive
message box which gives different information depending certain
user  operations  to  be  described  in  detail  below.     The
third  frame contains a  canvas in which  the application setup
information  is depicted graphically.   Each  host is portrayed
as a  circle with the name  of the host  written just above it.
Each source file is represented by a rectangle with the name of
the file  written inside the rectangle.   The set of rectangles
associated  with a  particular host are  connected by  lines to
the circle  representing that host.   Thus  the canvas contains
a set  of circles with each circle being  connected to a set of


                               80







rectangles.   An  example of the  Tree View Window  is shown in
Fig. (5.9).   These  three frames are described  in more detail
below.

5.5.2 The Tree View Buttons

The Add Host and Add File Buttons

The  Add Host and  Add File buttons  enable to the  user to add
hosts and files to the application setup information.  They are
identical, respectively to  the PADE Setup Window Add Entry and
the PADE Setup Files Window Add File buttons and cause the same
windows to appear as do those buttons.

The Duplicate Button

The  Duplicate button enables  the user to  create an identical
copy  of either a  host or  a file.   Selection  of this button
causes the message Click on item to the Duplicated to appear in
the context-sensitive  message area.   If the user subsequently
clicks on  a circle (host) on  the canvas, a  copy of that host
appears  elsewhere on the  canvas.   The user  must then modify
this host.   This  affords the user  a quick way  of adding new
hosts, especially if the same set of local source files must be
sent to this new host.
   The  canvas currently  accomodates an  adjustable  number of
rows  and columns  of  hosts and  that  the new  host  is added
to  the shortest  column.   Furthermore,  the canvas  is filled
row-wise  from left  to right.    That  is,  the first  n hosts
comprise the  first row and host n +1 begins a  second row.  If

the  nth host  is duplicated,  this  duplicate becomes  the nth
host  and all hosts  after it  are displaced.   This  may cause
some  disorientation at first.    The user  new to the  PADE is
encouraged  to experiment with  the Tree View  Window using the
example  setup files provided  in the  examples subdirectory of
the PADE distribution.
   If the  user subsequently  clicks on  a rectangle  (file), a
copy of that file is added to the same host.  The user can then
modify  the name of  this duplicate.   This  is a  quick way of
adding new  files to the list  of those to  be transferred to a
given host.




                               81







The Modify Button

The Modify enables  the user to modify the attributes of either
a  host or  a file.   Clicking  on the  this button  causes the
message  Click on item  to be Modified  to be  displayed in the
context-sensitive message area.
   If  the user  subsequently clicks  on a  circle  (host), the
PADE Add Host  Window appears with the appropriate text already
present.   This window was  described in Subsection  5.3.2.  If
the  user subsequently clicks  on a rectangle  (file), the PADE
Add  File  Window appears  with  the  appropriate  text already
present.    The  Add File  Window was  described  previously in
Subsection 5.4.2.

The Delete Button

The Delete  button enables the user to  delete either a host or
a file  by selecting the  button and then clicking  on the host
or  file to  be deleted.    Note  that,  when deleting  a host,
a  confirmation box  will appear regardless  of the  setting of
the  Confirmation Dialog switch  in the PADE  Help Menu.   When
deleting a file a confirmation box will appear or not depending
on the setting of the Confirmation Dialog switch.

The Columns Button

The  Columns button enables  the user  to choose the  number of
columns of  hosts displayed on the Tree  View canvas frame from
a list  of preselected numbers.   When the  user clicks on this
button,  a pull-down list of  radio buttons is displayed.   The
user can then  select the desired number from a list consisting
of 2,  3, 4, 6,  4, 8, 10, 15,  and 20 columns.   Note that the
size of  the circles and rectangles changes  in response to the
choice while the size of the canvas remains constant.

The Rows Button

The Rows  button enables the user to  choose the number of rows
of hosts  displayed on the  Tree View canvas frame  from a list
of preselected  numbers.  When the  user clicks on this button,
a pull-down  list of radio buttons is displayed.   The user can
then select  the desired number  from a list  consisting of 18,
24, 30, 36, 48, and 60 rows.  Note that the size of the circles
and rectangles changes in response to the choice while the size


                               82







of the canvas remains constant.

The Help Button

The Help  button enables the  user to display a  summary of how
host  and file icons  displayed on the  canvas are manipulated.
Clicking  on  this button  causes  the  summary  information to
appear in the context-sensitive message area.

The Save and Cancel Buttons

The  Save and  Cancel buttons enable  the user  to respectively
accept  or reject  the changes  made in  the Tree  View Window.
Note that  choosing the Save button does  not cause anything to
be written to a file.

5.5.3 The Context-Sensitive Message Area

The context-sensitive  message area gives different information
depending on user operations as follows.

  o  The user  clicks on a circle  (host) -- the  host name and
     associated host  commands as currently listed  in the PADE
     Setup Window are displayed.

  o  The user clicks on a  rectangle (file) -- the locations of
     the file on the  development and remote hosts as currently
     listed  in the  appropriate  PADE Setup  Files  Window are
     displayed.

  o  The user selects the Duplicate button -- the message Click
     on item to be Duplicated is displayed.

  o  The user selects the Modify button -- the message Click on
     item to be Modified is displayed.

  o  The user selects the Delete button -- the message Click on
     item to be Deleted is displayed.

  o  The user selects the Help button -- a summary of the above
     operations is displayed.





                               83







5.5.4 The Tree View Canvas

Moving Files with the Mouse

The user  can move files  from one host to  another by pressing
and holding  the left mouse button on  a rectangle and dragging
the rectangle to another  host.  The mouse arrow must be within
the circle representing the new host in order for the change to
be accepted.   The rectangle will  follow the mouse arrow until
the mouse  button is released.   If the  button is not released
within a host circle, the rectangle will return to its original
position.
   If the  source and  destination hosts  are not  both visible
on the  canvas simultaneously, the  user can still  move a file
between them.   The  procedure is as  follows.   The user first
grabs  and drags  the file  to the  bottom  of the  canvas, the
user then  presses the control key on  the keyboard while still
holding down  the mouse button.   This will cause the rectangle
to  freeze its  position on the  canvas.   However,  moving the
mouse  now causes  the canvas  to scroll.   The  scrolling acts
essentially as  if the mouse arrow were  attached to the canvas
so that moving the mouse arrow towards the bottom of the window
causes the  canvas to scroll up  and vice versa.   The user can
then scroll  the canvas (while still  holding both mouse button
and control  key down) to the destination host.   The user then
releases  the control  key  causing the  rectangle  to reappear
under the  mouse arrow.   The rectangle can  then be dragged to
the destination host and the mouse button then released.

Selecting a File to Edit

The user can also  edit files from within the Tree View window.
Simply  double-clicking the  left mouse  button on  a rectangle
causes the  PADE Edit File Window  to appear.   This window was
described earlier.











                               84
