






                       HOW TO USE ET
____________________________________________________________


This directory contains EXODUS Storage Manager  tester,  ET.
We  do  not  attempt  to  explain ET here. Instead, we given
brief instructions for running command scripts,  which  test
Storage  Manager  functions and recovery. These scripts WILL
CRASH THE SERVER periodically to test recovery.

ET is rather complicated, and can be used in  lots  of  dif-
ferent ways.
____________________________________________________________

NOTE: If you are using ET as part of  the  instructions  for
installing  the  Storage Manager at your site, SKIP the rest
of this file; read  and  follow  ONLY  the  instructions  in
./README.install.
____________________________________________________________


Read on only if you want to delve in a morass of details.

The ET tests can be run in  two  modes:  SINGLE-SERVER,  and
MULTIPLE-SERVER   modes.    The   files   README.single  and
README.multiple give detailed instructions  for  each  mode.
Running  in single-server mode is by far the simplest way to
run the tests.

This directory contains several shell scripts that you  need
to use ET:

    wsm_server (for single-server mode),
    wsm_server.multi (for multiple-server mode), and
    runtests (for both modes).


This directory contains serveral subdirectories.   The  sub-
directory  src/ contains the source for the ET program.  The
other subdirectories contain "ET scripts", which  are  input
to the ET program.  Each ET script is a file with the exten-
sion ".et". The ET scripts  are  found  in  these  subdirec-
tories:

     ./small - operations on small objects
     ./large - operations on large objects
     ./forwarded - operations on forwarded objects
     ./convert - operations that convert objects from one
           format to another (e.g. small to large)
     ./distr - external 2-phase commit scripts.
















You can run all the scripts in one or more directories:

            runtests -d large small
    or
            runtests -d large -d small


You can run a selection of scripts that  you  name  by  file
name:

            runtests -f convert/forward*.et -f large/*1.et


You can run a combination of these:

            runtests -f convert/forwardByInsert.et -d small

If you are testing with multiple servers, you  can  run  all
the scripts with:

            runtests -all
            # Multiple-server mode ONLY!


Any problems encountered by ET will be reported.  The  "run-
tests"  shell  script  prints  brief  information  about the
results to the screen and also to a file  called  "results".
The  output  of  ET  is  put  into  a  temporary file called
/tmp/<test>.tmp.  If the test  runs  to  completion  without
errors, the temporary file is removed.

The script "runtests" can be made to stop if  it  encounters
an error by invoking it with the flag -stop.

For example, the following runs all the small-object scripts
and the single script, convert/convertByAppend.et, and stops
as soon as an error is encountered:

      runtests -f convert/convertByAppend.et -d small -stop.


Each subdirectory  of  scripts  contains  another  directory
called  "answers".  The  answers directory contains the last
100 lines of the output for each script. These answer  files
can  be used for regression testing (i.e., to make sure that
things which used to work before a change, still work).  All
of the ET scripts are structured so they output the contents
of an "object validation file" (OVF) and a  summary  of  how
many  validations  failed  during the script (this should be
0). This information is included in the answer files.

The scripts are written so that they can be run without hav-
ing  to  regenerate  the  OVF  or  reformat the data volume,













however, the answers in the answer files are based  on  run-
ning  the  script on a fresh data volume and OVF. Therefore,
to use the answer files for validation, "runtests" reformats
the  data  volumes  and  removes the OVF before running each
script.

You can use ET to test the following three configurations:

(1)  SINGLE SERVER: One volume is used.  The scripts in  all
     the subdirectories except distr/ apply.

(2)  MULTIPLE SERVERS, INTERNALLY DISTRIBUTED  TRANSACTIONS:
     Several  volumes are used, and they are managed by dif-
     ferent servers.  The scripts in all the  subdirectories
     except distr/ apply.

(2)  TWO-PHASE COMMIT FOR DISTRIBUTED TRANSACTIONS: Use  any
     number  of volumes on one or more servers.  The scripts
     in distr/ apply.  If only one server is used, a trivial
     case  of  the  external  two-phase  commit interface is
     tested.

The files README.single and README.multi give more  informa-
tion.
            STEPS TO TAKE REGARDLESS OF THE MODE
____________________________________________________________


*    Compile the ET test program.  In ./src,  do: "make et".

*    Decide how many servers you will run. Create  a  window
     for each server that you want to run.

*    Decide how many volumes you  want  to  use,  and  which
     servers are to manage which volumes.

*    Update the client's  configuration  file.   An  example
     .sm_config  is  given  in  this release, but it must be
     amended to describe your configuration.  In  the  file,
     describe  the  volumes  that  you  want  to use and the
     servers that manage them (with the "mount" option).

*    Create a window for running the ET tests (the  client).
     In  this window, set the environment variable EVOLID to
     describe the volumes on which you want the tests to  be
     run.

         For example:
                 setenv EVOLID 8000
         or
                 setenv EVOLID "8000 8001 7001 7000"















     If you use any temporary volumes in  your  tests,  THEY
     MUST  APPEAR  AT THE END OF THE LIST OF VOLUMES IN EVO-
     LID!!!. If they do not, ET will not run properly.

*    If you are testing  the  SINGLE  SERVER  configuration,
     single  server, follow the directions in README.single.
     If you are testing the MULTIPLE  SERVERs  or  TWO_PHASE
     COMMIT   configurations,   follow   the  directions  in
     README.multi.


















































