FILE: spider-inst-alpha.doc                       October 1, 1996

         SPIDER INSTALLATION ON VAX/VMS (Alpha AXP)  

0)  CONTENTS OF THIS DOCUMENT:
    ==========================

    1) LOADING THE TAPE
    2) INSTALLATION OF EXECUTABLES
    3) EXECUTABLE USE
    4) OTHER INSTALLATION-DEPENDENT FEATURES
    5) TESTING THE SPIDER SYSTEM
    6) BUGS

1)  LOADING SPIDER TAPE

    Code is distributed on TK50 or 8mm tape in DEC BACKUP format. 
    To load the tape use the following commands but substitute your 
    tape drive's logical name for msa0: and  your desired SPIDER 
    source code location for spider_dir:

    $ALLOC msa0:
    $SET DEF [spider_dir]
    $BACKUP /LOG msa0:SPIDER.BCK [...]*.*
       
    The main directory will contain SPIDER subroutines. The routines
    have been compiled and placed in object libraries.  There are
    different libraries and executable files depending upon the type of
    workstation in use.

2)  INSTALLATION OF EXECUTABLES

    A) Using Precompiled and Linked Executables.
       If you run VMS version 6.0 (or newer), you should be able to use
       the SPIDER executables provided on the tape.  Use DRIVERA.EXE for 
       interactive use and  DRIVERAX.EXE for batch  use.  Use the 
       following command to try SPIDER from a terminal window:

       $RUN [spider_dir]DRIVERA
               .ENTER DATA CODE: DAT  

       You may delete SPIDER.OLB, DRIVER.EXE, and DRIVERX.EXE if you 
       do not have any non-Alpha AXP computers.  If the executable 
       files do not run on your computer proceed to step B).

    B) Linking the Executables.
       If SPIDER does not run, there is probably an incompatibility 
       in the use of shared libraries or the operating system version.  
       You may have to link SPIDER on your machine.  

       SPIDERA_LINK.COM contains sample code for linking SPIDER.  Edit 
       the linking command file for any necessary local 
       linking modifications.  Then use the following commands to link 
       SPIDER and create new executable files:

       $@[spider_dir]SPIDERA_LINK

       If the link fails or the new executable files do not run on 
       your computer proceed to step C). 

    C) Compiling and Linking the Executables.
       If SPIDER does not link properly then you may not have 
       shareable images or you can not use the object library due to 
       incompatible operating system versions. You may have to create 
       a new SPIDER system starting from the source 
       code files.   SPIDERAGEN.COM contains commands for complete 
       system generation, starting from the source code files. This 
       command file directs all the steps (compile, build library, 
       link) to create the executable files of the SPIDER  system.  
       Use the  following commands (see note 4B below first):

       $SET DEF [spider_dir]
       $@SPIDERAGEN.COM

       If SPIDER does not link properly then you may not have 
       sharable images or you can not use the object library due to 
       incompatible operating system versions.   You may have to 
       compile and link the  source code.  Use the 
       following commands (see note 3C below first):

    C) Compiling and Linking the Executables.
       If your VAX/VMS version can not use the executables and object 
       code libraries provided, then may will have to create a new 
       SPIDER system  from the source code.  SPIDERAGEN.COM contains
       commands for complete system generation, starting from the source 
       code files. This command file directs all the steps (compile, 
       build library, link) to create the executable files of the SPIDER 
       system.  

       To generate the system, first delete or rename the existing 
       SPIDERA.OLB library.  Execute SPIDERAGEN.COM .  This procedure 
       compiles the source code, stores the object code in SPIDERA.OLB,
       INILUN.OBJ and INILUNI.OBJ,  and links the object code to create
       DRIVERA.EXE and DRIVERAX.EXE executables. 

3)  EXECUTABLE USE

    Note that DRIVERA.EXE is created to serve the interactive (and
    pseudo-batch) runs while DRIVERAX.EXE is created to serve the true
    VMS batch runs. DRIVERAX is called by the command file SPIDERA.COM. 
    The difference between DRIVERA.EXE and DRIVERAX.EXE  is that DRIVERA 
    includes INILUNI.OBJ and DRIVERAX includes INILUNB.OBJ during 
    linking. These subroutines define the logical unit numbers that are 
    different for true batch and interactive processing. They also set 
    aside the amount of common memory avilable to SPIDER operations.  
    INILUNI.OBJ and INILUNB.OBJ are the only object code files that 
    are explicitly linked and must not be contained in the SPIDERA.OLB 
    library.


4)  OTHER INSTALLATION-DEPENDENT TASKS

    A) Directory Structure.  

       Directory        Files that should be in that directory:

       [.SPIDER.SRC]      *.EXE, *.COM, *.F, *.INC, *.OLB, 
                          *.OBJ, *.INC
       [.SPIDER.MAN]      *.MAN, *.PMA, *.GDE, *.DOC, *.MEN
       [.SPIDER.RGB]      *.RGB
       [.SPIDER.PROC]     *.SYS
       [.SPIDER.DOCS..]   *.HTML, *.GIF, *.XBM

    B) Logical and Symbol Assignments for Users.
       Inside SPIDER, directory and disk names are specified by 
       logical names which you define in your SPIDER users login 
       files.  These names are necessary to access manual chapters 
       and to find the .SYS procedure files.  Sample assignments 
       are given in LOGINEXT.COM   Edit the assignments in this 
       file to correspond to the locations of the relevant files 
       on your system.  Then include the edited file in the 
       LOGIN.COM file for each of the users who will access SPIDER. 
       Whenever one of the users logs in the following logical
       assignments will occur (with ***** replaced by the relevant
       local directory).

       $ASSIGN /JOB/GROUP/PROCESS [*****] PROC       (for *.SYS)
       $ASSIGN /JOB/GROUP/PROCESS [*****] SPMAN_DIR  (for *.MAN)

       Whenever one of the users logs in the following symbol
       assignments will occur so that users can start SPIDER and
       SPHELP easlily from any location. (with ***** replaced by the 
       relevant local directory).

       $DRIVERA :== RUN [*****]DRIVERA       (for Alpha DRIVER)
       $SPIDERA :== @[*****]SPIDERA          (for Alpha SPIDER)
       $SPHELP  :== @[*****]SPHELP           (for spider help) 


    C) Logical Assignments for Programmers.
       To compile programs, you need certain definitions to assign the
       the correct directory names for the included files that are 
       referred to in the source code.  Add the  following definition to
       the LOGIN.COM files of any user who  will do SPIDER related 
       program compilation.  Sample assignments are given in 
       LOGINEXT.COM: 

       $ASSIGN spider-source-directory COMMON1

    D) Memory allocation.
       The main memory allocation for the SPIDER system is in the 
       unlabeled common.  This is defined by the size of MAXDIM in 
       INILUNI.F  (for interactive use) and INILUNB.F  (for true
       batch use).  If your system does not allow you to use as 
       much memory as defined there, you will have to edit these 
       files to decrease MAXDIM, recompile the INILUN routines 
       (note that INILUN*.OBJ is NOT placed in any object library) 
       and relink your SPIDER system.

    E) Line graphics support.  
       The line graphics part of the package has been extended. 
       The SPIDER line graphics programs create a so-called contour 
       storage file, which can then be plotted using the 
       appropriate device driver.   The command for plotting is 
       'CS DI **' (where ** is replaced by an abbreviation for
       the particular device).  Device drivers are provided for a 
       a GOULD (HPGL) plotter, a TEKTRONIX plotter 
       (both connected in line with the terminal), Postscript 
       printers and for a DEC VT125 graphics terminals.

    F) Command files.  
       Some of the *.COM command files provided contain 
       directory names. If you use these command files you will 
       have to edit the directory names to correspond with the 
       directories in use at your installation.

       Command files provided:

       SPIDERAGEN.COM       Creates SPIDER system from the source code.
       SPIDERALINK.COM      Links SPIDER system.
       LOGINEXT.COM         Gives logical names, symbols, etc. that
                            should be defined in the login files of
                            SPIDER users. 
       SPIDERA.COM          Starts batch SPIDER.  Accessed when user
                            types the command SPIDER.
       SPHELP.COM           Accesses SPIDER manual.
       NEWINFO.COM          Used by SPHELP.COM
       SPUSER.COM           Used by SPHELP.COM


5)  TESTING THE SYSTEM
 
    In this and the following tests, use the SPIDER manual to check
    the proper usage of commands and the expected performance of
    the operations.
 
    A) Testing Interactive Operations

       $SET DEF [spider_dir]
       $RUN DRIVERA
       .ENTER PROJECT/DATA CODE: PRJ/DAT
                .OPERATION:

       TEST #1 : Test operation 'ME'. This should give you the list of
       commands. (Note that all commands are listed, including those 
       not contained in the distributed program set)
 
       TEST #2 : Test arithmetic operations.  These are the so-called 
       pocket calculator functions which allow a wide range of 
       arithmetic expressions to be computed.  Expressions should be 
       entered in the same way as FORTRAN arithmetic expressions 
       appear in a FORTRAN source program, e.g. ((3-0.26)/4)**2.  
       See USER.DOC for more details.

       TEST#3 : Test the use of registers and document file. Execute 
       the sequence
                       X10=2
                       X20=5
                       SD 1,X10,X20
                       DOC001
                       UD 1,X40,X50
                       DOC001
                       X40
                       X50

       The values 2 and 5 stored in the registers X10 and X20 should 
       have been saved in DOC001.PRJ under the key 1 and subsequently 
       unsaved into the registers X40, X50.  Upon entering 'X40', 
       the system should respond with '2.00000', and upon 'X50', 
       it should respond with '5.00000'.  
 
       TEST#4 : Test file creation.  Execute the sequence

                       MO
                       JNK001
                       16,16
                       T
                       FI
                       JNK001
 
       The operation 'MO' creates a test pattern (a diagonal sine 
       wave), and 'FI' gives some info about this image.

    B) Testing a Simple Procedure Run. 
 
       Start DRIVERA as before, then execute the sequence

                       MD
                       TR ON
                       MO1
 
       'MO1'  refers to a file MO1.PRJ that is part of this package,
       containing exactly the sequence previously entered in the 
       interactive mode, but with 'PR' added to print the image
       file out in the RESULTS file.  The procedure 
       sequence as well as the overprint display will be contained in 
       RESULTS.PRJ, which can be printed on a line printer.


6)  BUGS, SUGGESTIONS

    A) Since "X" is used as a flag for register substitution in file
       names you should avoid the use of "X" in filenames except for
       this purpose.  Also the letter "X" anywhere on the command
       line may cause problems.

    Please send any further bug reports to:

       ArDean Leith
       phone: 518-486-5604
       fax:   518-474-7992
       email: leith@wadsworth.org