C. STEP BY STEP PROCEDURE FOR INSTALLING AIPS ON A VAX FROM NRAO
SUPPLIED TAPES

1.  Introduction

   The following procedure will install AIPS on a VAX/VMS system.
If you have different graphics peripherals from those at NRAO
a good deal of work will be needed before all the display programs
work properly.

   The installation of AIPS  (including .FOR's, .OLB's, .EXE's, etc.)
using the default options (an average system) requires about 50,000
blocks of disk space.  The installation of a minimal system (no batch,
one user) requires about 45,000 blocks. At NRAO we keep an 'old' system
around thus using about 100,000 blocks.  The disk space can be reduced
after the installation by keeping source and libraries on tape.

   The first installation routine ILOAD will prompt for the specific
parameters needed in your installation and then load everything from
tape.  This step takes about 30 minutes if you do not think about
the answers to the prompts for too long.  The second (and last)
installation procedure IBUILD will compile and link all of the AIPS
routines and create all of the data files.  This step takes about
4 hours, longer on a busy VAX.


   The installation procedure is flexible in allowing various names
for directories, different numbers of disk drives, tape drives, etc.
All of this is determined by how you answer the prompts at the
beginning of the installation procedure.  Filling out the VAX/VMS AIPS
Installation Work Sheet should prepare you for answering these prompts
correctly.

2.  Creating the account and main directory.

   Decide what 3 octal digit group number and user number you will use
for the AIPS account.  This number is referred to as [ggg,uuu] in the
example below.  The disk for the main directory is represented by
'disk' in the example.

    The following is an example of the steps needed for creating the
AIPS account:

Log on to the system manager's account and type the following:

SET DEFAULT [SYSEXE]
RUN AUTHORIZE

In response to the prompt UAF>

ADD AIPS/PASS/UIC=[ggg,uuu]/DIREC=[AIPS]/ACC=AIPS-
/PRIORITY=4/PRIVILEGE=(GRPNAM,DETACH,GROUP,PRMCEB)-
/PRCLM=6/FILLM=40/BYTLM=8192/DEVICE=disk:
LIS
EXIT

Create a directory for AIPS by typing

CREATE /DIRECTORY /OWNER_UIC=[ggg,uuu] disk:[AIPS]


3.  Loading the installation command procedures from tape.

  Now we must load the command procedures from tape that will
control the remainder of the installation.  To do this log on
to AIPS, put the tape labeled AIPS on a tape drive, and type in:

MOUNT /FOREIGN tape_drive_physical_name DUMMY TAPE:
BACKUP  TAPE:START.BCK []/NEW_VERSION

4.  Running the installation procedure

  Next we will run the command procedure that controls the first part
of the installation by typing:

@ILOAD

ILOAD first displays all of the default system parameters on the
screen and allows the user to change them.  This display will
look like the following:

NO.  PARAMETER                             VALUE
1    NO. OF DISK DRIVES                    1
2    NO OF TAPE DRIVES                     1
3    NO OF LINES PER CRT PAGE              24
4    NO OF LINES PER PRINT PAGE            61
5    NO OF BATCH QUEUES                    2
6    PLOTTER NO OF X DOTS PER PAGE         2112
7    PLOTTER NO OF Y DOTS PER PAGE         1600
8    PLOTTER NO OF X DOTS PER CHARACTER    20
9    PLOTTER NO OF Y DOTS PER CHARACTER    25
10   NO OF INTERACTIVE AIPS                3
11   NO OF WORDS IN AP (IN 1024 S)        64
12   NO OF TV DEVICES AVAILABLE            1
13   NO OF GRAPHICS TERMINALS              1
14   NO OF X DOTS PER MM ON PRINTER        7.83
15   NO OF X DOTS PER MM ON GRAPHICS       5.00
16   NO OF USERS ALLOWED ACCESS TO TVS     1
17   NO OF USERS ALLOWED ACCESS TO TKS     1
18   NO ENTRIES IN PRIVATE CATALOGS        300
19   NO OF RESERVED AIPS TERMINALS         0
20   NO OF MESSAGE TERMINALS               0
21   NO OF REMOTE GRAPHICS TERMINALS       0
22   HIGHEST ALLOWED USER NUMBER           800
>>> ENTER NUMBER TO CHANGE, 0=PRINT, -1=FINISHED :

   At this point the user may choose to change any of the parameters
listed by entering the number to the left of the parameter.  By
entering a zero the user may reprint the list of parameters and their
current values.  After all parameters have been set correctly the user
may move on to the next step by entering a -1.  All entries are free
format.

   The following prompts and responses show how to change the number of
batch users from 2 to zero and then move on to the next part of the
installation:

ENTER NUMBER FOR CHANGE, 0=PRINT, -1=FINISHED : 5
NO OF BATCH QUEUES
ENTER : 0

ENTER NUMBER FOR CHANGE, 0=PRINT, -1=FINISHED : -1

   The following section discusses some of the implications of the
various parameters.  Those parameters marked with an asterisk are
important to the installation.  The other parameters can be adjusted
later with utility program SETPAR.  The parameters marked with an
asterisk can also be adjusted with SETPAR but this will require the
user to create and initialize more files (using utility program FILINI)
or make additional logical assignments.  The user must have a good
understanding of the structure of AIPS to do this successfully.  A
careful study of the installation procedure may help you determine
what must be done.

*1    NO. OF DISK DRIVES
        An [AIPS] directory (or your equivalent) must exist on
      each disk before running the installation procedure.  Later
      in the installation procedure you will be prompted for the
      physical names of all of the disk drives.
*2    NO OF TAPE DRIVES
        The installation will prompt for the physical names of all the
      tape drives.
 3    NO OF LINES PER CRT PAGE
 4    NO OF LINES PER PRINT PAGE
*5    NO OF BATCH QUEUES
         The batch subsystem allows a user to set up a file to run a
      subset of AIPS commands as a detached task.  For a minimum system
      this value can be set to zero.
 6    PLOTTER NO OF X DOTS PER PAGE
 7    PLOTTER NO OF Y DOTS PER PAGE
 8    PLOTTER NO OF X DOTS PER CHARACTER
 9    PLOTTER NO OF Y DOTS PER CHARACTER
*10   NO OF INTERACTIVE AIPS
         The number of simultaneous non batch users.  Each interactive
      user requires some disk space.  For a minimum system set this
      number to 1.
 11   NO OF WORDS IN AP (IN 1024 S)
         Words of memory in the array processor in 1024 word units.
      This must be a positive number even for systems without an AP.
*12   NO OF TV DEVICES AVAILABLE
         If you do not have a TV you can save a little disk space by
      setting this value to 0.  If you are going to add a TV later,
      set this value to 1 during the installation so that the TV catalog
      file is created and set it back to zero after the installation by
      using the stand alone interactive program SETPAR.
*13   NO OF GRAPHICS DEVICES
         If you enter a number greater than zero the installation
      procedure will prompt you for the physical name of the graphics
      terminals and create a graphics catalog file.
 14   NO OF X DOTS PER MM ON PRINTER
 15   NO OF X DOTS PER MM ON GRAPHICS
 16   NO OF USERS ALLOWED ACCESS TO TVS
         If set to 1  AIPS1 will be the only user allowed to use the
      default TV.  If set to more than one the users will have to
      cooperate with each other when using the TV.
 17   NO OF USERS ALLOWED ACCESS TO TKS
         The same as 16 above but for the default graphics device.
*18   NO ENTRIES IN PRIVATE CATALOGS
         This entry requires some thought by the AIPS manager.
      If this value is zero the installation procedure will create
      a 400 entry public catalog on each disk to be shared by all users.
      If the entry is negative the procedure will create a public
      catalog with the maximum number of entries equal to the absolute
      value of your negative entry.  A positive entry will cause
      private catalogs to be created whenever a new user
      starts up AIPS.  If a number of users are using AIPS over a
      period of time then the public catalog uses less disk space.
      However if disk space is really crucial the private catalogs
      facilitate backing up of a user to tape.  If private catalogs
      are used the users files on disk will have an extension appended
      to their file name equal to the hexadecimal value of their user
      number.  At NRAO we have found private catalogs to be very
      convenient and have set this parameter value to 500.
*19   NO OF RESERVED AIPS TERMINALS
      This parameter allows specific terminals to always be AIPS1,
      AIPS2, etc., up to the number you enter here.  You will be
      prompted for these terminals later in the installation.
*20   NO OF MESSAGE TERMINALS
         If you have message terminals next to AIPS terminals to print
      the messages of shed tasks (see A-3c) then enter the number here.
      You will be asked for the physical names of all the message
      terminals and the corresponding AIPS terminals later in the
      installation.
*21   NO OF REMOTE GRAPHICS TERMINALS
         If you have terminals that serve as both a user terminal and
      a graphics terminal (graphics commands are sent back to the
      users terminal) enter the number of these terminals.
 22   HIGHEST ALLOWED USER NUMBER
         User numbers may range from 1 to 4095 (hexadecimal FFF).
      Some AIPS tasks like DISKU cycle through all allowable user
      numbers.  This parameter allows those programs to save time
      by not going all the way to 4095.

   After entering a -1, the installation procedure moves into the next
phase.  If you have told the procedure that you have one or more TVs,
then you will be presented with another set of parameters.  For two TVs
the screen will look something like:
 
TV PARAMETERS
NO.  PARAMETER                                VALUE
1    NUMBER OF IMAGE PLANES IN TV DEVICE 1        4
2    NUMBER OF GRAPHICS PLANES IN TV DEVICE 1     4
3    NUMBER OF IMAGE PLANES IN TV DEVICE 2        4
4    NUMBER OF GRAPHICS PLANES IN TV DEVICE 2     4
>>> ENTER NUMBER TO CHANGE, 0=PRINT, -1=FINISHED, -2=1ST PARM SET :

   These parameters may be adjusted in a manner identical to the
first parameter set.  If you need to go back to the first set of
parameters for any reason, for example to adjust the number of TVs,
then enter a -2.

   After a -1 is finally entered for the prompt, the installation
procedure moves into the next phase of prompting for your directory
and device names.  The first prompt is:

ENTER A 20 CHARACTER STRING IDENTIFYING YOUR LOCAL SYSTEM
ENTER:

Enter a string that identifies your institution and computer type.
For example at NRAO, Charlottesville, we use the string "NRAO CVAX".

The next prompt tries to verify that you are logged in to the equivalent
of the AIPS account.

THE DEFAULT IS currentdefault AND SHOULD CORRESPOND TO [AIPS]
ENTER: 1=YES IT DOES, CONTINUE. 2=NO, EXIT :

If the device/directory mentioned corresponds to [AIPS] type in a 1,
else type in a 2.  If a 2 is typed the procedure will exit, allowing
you to log in to AIPS and start over.

If a 1 is entered the next prompt is:

ENTER STRING TO USE FOR NEW VERSION. USUALLY A DATE LIKE 15NOV84"
(ALL ALPHANUMERIC CHARACTERS PLEASE)"

This string will be used in constructing your subdirectory names.
One suggestion is to use the date written on the installation
tape.  This would preserve useful information about the version of
AIPS that your are using.

   The next prompt is:

ENTER STRING TO USE FOR OLD VERSION (<CR> MEANS OLD=NEW)

If you already have an AIPS with the current directory structure,
and you wish to keep it available to users, enter the string used
in its subdirectory names.  If you will only have one version of
AIPS enter a carriage return.  If you have an AIPS with the previous
directory structure (the AIPS/TEST version) you can still keep this
area available by modifying the start up procedures AIPS.COM and
AIPSTR.COM.  Use OAIPS.COM and OAIPSTR.COM as models.

  At this point the procedure displays the directories used for OLD and
NEW and allows you to re-enter if you mistyped.

   Next the procedure prompts for all of the disk drives, tape drives,
TV devices, graphics devices, message terminals, remote terminals and
reserved terminals that your parameter values indicate that you have.
These prompts are described in more detail below.

   The procedure assumes that your current default disk is AIPS data
disk 1.  If you have have told the installation that you have more
than one data disk, then the installation will prompt you for the
rest of the disks with a prompt like:

ENTER PHYSICAL NAME (WITH :) FOR DISK 2 :

   The comment (WITH :) is to remind you to add a colon after
the name.  If a colon is not present the prompt will be re-printed.
The procedure verifies that a [AIPS] directory (or its equivalent)
exists on each disk you enter.  If the directory is not found you
will get an error message and a chance to re-enter.  If you mistyped
just re-enter the disk name.  If the directory does not exist, you
can choose to exit and create the directory and start over or just
create the directory on another terminal before re-entering.

  Next you will be asked for all of the tape drives with a prompt
such as:

ENTER PHYSICAL NAME FOR TAPE 1 (WITH :)

  The tape drives (and terminals and graphics devices in later prompts)
are not verified (except for the existence of a colon in the name) so
you must be careful when entering these names.

   Next the procedure asks for all the 'reserved terminals' that you
indicated that you have.  Reserved terminal i automatically comes up
as AIPS i.

   If you indicated that you have TV devices, you will now get a series
of prompts concerning TV devices.  For one TV the following prompts
appear:

ENTER TV TYPE : 1=IIS (M70), 2=IIS (M75), 3=DEANZA :
ENTER DEFAULT TV DEVICE (WITH :) :
ENTER PHYSICAL NAME FOR TV DEVICE 1 (WITH :) :
ENTER PHYSICAL NAME FOR TV USER TERMINAL 1 (WITH :) :

   We send 3 sets of TV subroutines, one for the IIS model 70, one
for the IIS model 75, and one for the Deanza TV device.  Chose the
model that matches yours.  If you have a different type of TV, and
you already have TV subroutines that correspond to our "Y subs",
you can have AIPS link with these subroutines by editing
[AIPS]ASSIGNL.COM after running ILOAD and before running IBUILD and
replace the statement that assigns logical name TVDIR to one of our
subdirectories with a statement that assigns TVDIR to the subdirectory
containing your TV routines.

   For one TV the default device will have to be the same as TV device
1.  TV user terminal 1 will always have access to TV device 1.  The
other terminals will be able to access the default TV up to the number
of users allowed access to the TV (system parameter 16).

   Next the procedure asks for the message terminals for task messages
and the user terminal whose tasks print to the message terminal.  The
default message terminal for users not in this list is TT:.  That is,
interactive messages, user input, and task messages all occur at the
same terminal.

   Next the procedure prompts for the default graphics terminal
(TEKTRONIC 4012 at NRAO), and all graphics terminals and matching
(primary) users terminals.  Access to the graphics terminals is
controlled in a manner identical to the TVs.

   Next the procedure prompts for all 'remote' terminals.  These
are terminals that serve as both a user input terminal and a graphics
terminal.  All graphics commands originating from users at these
terminals will be sent back to these terminals.

If you have chosen to have a batch AIPS the procedure asks for the
batch message terminal.  This terminal serves as a batch error message
terminal. If you do not have a batch message terminal, you can enter a
disk file name such as BATERR.DAT when prompted for the batch terminal.
In this case, all batch error messages will be written to this file.

   The final prompt asks for the device queue for the plotter.  If you
have a versatec plotter with rev C or higher of the device driver, and
this plotter is installed as a queued device, then enter the device
queue here.  If your system does not satisfy these conditions, then
you may need to modify subroutine ZDOPRT (see section 5b).  In this
case you can enter a carraige return in response to the prompt.

   At this point all of the subdirectories are created, and a file to
make group logical assignments need for AIPS (ASSIGNL.COM) is created.
Next the procedure reads the rest of AIPS from tape and puts the
files into the proper directory or subdirectory.  If an error occurs
reading the tape, the procedure gives you a chance to mount the
tape or to try again.

   This completes procedure ILOAD.  At this time you may need to edit
source code to tailor AIPS to your own environment.  Some common
examples are the priorities for tasks in program
[AIPS.new.AIPS.ZSUB.VMS]ZACTV9.FOR, or fundamental system parameters
such as cluster size in program [AIPS.new.APL.ZSUB.VMS]ZDCHIN.FOR.

   The next (and final) procedure, IBUILD, creates the subroutine
libraries, compiles all of the subroutines and puts them into the
proper libraries, and compiles and links all of the AIPS programs,
utility programs and tasks.  IBUILD then creates and initializes all
system files needed for AIPS.

   The first action of IBUILD is to display the prompt:

ENTER: 0=USE PSEUDO AP CODE, 1=AP AVAILABLE :

If you enter a 0, then IBUILD will automatically link the tasks
that use the AP with the pseudo AP library and put the executable
modules for the tasks in the standard NEW load module directory.
If you enter a 1, then you get more prompts:

ENTER TYPE OF AP : 1=120B COMPATIBLE, 2=5000 SERIES :

Choose 1 for this prompt if you have an old FPS 120B, 2 if you
have one of the newer FPS models with 4K table memory.


ENTER DEVICE AND DIRECTORY OF FPS LIBRARIES AS dev:[dir] :

Do not forget the colon and the brackets.  The program will display
the libraries found in this area and the libraries used in ILINKAP.COM
and ILINKAN.COM.  Since FPS has been known to change their library names
they could be different.  If so, you will have to edit ILINKAP and
ILINKAN before continuing. (Note: When IBUILD displays the libraries
used in ILINKAP and ILINKAN it is displaying values hard coded in
IBUILD.  The libraries displayed by IBUILD will not change after
ILINKAP and ILINKAN have been edited.)

The next prompt:

1=RE-ENTER FPS DEVICE, 2=CONTINUE, 3=EXIT :

gives you a chance to re-enter if you made a mistake, exit to edit
ILINKAP and ILINKAN or continue with the update.

   If you have an AP the installation procedure will link both an
AP version of the task and put the executable module in the standard
NEW load module area, and a pseudo array processor version and put the
executable module in [AIPS.new.PSAP.LOAD].  The pseudo AP version is
useful when the AP is in use, and for debugging.  A user can select
the pseudo AP version inside of AIPS by setting the VERSION adverb to
NEWPSAP.

   Next the installation procedure compiles and links AIPS, all of the
tasks, and all of the utility programs.  Some of the tasks may not
link.  Since all tasks run independently of each other this is not a
disaster, and can sometimes be fixed later.  See the section on
TROUBLESHOOTING for further discussion.


   A copy of all the system error messages that are printed during
the compilation and linking phase of the procedure is written into
the file [AIPS]ERROR.DAT.

   After all of the programs are linked, the installation procedure
attempts to build and initialize all the data files by running program
FILAI2. FILAI2 reads the system parameters from the text file
[AIPS.new.DOC.TEXT]SYSPARM. and builds the files according to these
specifications.  If any older versions of the files exist they are
deleted except for the catalog (CA) files, the Message (MS) files
and the accounting (AC) files.  These files are not deleted or
re-initialized as a protection against losing data on an existing
system.

5.  Tailoring AIPS to your environment after the installation.

a. group logical assignments.

   After the installation is finished you must insure that the group
logical names that have been set by ASSIGNL.COM are always available
even after the system is rebooted.  The most efficient way is to
have ASSIGNL called by the system manager's startup procedure.
The following code shows an example of how the group logical
assignments can be initialized by calling ASSIGNL.COM in the SYSTARTUP
command file.  The example also shows how program BSTRT1 can be
executed at boot time.  BSTRT1 restarts the AIPS batch queues (AIPS
'batch' runs as a detatched task and is not to be confused with the
batch facilities provided by VMS).

$DIRSAV := 'F$DIRECTORY()       !save present directory
$UICSAV := 'F$USER()            !save present uic
$SET UIC [100,101]              !AIPS group (NRAOs. Use yours)
$@DBA0:[AIPS]ASSIGNL.COM        !AIPS disk 1 and directory (Use yours)
$ run 'DIREC'BSTRT1 -           !restart AIPS batch queues.
    /process_name=BSTRT1/uic=[100,101]/noaccounting -
    /noauthorize/error=NEW:BERROR.DAT/output=NEW:BSTRT1.DAT
$SET UIC 'UICSAV
$SET DEFAULT 'DIRSAV

  Another way is to have the group logicals set everytime someone
logs in to AIPS by having [AIPS]LOGIN.COM call ASSIGNL.COM.  To
do this edit LOGIN.COM and remove the !** in the line shown below.

$!**  @ASSIGNL  ! Group logical assignments. Could be in SYSTARTUP.COM

b.  Priorities for tasks and batch jobs.

  Priorities for the shed tasks of AIPS and for the batch jobs are set
in program [AIPS.new.AIPS.ZSUB.VMS]ZACTV9.FOR.  This priority is
currently set at 4 for tasks and 3 for batch jobs.  To adjust these
priorities before running IBUILD just edit ZACTV9.FOR.  To adjust these
priorities after running IBUILD you must
edit ZACTV9, recompile it, insert it into [AIPS.new.APL]SUBLIB and then
recompile (since we usually delete object modules) and relink programs
AIPS.FOR, AIPSB.FOR, and AIPSC.FOR.

c.  The plotter.

   Directing output to a plotter from AIPS can be a problem for many
installations.  Program PRTPL converts an AIPS plot file into the bit
map format needed for a raster type plotter.  Then PRTPL calls
subroutine ZDOPRT.  ZDOPRT reads the bit map file, writes a file called
FOR001.DAT with a DISP='PRINT/DELETE' which contains plot commands
recognized by version C of the VERSATEC driver.  After this file is
closed, the plot will be spooled to the device queue defined by group
logical name PLOTTER.  If your plotter is not a spooled device you will
have to replace ZDOPRT with a subroutine that writes directly to the
plotter.  You can use ZDOPR3.FOR as a model. You may also have to change
the plot commands in ZDOPRT to the commands needed by your particular
plotter driver. The length of the plot line in ZDOPRT is hard coded.
You may have to change this for other types of plotters.
