^PY^-
^IOP^IL0600^IS404^IC1000^IJ00700^IT00700^PN^-


C. STEP BY STEP PROCEDURE FOR INSTALLING AIPS UNDER UNIX

1.  Introduction

   The following procedure will install AIPS on a UNIX operating
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 tape interface will no doubt require some work as
well, however the development effort for these routines can be postponed
for a while.  The extant relevant Z-routines will probably compile and
the programs will therefore have something with which to link but don't
expect them to work properly for your tape controller.

   The installation of AIPS  (including source code, object libraries and
executable modules) requires about 70-80 Mb of disk space.  At NRAO, we
maintain an "OLD" system as well which requires twice the space.  The
disk space can be reduced after the installation by keeping source code
and object libraries on tape.

2.  Creating the AIPS account

   The first step of the installation procedure is to create the AIPS
account on your system unless, of course, it already exists.  If it
already exists, skip this section.  The home directory should not be
too far down from the root since there are limitations in AIPS as to the
string lengths of full pathnames to files.  This limitation is believed
(but not guaranteed) to be filename + 48 character pathname.  The
installation procedure is not sensitive to this but AIPS and the tasks
that AIPS sheds are.  For example, the AIPS verb HELP must be able to
handle the full pathname to the files found in the HELP directory in a
Fortran OPEN statement where the filename is held in a 64 byte
CHARACTER variable.  If you're smart, you won't push this limit.  It
can cause you all kinds of problems.  At NRAO under UTS, the AIPS account
home directory is just /AIPS.

   After establishing the AIPS account a directory named whatever you
like should be created just below the HOME directory which will serve
as the topmost directory of the version of AIPS that you are installing
(we use the release date, e.g., 15JUL84).  This is the ubiquitous "xxx"
that you have seen an will continue to so throughout this document.

3.  Down loading the AIPS system to disk

   The next step in the installation procedure is to down load the
AIPS system from the tar tape to disk.  This tape was generated using
a blocking factor of 20 at a density of 1600 BPI (unless you requested
6250 BPI).  The current working directory during the tape generation
was topmost directory of the version of AIPS requested (e.g., 15JUL84)
under our IBM/UTS system.  Directories were specified in order to
exclude the UTS executable and object module libraries (except in the
case of ports to other UTS sites).  The installer can selectively down
load these directories which include AIPS, APL, DOC, FPS, HELP, HIST,
INC, NOTST, PSAP, UNIX and VMS.  See chapter B section 3 for a
description of these AIPS directory nodes.  For example, if you don't
have a Floating Point Systems (FPS) array processor, the FPS node is
probably of little interest to you, at least for the time being.
Similarly, if you aren't interested in the history of AIPS modifications,
you may not want to down load the HIST node.  However, the installation
procedure requires that the nodes AIPS, APL, DOC (at least the directory
structure), HELP, INC, NOTST, PSAP and UNIX be present.  A rough estimate
of the disk space requirements for each node follows (these allow for
object module libraries where applicable):

   AIPS........................  6 Mb
   APL......................... 14 Mb
   DOC.........................  3 Mb
   FPS.........................  2 Mb
   HELP........................  3 Mb
   HIST........................  1 Mb
   INC.........................  1 Mb
   NOTST....................... 11 Mb
   PSAP........................  1 Mb
   UNIX........................  1 Mb
   VMS.........................  1 Mb

   In addition, the AIPS executable modules will require 30-40 Mb more
bringing the total to the 70-80 Mb mentioned earlier.

   Since mounting a tape and executing tar to dump the AIPS system to
disk varies from system to system, describing a recipe for doing so here
would be useless.  Consult your local UNIX guru if you need help.

4.  Running the installation procedures

   There are three largely automated major steps to the installation of
AIPS called ILOAD, CRLIBS and CREXES.  ILOAD will take just a few minutes
to run and is highly interactive.  CRLIBS and CREXES will require much,
much longer but are list driven.  Under UTS (on an empty machine) CRLIBS
and CREXES require some 12 to 16 hours.  The first of theses, CRLIBS,
attempts to perform the mass compiles of all the subroutines and CReate
object module LIBrarieS.  The purpose of the final step, CREXES is to
compile and link all the programs with the appropriate object module
libraries CReating EXEcutable moduleS.  CRLIBS and CREXES will be
described in much greater detail later but a description of ILOAD
follows immediately.  In addition to the major steps, there are several
minor ones that will described as they are encountered in the text.


a. ILOAD

   Once the system is down loaded, change to the directory $HOME/xxx/UNIX.
You are now ready to execute the ILOAD step of the installation process
that has been mentioned so many times before.  Since you have already
prepared for this step by completing the installation worksheet, you only
need to type ILOAD and answer the questions.  The ILOAD shell script
appears below:

: set -x
: "This is the first step of the installation procedure for AIPS under"
: "UNIX.  It must be run from the directory $HOME/xxx/UNIX where it"
: "resides."
:
   cc ILOAD.c
:
   a.out
:
: set -


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
01           NO. OF DISK DRIVES                            1
02           NO OF TAPE DRIVES                             1
03           NO OF LINES PER CRT PAGE                     24
04           NO OF LINES PER PRINT PAGE                   61
05           NO OF BATCH QUEUES                            0
06           PLOTTER NO OF X DOTS PER PAGE              2112
07           PLOTTER NO OF Y DOTS PER PAGE              1600
08           PLOTTER NO OF X DOTS PER CHARACTER           20
09           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                    0
13           NO OF GRAPHICS TERMINALS                      0
14           NO OF X DOTS PER MM ON PRINTER             7.83
15           NO OF X DOTS PER MM ON GRAPHICS               5
16           NO OF USERS ALLOWED ACCESS TO TVS             0
17           NO OF USERS ALLOWED ACCESS TO TKS             0
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
ENTER>>>

   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.

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

ENTER NUMBER FOR CHANGE, 0=PRINT, -1=FINISHED
ENTER>>>5
05           NO OF BATCH QUEUES                            0
ENTER NEW VALUE>>>2
05           NO OF BATCH QUEUES                            2
ENTER NUMBER FOR CHANGE, 0=PRINT, -1=FINISHED
ENTER>>>-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 the 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 shell variable definitions.  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
        A file system/directory where the AIPS account has read/write
      priviledges must exist on each disk that you specify.  Later
      in the installation procedure you will be prompted for the full
      pathnames of all of the disk drives.
*2    NO OF TAPE DRIVES
        The installation will prompt for the full pathnames 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 background process.  For a minimum
      system this value can be left as zero.  Batch AIPS under UNIX has
      not been developed.
 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 and
      for the time being, it should also be a power of two.  If you
      specify something other than the default (64), you should also
      modify the include file DAPC by adjusting array dimensions
      accordingly.  This should also be done for pseudo array processor
      systems, particularly if you machine does not have virtual memory.
*12   NO OF TV DEVICES AVAILABLE
         If you enter a number greater than zero the installation
      procedure will prompt you for the full pathnames of the tv devices.
      If you do not have a TV you can save a little disk space by
      leaving this value as 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 full pathnames of the graphics
      terminals and create a graphics catalog file.  Again, if you are
      going to add a graphics device later, set this value to 1 during
      the installation so that the graphics catalog file is created
      and set it back to zero after the installation by using the stand
      alone interactive program SETPAR.
 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 300.
*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 the full pathnames of 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 then enter the number here.
      You will be asked for the full pathnames of all the TASKn message
      terminals and the corresponding AIPSn 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
01   NUMBER OF IMAGE PLANES IN TV DEVICE #1       4
02   NUMBER OF GRAPHICS PLANES IN TV DEVICE #1    4
03   NUMBER OF IMAGE PLANES IN TV DEVICE #2       4
04   NUMBER OF GRAPHICS PLANES IN TV DEVICE #2    4
ENTER NUMBER TO CHANGE, 0=PRINT, -1=FINISHED, -2=1ST PARM SET
ENTER>>>

   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 pathnames.  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 under UTS, we use the string
"NRAO(CV) IBM/UTS 2.3"

Next you will be prompted for the number corresponding to a list of
UNIX operating systems that most closely resembles your own.

PLEASE ENTER THE NUMBER OF THE OPERATING SYSTEM WHICH
MOST CLOSELY MATCHES YOUR OWN:
           1         Berkeley 4.1 UNIX
           2         Berkeley 4.2 UNIX
           3         Bell System III (Masscomp)
           4         Bell Version 7 (Amdahl's UTS)
           5         UNOS (Charles River Data Systems)
ENTER>>>

The list includes the more popular flavors of UNIX available with the
conspicuous exception of Bell's System V.  That's simply because we
have had no hands on experience under System V.  It's probably safe
to assume that what will work under Version 7 will work under System
III and will work under System V.  Therefore, if you have a System
V operating system, indicate system III.  We also qualify the
selections by specifying exactly whose implementation of the given
flavor of UNIX we know something about.  Hopefully we won't have to
distinguish between UNIX systems forever but you may find it necessary
to establish yet another flavor option to suit the peculiarities of
your system.  As you become more experienced with the design of AIPS
under UNIX you will see that to do this is not all that difficult.
However, if this is your first installation or if you would prefer to
simply hack on one of the flavors above, just pick one that seems to
be most appropriate.  Your choice is not crucial since after its
initial inception, the use of this feature has dwindled to a few shell
scripts only including AIPSTR which you will want to modify anyway.
The other scripts that make use of this really care only if your system
is UTS.

   The next prompt is:

ENTER NAME OF THE TOP MOST DIRECTORY OF YOUR OLD VERSION OF AIPS
USUALLY A DATE LIKE 15SEP83 (-1 ==> OLD=NEW)
ENTER>>>

If you already have an "OLD" AIPS system in the AIPS account directory
structure and you wish to keep it available to users, enter the name of
its topmost directory.  If you will only have one version of
AIPS enter -1 which will equate OLD with NEW.  ILOAD will determine
the value for NEW from the AIPS account directory structure (i.e., as
the name of the parent directory of the directory in which you should
be when you execute ILOAD).

  At this point the procedure displays the directories used for OLD and
NEW and allows you to re-enter the value for OLD if you wish.  ILOAD
will then check for the existence of OLD.  If ILOAD can't find the OLD
directory, it will say so and ask you for the correct name.

   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 will ask you for the full pathnames of all the disks
you claim to have with a prompt such as:

ENTER FULL PATHNAME (STARTING WITH /) FOR DISK 1
ENTER>>>

If the pathname to the disk does not exist, you will get an error
message and a chance to re-enter the full pathname.  If you mistyped
just re-enter the full pathname.  If the pathname does not exist, you
can choose to exit and create the pathname and start over or just
create the pathname on another terminal before re-entering.

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

ENTER FULL PATHNAME (STARTING WITH /) FOR TAPE DRIVE 1
ENTER>>>

  The tape drives as well as terminals and graphics devices in later
prompts are not verified so you must be careful when entering their full
pathnames.

   Next the procedure asks for all the 'reserved terminals' that you
indicated you have.  Reserved terminals mean that AIPSn will only come up
on reserved terminal n.

   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, 4=OTHER
ENTER>>>

              .
              .
              .

ENTER FULL PATHNAME (STARTING WITH /) FOR DEFAULT TV DEVICE
ENTER>>>

              .
              .
              .

ENTER FULL PATHNAME (STARTING WITH /) FOR TV DEVICE #n
ENTER>>>

              .
              .
              .

ENTER FULL PATHNAME (STARTING WITH /) FOR TV USER TERMINAL #n
ENTER>>>

   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.  If you have
a different type of TV device, and you already have TV Y-routines
that correspond to our "Y subs", you can have AIPS link with these
by specifying "4" (i.e., OTHER) and answer the additional questions
that ILOAD will then ask.  Specifically, ILOAD will ask you for the
name of the AIPS account Y-routine subdirectory where these subroutines
reside.  This will be part of the "APL" branch of the directory
tree and will have the form $HOME/xxx/APL/YSUB/yyy where "yyy" is the
name you specify.  We supply three such subdirectories called IIS, M75
and DEA (see chapter 3, section 3).  ILOAD will test for the existence of
this directory and if it exists, it is assumed that it contains the full
compliment of "Y subs" required by AIPS.  Similarly, ILOAD will ask for
the full pathname of any vendor supplied object module library for your
TV device and will define (in either PROFILE or CDVER) a shell variable
called TVLIB accordingly.  In addition, ILOAD will define two other shell
variables.  One will be called APLyyy where again "yyy" is the name of
of the directory structure node you specified.  The other is called
APLY which is used to indicate which of the Y-routine directories is to
be used by CRLIBS.  In the shell script ILOAD produces, APLY will be
equated to APLyyy if and only if ILOAD finds that $HOME/xxx/APL/YSUB/yyy
exists.  Otherwise, ILOAD will create $HOME/xxx/APL/YSUB/yyy and
define APLyyy as above, but APLY will remain defaulted to the IIS
model 70 Y-routine directory ($HOME/xxx/APL/YSUB/IIS) and TVLIB will be
set to null.  The definition for APLyyy is still generated (in either
PROFILE or CDVER), however it will not be used in the CRLIBS step.  To
activate $APLyyy as the correct Y-routine directory for CRLIBS, edit
the appropriate shell script produced by ILOAD and set APLY=$APLyyy.

   In the case where you specify that no TV devices are
available, ILOAD will set the shell variables TVLIB to null and APLY to
the IIS model 70 Y-routine directory.  CRLIBS will then compile these
routines so that the programs that call Y-routines will at least have
something with which to link.  The Y-routines that expect a TV device
to be there will know that none actually exists from the system parameter
file.  In the future, we may provide a set of dummy Y-routines to serve
as the TV library for systems without TV devices.

   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 ILOAD will ask the installer for array processor information.
If you indicate none, the shell variable APLIB will be set to null and the
shell variable AP will be set to $PSAP in the scripts generated by ILOAD.
Later steps in the installation procedure will generate only a pseudo AP
object module library ($PSAP/SUBLIBU) and AP tasks will therefore
be linked with these routines ONLY.  The AIPS convention is to store the
AP task executable modules that use a real AP in the directory
$HOME/xxx/LOAD and those that use the pseudo AP in the directory
$HOME/xxx/PSAP/LOAD.  However, for those systems that do not have a real
AP, there is no point in doing this and the pseudo AP task executable
modules are simply stored in $HOME/xxx/LOAD.  On the other hand, if you
specify FPS (i.e., enter "2"), ILOAD will define the shell variable AP
as $HOME/xxx/FPS and the shell variable APSUB as $HOME/xxx/FPS/SUB.
These correspond to the NRAO provided subroutines for a Floating Point
Systems model 120B array processor.  ILOAD will then ask you for the
full pathname of the FPS library (i.e., vendor provided) for your 120B
array processor and define the shell variable APLIB accordingly.  ILOAD
will also define the shell variable APZ as $HOME/xxx/FPS/ZSUB/UNIX/LOCAL
The CRLIBS step will know to generate an object module library at the $AP
node based on the $APSUB and $APZ routines as well as a library at the
$PSAP node based on the $SAPSUB and $SAPZ routines (i.e., both a
$AP/SUBLIBU and a $PSAP/SUBLIBU).  Then, when executable modules are
generated via the provided COMLNK script, the array processor tasks
will be linked twice, once with the libraries $AP/SUBLIBU and $APLIB
(real array processor libraries) and once with the library $PSAP/SUBLIBU
(pseudo array processor library).  The executable modules that
result from linking with $AP/SUBLIBU and $APLIB will be stored in
the directory $HOME/xxx/LOAD whereas the executable modules created
by linking with $PSAP/SUBLIBU will be stored in the directory
$HOME/xxx/PSAP/LOAD.

   As in the case of the TV devices, if you specify "OTHER", ILOAD will
quiz you for an array processor routine directory name "aaa" (NOT
limited to three characters).  The string "aaa" will be used to define
the shell variables AP and aaaFIL both as $HOME/xxx/aaa.  ILOAD will
check for the existence of $HOME/xxx/aaa and if not found will ask to
create it.  If you tell ILOAD not to create $HOME/xxx/aaa, it will start
the array processor quiz all over again, otherwise it will create
the necessary directories and define the shell variables AP and aaaFIL as
$HOME/xxx/aaa, APSUB as $AP/SUB and APZ as $AP/ZSUB/UNIX/LOCAL.  ILOAD will
also ask you for the full pathname of the vendor provided link library
for your array processor (e.g., /usr/lib/libsky.a) and define a shell
variable APLIB accordingly.  If ILOAD can't find the library you give it,
you will be asked to either re-enter or skip this question.  If you
elect to skip this question or ILOAD had to create the $HOME/xxx/aaa
directory, the shell variable AP will be defined as $PSAP (i.e., pseudo
array processor system ONLY) and the shell variable APLIB (vendor library)
will be set to null.  The shell variables aaaFIL, APSUB and APZ will
still be defined as the directories above and these directories will
have been created by ILOAD if they didn't already exist, but will not be
used by any of the NRAO provided scripts (since the shell variable AP is
defined as $PSAP).  Once both the vendor provided AP link library (APLIB)
as well as the $APSUB and $APZ routines are available, the shell variable
AP can be set to "aaa" and the shell variable APLIB can be set to the
full pathname of the vendor library in the AIPS account login process.
The shell script CRLIB is discussed later in this document, but provided
lists of the routines in $APSUB and $APZ, it will compile these routines
and create the object module library $aaaFIL/SUBLIBU.  With these
libraries in place, the NRAO provided shell script COMLNK will link
array processor tasks twice, once with $PSAP/SUBLIBU and once with
both $AP/SUBLIBU and $APLIB.  One link will generate an executable
module that will be stored in the directory $PSAP/LOAD and the other will
will generate an executable module that will be stored in the directory
$LOAD (i.e., there will be both a pseudo AP and a real AP version).

   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 generated at login
time via the shell variable assignment TASKTT0=`tty`.  That is, AIPS
interactive messages, user input, and task messages all occur at the
same terminal.

   Next the procedure prompts for the default graphics terminal
(TEKTRONIX 4010 or 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
simple disk filename where all batch error messages will be written,
e.g., BATER.MSG.  ILOAD will take this simple filename and define a
shell variable BATTT0 as $VER/<filename> so that error messages from
different versions of AIPS will be kept separate.

   The next prompt asks for the device queue for the plotter.  This is
yet another device that is not available under any of the UNIX systems
at NRAO.  We do have a Calcomp pen plotter spooled as a device under
one of the other operating systems that we run under VM on our IBM 4341
however, in order to produce a plot under UTS and get the plot file
out to the plotter, we have to go through some amazing if not ridiculous
extremes that would probably less that useful to anyone else.  Under
VMS however, we now have two printer/plotters that AIPS can access.
One is a laser printer that will not be described here.  The other is
a Versatec plotter which also serves as the AIPS line printer.  To
generate plots, there is an AIPS task called PRTPL which depends heavily
on the routine ZDOPRT and the lower level routines ZDOPR2, ZDOPR3 and
ZDOPR4.  You may gain some insight into the requirements for interfacing
a printer/plotter of the versatec variety by studying these routines.
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 the shell
variable 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.

   As mentioned above, under UTS we can produce plots on a Calcomp pen
plotter.  A nonstandard AIPS task called CALPL exists that is simply
a modified version of the AIPS task TKPL (generates raster plots).
We have installed a modified version of the Calcomp subroutine library
under UTS.  One of the modifications is that plot files are automatically
punched over to the virtual machine underwhich the plotter is actually
spooled.  This method of getting the plot into the plotter queue is
therefore not part of the design of CALPL or any of the Z-routines on
which it depends.  You may be able to do something similar with your
plotter.

   The final prompt asks you for the AIPS account default shell (either
Bourne shell or C-shell).  ILOAD will then create a file called
$HOME/xxx/DOC/TEXT/SYSPARM. which is used by the service program FILAI2
to create and initialize most of the files used in running AIPS.
Depending on whether you specified the Bourne shell or the C-shell as
your AIPS account default shell, ILOAD will produce one or two shell
scripts, respectively.  In the case of the Bourne shell, ILOAD will
create a shell script called $HOME/xxx/UNIX/PROFILE.  This script
should be incorporated into the AIPS account login procedure by
inserting it in the file that is executed on login [known throughout
the UNIX world by such names as (.)profile, (.)login, (.)init, etc.].
In the case of the C-shell, ILOAD creates files $HOME/xxx/UNIX/LOGIN and
$HOME/xxx/UNIX/CDVER.  The file $HOME/xxx/UNIX/LOGIN (as in the case
of the Bourne shell script $HOME/xxx/UNIX/PROFILE) should be incorporated
in you AIPS account login procedure.  The file $HOME/xxx/UNIX/CDVER
should remain in the directory where it was created and in the case
where you are maintaining both an OLD and a NEW version of AIPS, it
should be copied to the corresponding "OLD" directory.  To activate
the shell variable definitions, logoff and login again (executing the
UNIX command "newgrp" will probably also work).  This is essential
since from this point on the installation procedure depends on these
shell variable definitions.

   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 fundamental system parameters such as cluster size or
byte and word flip in the subroutine $APLZ/ZDCHIN.FOR.  The Z-routines
for your system should be accumulated in the .../ZSUB/UNIX/LOCAL
subdirectories before proceeding.  Chapter E describes the Z-routines
and which ones will probably require some local development.  The
.../ZSUB/UNIX/GEN subdirectories also include stubbed or potentially
generic versions of these problematic routines.

b. MAKSRC

   MAKSRC is a minor procedure that can be found in the shell script
file $UNIX/MAKSRC.  Its purpose is to generate a file called $UNIX/SOURCE
which contains a list of the full pathnames of all the AIPS source code
pertinent to your installation.  This list is created via the UNIX "find"
command and will include only those Y-routine and Z-routine source code
files that match the libraries that are defined by the shell variables
APLY and APLZ respectively.  In addition, the real AP source code library
files will be included, if any (i.e., if $AP != $PSAP).  This list is
used by the COMLNK shell script to find the appropriate source code.
This means that in order to maintain a current $UNIX/SOURCE file, MAKSRC
must be run periodically, especially when new source code files are
created.  Two other $UNIX shell scripts are provided that make use of this
list, GET and WHERE.  Given the first part of a source code filename
(i.e., without the .FOR or .c extension), GET will search $UNIX/SOURCE
and bring the file up in the local editor.  The local editor is
determined by a shell variable called EDITOR.  If you want to make use
of GET, you should either define EDITOR in your login procedure or hard
code the local editor in the text of GET.  The script WHERE also searches
$UNIX/SOURCE but only reports the full pathname of the routine specified.
The advantage of $UNIX/SOURCE is speed.  The same could be achieved via
the UNIX "find" command with much more painful command syntax as well as
much slower response.  The disadvantage of course, is that $UNIX/SOURCE
can get out of date.  To generate a $UNIX/SOURCE file for your system
(assuming that you have implemented all the shell variables whose
definitions were created by the ILOAD step), simply type:

   MAKSRC

   As an example of what WHERE does, once MAKSRC finishes, type:

   WHERE AIPS

WHERE should print the full pathname of the source code file AIPS.FOR.


c. Potential common block alignment errors

   Before you start the procedures that will do any compiling, you should
take the time to compile a special Fortran program called INCLUD.FOR.
This program consists of many dummy subroutines that "include" all of
the files found in the directory $INCS.  The idea is to check for common
block alignment errors arising from the ordering of variables in the
COMMON statements often contained in these files.  INCLUD.FOR is stored
in the directory $HOME/xxx/UNIX as well as its preprocessed form
INCULD.F.  The preprocessed form should be okay for your system (it
only contains ANSI standard syntax) but if you like, you can try out
the Fortran preprocessor call PP (also stored in $HOME/xxx/UNIX).  To
do this, type:

   PP INCLUD

PP will generate INCLUD.F from INCLUD.FOR.  To check the include files
for common block alignment errors, simply compile INCLUD.F via "f77",
e.g.,

   f77 -w INCLUD.F

   If this generates alignment errors, you should edit the include files
involved and rearrange the variables in the COMMON statement to eliminate
the errors.  Hopefully you will not get any errors.  We have tried to
detect such problem cases by performing this test on each port of AIPS
to NRAO's UNIX systems.  In particular, the theory is that alignment
errors will not occur if variables in COMMON statements are arranged in
descending order of length, i.e., 8 byte items followed by 4 byte items
followed by 2 byte items.  Variables of type LOGICAL are particularly
notorious for producing alignment errors.  This is because on some
systems LOGICALs can be of length 2 or 4 but on others they must be of
length 4.  This problem is solved by placing all LOGICAL variables after
all variables that are always 4 bytes long and before all variables that
are always 2 bytes long.  This way, whether LOGICAL variables are 2 or
4 bytes, common blocks will always align properly.  Some systems make
LOGICAL's 1-byte items when the 'f77' option 'I2' (or its equivalent is
selected.  To avoid alignment errors, you should change the $UNIX/PP
'sed' script $UNIX/DCL.SED to transform declarations of LOGICAL's to
LOGICAL*2 (most will already be declared this way from VMS).


d. CRLIBS

   The next major step called CRLIBS compiles all the subroutines found
in $APLSUB, $APLY, $APLZ, $AIPSUB, $AIPZ, $NOTSUB, $NOTZ, $SAPSUB, $SAPZ
as well as $APSUB and $APZ if you have a real array processor.  CRLIBS
invokes the shell script CRLIB for each subroutine subdirectory and is
list driven.  The lists are stored in the $UNIX directory under names of
the form *.LIS where "*" corresponds to the respective shell variable
names for the subdirectories involved (e.g., $UNIX/AIPSUB.LIS contains
the list of $AIPSUB subroutines to drive CRLIB).  CRLIB will stop when
either the end of the list or a blank line is encountered.  To experiment,
edit AIPSUB.LIS, insert a blank line after the first few routines and
startup CRLIB by typing "cd $AIPSUB; CRLIB < $UNIX/AIPSUB.LIS".  The
resulting object modules will be archived into libraries at the major
nodes $APL, $POPS, $NOTST, $PSAP and when appropriate $AP.  For example,
all the subroutines stored in $APLSUB, $APLY and $APLZ will be compiled
from the lists APLSUB.LIS, APLY.LIS and APLZ.LIS, repectively, and the
resulting object modules will be archived in the library $APL/SUBLIBU.
Similarly, the object modules generated by CRLIB from the subroutines
found in $AIPSUB and $AIPZ will be archived in the library $POPS/SUBLIBU.
CRLIB maintains both an error file (CRLIB.ERR), a log file (CRLIB.LOG)
and a lock file (CRLIB.RUN) at the major node on which it is working
(e.g., $APL/CRLIB.LOG, $APL/CRLIB.ERR and $APL/CRLIB.RUN if CRLIB is
working on the $APL node).  CRLIB.ERR and CRLIB.LOG will be appended if
they already exist.  CRLIBS will not run if an file called CRLIB.RUN
exists at any of the major nodes.  This is to prevent more than one
CRLIBS from being accidently started up by the user.  If any CRLIB.RUN
files are left around by a system crash or an abort, the user will have
to first delete them before CRLIBS will run.  An auxillary script
called WATCH is available for the purpose of monitoring the progress of
CRLIBS/CRLIB.  WATCH tries to find CRLIB.RUN at one of the major nodes
and if found, it will periodically display the last few lines of both the
CRLIB.ERR and CRLIB.LOG files at that node until the CRLIB.RUN file
disappears (CRLIB will delete the CRLIB.RUN file when it finishes with a
list of routines to compile).  WATCH can be aborted at any time without
concern.  At NRAO, we run CRLIBS as a background process and run WATCH
to monitor it.


e. CREXES

   The third and final major step of the installation process is called
CREXES which attempts to compile and link all the AIPS programs found
in $AIPPGM, $APLAPG, $APLPGM, $NOTAPG and $NOTPGM.  Like CRLIBS, CREXES
is an upper level script that executes a list driven lower level script
called CREXE. CREXE is much simpler than its CRLIBS counterpart (CRLIB).
This is because CREXE in turn calls the shell script COMLNK for each
program in its list.  The lists that are used to drive CREXE (as in the
case of CRLIB) are stored in the directory $UNIX with names of the form
*.LIS where "*" corresponds to the respective shell variable names for
the subdirectories involved (e.g., AIPPGM.LIS contains a list of the
$AIPPGM programs to compile and link).  You might notice that these lists
do not include every *.FOR file found in say, $AIPPGM.  This is because
some programs either do not apply to any installation other than the
Charlottesville VAX (often referred to as CVAX) or in the case of many
of the programs found in the nonstandard program directories ($NOTAPG
and $NOTPGM), the code is so nonstandard that all attempts to implement
them under UNIX have been futile.  You are welcome to try them if you
like.  The lists supplied are based on the programs that we were able
to compile and link successfully under UTS.  This does not imply that
they necessarily work (many have never even been tried).  However, a
substantial number of the tasks most often run by AIPS users have
been execised to some extent.  The prospect of CREXES grinding out a
set of executable modules that are of no use suggests that it is
probably wiser to compile and link the AIPS stand alone programs and
AIPS tasks on an individual basis, at least until the integrity of the
subroutine object libraries is proven out.  The next section describes
the stand alone programs that you must get up and running before all
else.


f. FILAI2, SETPAR, POPSGN and AIPS

   Once the executable modules for FILAI2 and POPSGN have be created,
you are ready to generate and initialize the AIPS system/communication
files.  FILAI2 will create and initialize a number of files in $DA00.
It will also create (but not initialize) the POPS memory files in
$NEW (ME* files).  FILAI2 uses the $DOCTXT/SYSPARM. file generated by
the ILOAD to determine how many of each type of file to create.  After
running FILAI2, disk 1 (i.e., $DA00) should contain the following
files (size is in 512-byte blocks):

File type       Bytes    Number of files

AC100000;1      57344    1
BA100qnn;1      65536    1 * no_of_interactive_users * no_of_batch_queues
                           + no_of_batch_queues
BQ100000;1       8192    1
CA100000;1     221184    1 on each disk (zero if private catalogs).
GR100000;1      57344    1
IC100000;1       8192    1
IC10000n;1     139264    no. of tvs
ID10000n;1       8192    no. of tvs
MS1000nn;1      57344    2 * no_of_interac_users + no_of_batch_queues + 1
                           (if public catalog/message file)
MS100100.001;1   8192    1 (if private catalogs/message files)
TA10010n;1       8192    no. of tape drives.
TD100000;1      24576    1
SP100000;1       8192    1

   AIPS will also create other data files after being in use.  SETPAR
will allow you to reset the system parameters in the $DA00/SP* file
created by FILAI2.  If you told ILOAD that you had a TV when in fact
you don't but did so just so FILAI2 would generate the necessary files
for the future (i.e., you are planning on adding a TV later), this is
when you should run SETPAR to set the number of TV's to zero.

   FILAI2 also creates (but does not initialize) the AIPS 'memory'
files in $NEW as follows:

File type   Bytes    Number of files

ME10000n    122880   2 * no_of_interac_users + no_of_batch_queues + 1

POPSGN uses the file $HLPFIL/POPSDAT.HLP to initialize the $NEW/ME*
files (see GOING AIPS for more on POPSGN).  There are shell scripts in
$UNIX called FILAI2, SETPAR and POPSGN which will startup the respective
programs.  FILAI2 must be executed first, followed by POPSGN.  After
these programs run successfully you are ready to try running AIPS when
it has been compiled and linked.  A third shell script, $UNIX/AIPS
which simply executes another shell script $UNIX/AIPSTR will try to
startup AIPS.  AIPSTR will require some local development.  If AIPS
comes up and asks you for your user number, the installation has been
tremendous success.  Good luck!


g. Other $AIPPGM programs of interest

   There are several other stand alone utility programs with which your
AIPS manager will want to become familiar.  These include:

   PRTACC............prints out $DA00/AC* file data in a variety of
                     ways (i.e., AIPS accounting data).

   GRIPR.............allows you to index, list or make entries to the
                     $DA00/GR* file (i.e., AIPS gripes).

   GRITP.............used to make a GRIPE tape from the $DA00/GR* file
                     to send back to the AIPS group at NRAO.

   FILINI............used to initialize individual AIPS system files.

   AJAX..............used to delete a special group of scratch files
                     from aborted tasks (e.g., APCLN, UVMAP, UVSRT,
                     CONVL, FFT, etc.).  These scratch files can be
                     quite large, so AJAX is potentially a very useful
                     program except that it is designed for public
                     catalog installations only.

   BATER.............a stand alone AIPS-like program for preparing and
                     submitting text to batch AIPS.

   BSTRT1............starts up all AIPS batch queues (must be run after
                     every system restart).

   AIPSB.............batch version of AIPS (activated by AIPSC).

   AIPSC.............checks batch AIPS input for errors and if none,
                     activates AIPSBn (AIPSC is activated by either BATER
                     or AIPS).

   CATCHC............converts old clean component file to new format
                     (1/83).

   CATCHG............converts public catalog arrangement to private user
                     catalogs.

   CATCHL............converts from old to new header format (1/83).

   CATCHR............converts filenames containing decimal user numbers
                     to filenames containing the user number in
                     hexidecimal.

   CATCHU............converts old UV data format files to new format
                     (1/82).

   DELSG.............used to delete outdated SAVE/GET files after AIPS
                     system updates.

   FIXCAT............used to delete entries in user catalog files.

   FIXFIL............used to manually correct bad data in a user file.

   FIXUSR............used to recover entries in user catalog files.

   RECAT.............used to rebuild/recover a damaged user catalog file.

   SETTVP............like SETPAR but for manipulating the TV display
                     parameter file.
