% UGUIDE.TEX -- AIPS Installation Porting Reference for Unix Systems
%               Soon to be renamed the Installation Reference Manual.
%
% Based on Kerry Hilldrup's reference; Pat Murphy [PPM] 90.11.29
% First TeX version printed 91.05.23 [PPM]
% Modified by Glen Langston 91.05.28 [GL]
% Table-of-Contents stuff gotten right 91.06.03 [PPM]
% Modified for 15APR92 92.05.04 and following days [PPM] 
% Modified for 15OCT92 92.10.01 and following days [PPM] 
% Modified for 15JUL93 93.08.21 (yeah, I'm late)   [PPM]
%
% This document should produce a table of contents file and will
% include it the second time around through TeX.
%-----------------------------------------------------------------------
\input NRAO_MACROS.TEX          % define sections, subsections, etc.
\input FORTRAN.TEX              % inserted text
\def\ttaips{{\tt AIPS}}         % references to program, not the system
\title{\aips\ \it Unix Porting Reference}
\footline={\ifnum\pageno>1
                \ifodd\pageno {\twelveit Version \thisver \hfil \today}
                \else         {\twelveit\today \hfil Version \thisver}
                \fi
           \else
                \hfil
           \fi}
\hrule height1.5pt \vskip 2pt \hrule \vskip 4cm
% *********************
\def\thisver{15JUL93}
% *********************
\pageno=-1
\centerline{\nraofont The AIPS Unix Porting Reference Manual}
\bigskip
\centerline{\twelvesl Version \thisver}
\bigskip\bigskip
\centerline{\twelveit Patrick P.~Murphy}
\centerline{\twelveit National Radio Astronomy Observatory}
\centerline{\twelveit 520 Edgemont Road}
\centerline{\twelveit Charlottesville, VA 22903--2475, USA}
\centerline{\twelveit (804) 296-0372}
\smallskip
\centerline{\tt pmurphy@nrao.edu}
\medskip
\centerline{\it Requests for help etc.~to \/ \tt aipsmail@nrao.edu}
\bigskip

\vfill
\hrule \vskip 2pt \hrule height 1.5pt
\eject
\ \vskip 5cm
\centerline{Ignore this page}
\vfill\eject
\contflag=1
\newread\testfile
\newwrite\contfile
\openin\testfile=\jobname.toc
 \ifeof\testfile\message{No Table of Contents found}
  \closein\testfile
  \contflag=1
  \message{(will generate one)}
  \immediate\openout\contfile=\jobname.toc
 \else
  \closein\testfile
  \contflag=0
  \message{Including existing table of contents}
  \ \bigskip\centerline{\nraofont TABLE OF CONTENTS}\bigskip
  \input\jobname.toc
  %%% @@@ if toc has odd number of pages, need this:
  \vfill\eject 
  \ \vskip 5cm
  \centerline{Ignore this page}
\fi
\vfill\eject
%------------------------- Document begins here ----------------------
\pageno=1
\newsection{INTRODUCTION}

This manual is intended as a reference for \AIPS\ system managers
installing a new version of \AIPS\ on a Unix machine.  It describes the
4 phases of \AIPS\ installation and many of the computer system
dependent changes which may be required.  There is a separate document
(The {\it \AIPS\ Unix Installation Summary\/}) that covers the basics of
installing \AIPS\ on the more common systems (Suns, IBM RS/6000, Convex,
HP, DecStation); if you are installing \AIPS\ on one of these systems,
please use that document as your primary guide.  The main purpose of
this document is twofold: As an aid to people installing \AIPS\ on new,
untried systems; and a more detailed explanation of the various steps of
installation for all systems.

\AIPS\ has had a long association with the proprietary VMS system,
and the installation process described here has many of its roots in the
VMS installation.  Hence there is no ``{\it make aips\/} command.
Because there are many variants of Unix, it is hard to arrive at an
installation procedure that will run with a minimum of installer
intervention, but we try.  This document explains the differences
between some UNIX systems, and guides the installer through the required
stages of the installation.

Unlike older VMS installations of \AIPS, there is currently no support
for a ``load-and-go'' installation with precompiled binaries.  NRAO
is, however, investigating the possibility of providing such an
installation option in the future.  For now, however, \AIPS\ is
distributed as a ``tar'' tape (or file) with source code only.
Recompilation is necessary to get a running system.

For an overview of the installation process, the reader is again
strongly recommended to read the {\it \aips\ Unix Installation
Summary\/}.  The following sections also give a brief tour of the work
involved. \medskip

\newsubsection{Overview of the Installation Process}

There are four basic steps to installing \aips\ on a Unix system.
These are often referred to as the {\it INSTEPs\/} in what follows,
\eg, the second step is {\tt INSTEP2}.  Some of the terminology in
this section may be confusing; it will be explained later in this
document, however.  Don't worry too much about the details yet; just
try to get an overall view of what needs to be done. \medskip

\newsubsubsection{INSTEP1: Setup and Unpacking}

The first steps of the installation process involve optionally creating
an \ttaips\ account, loading the installation tape to disk and running
an initial shell script.  This is the same {\tt INSTEP1} script as would
be used for a system that \AIPS\ is already ported to, \eg, Sun4.  The
procedure will ask you several questions and will attempt to set up the
directory structure and configuration files needed for an 
\AIPS\ installation.

If you are porting \aips\ to a new system, there will no doubt be some
Z-routines (machine-specific) that require local development (only a
handful hopefully).  (Note that NRAO has started a port to the DEC
Alpha--OSF/1 system).  The generic versions should suffice well into the
installation process.  Similarly, the Q-routines which constitute the
vanilla pseudo array processor library, and the X11-based TV server and
its set of Y-routines should be adequate for most new ports.  In the
unlikely event that you actually have a dedicated TV device similar to
the IIS or DeAnza systems, there is a stubbed versions of the Y-routines
that will do until you are ready to address the problem of local
development for unsupported TV devices.  For systems that \aips\ is
already ported to, {\it there should be no need\/} to develop local Z,
Q, or Y routines.  However, consult the appendices of this document to
check for notes on your system hardware and operating system versions.

We ask that you please {\it DO NOT\/} simply edit the distributed
versions of text files if you find they require require modification.
If you ask NRAO to provide support for problems that develop later, it
will be much harder for us to figure out what is going on if you have
done this.  Instead, please either use local directories if you are
doing a new port or significant development; or preserve the file in its
original directory, \eg, as {\tt <filename>.NRAO}.  Your cooperation in
doing this will be much appreciated!  It'll also make it easier for us
to assist you if you ever need our help.\medskip

\newsubsubsection{INSTEP2: Massive Compilation of Libraries}

This and the following steps are almost completely automated.  There is
a shell script {\tt INSTEP2} that will recompile all the necessary
subroutines into the right libraries.  It and the {\tt INSTEP3} and {\tt
INSTEP4} scripts are copied to an architecture-specific area in the
previous step to allow different architectures to be installed at the
same time.  There is unfortunately no {\it Makefile\/} for this or the
following steps, although the script comes fairly close to doing most of
the same things.

After the essential setup is performed --- editing the {\tt LIBR.DAT}
file if necessary, modifying or checking the compiler and linker
settings, and so on --- the {\tt INSTEP2} procedure will start the
massive compilation.  This can take a {\it long\/} time on some systems;
there is no formula for exactly how long as it depends on compiler
efficiency and processor speed.  On fairly modern, fast RISC machines,
it may only take a couple of hours.  There are about 1350 routines
% @@@ check this - wc -l *.LIS
altogether.  The nice thing about {\tt INSTEP2} (and the following steps
too) is that they checkpoint themselves.  This means that if one routine
breaks the procedure by not compiling, you can fix that routine and
continue where you left off without having to redo the previous good
compilations.  The same applies to system crashes or other unwelcome
interruptions.

As some 400 routines precede the Z-routines, the first part of {\tt
INSTEP2} is a good time to look at the few Z-routines and Z-procedures
that require local development for new ports (see the appendix on this
topic).  In particular, on processors where ``little endian'' byte
ordering is used, the value of {\tt BYTFLP} as set in the routine {\tt
ZDCHI2} must be changed.  Also, the values for {\tt SPFRMT}, {\tt
DPFRMT}, {\tt TTYCAR} as well as other system constants and parameters
defined in {\tt ZDCHI2} should be checked and modified as required.
Examples of little-endian architectures include DecStations (no need to
change anything; we already did), some Alliant machines (note there is
already an {\tt \$APLALLN} area), and all Intel-based machines.\medskip

\newsubsubsection{INSTEP3: Building Essential Tasks}

The third step of the installation process involves compiling and
linking a small but highly representative subset of \aips\ application
and maintenance tasks.  The programs involved are:\medskip

{\ndot The programs essential to create/maintain \aips\ system files}
{\ndot The \AIPS\ task itself, and}
{\ndot About a dozen of the most used tasks\medskip}\medskip

The \AIPS\ system files that must be generated include a system
parameter {\tt SP} file, an accounting {\tt AC} file, batch queues {\tt
BQ} and batch work {\tt BA} files (these are strictly speaking
optional), a password {\tt PW} file, image catalog {\tt IC}, {\tt
ID} files, a task communications file, a ``gripes'' file, and {\aipsfont
POPS}\footnote\dag{\eightpoint People Oriented Parsing System, \ie, the
                               \AIPS\ command language}
memory files.  These are created via the program {\tt FILAIP} which
prompts for its inputs.  This must be followed by the execution of the
program {\tt POPSGN} to initialize the {\aipsfont POPS} memory files.
Finally, the program {\tt SETPAR} should be run to set the system
parameters not set by {\tt FILAIP}.  In addition, for those systems with
TVs other than screen servers, the program {\tt SETTVP} may also need to
be run in order to change the default TV parameters.  After these
programs have been run, you are ready to run a basic stripped-down
\AIPS\ system.  Other details, such as network services, need to be
addressed before the network and graphical fetaures of \AIPS\ can be
activated. 

For networked installations, \ie, where more than one host of possibly
different architectures will share the \AIPS\ directory tree, you will
need to perform additional setup tasks.  Most, but not all, of this
has been encapsulated in some shell scripts ({\tt DASETUP}, {\tt
SYSETUP}) and a {\tt SETSP} program (latter compiled in {\tt INSTEP4}.

Most of the task program executables generated by {\tt INSTEP3} are the
same ones used in what is known as the ``Dirty Dozen Test'' or DDT
benchmark.  This test is used to regenerate images and UV datasets which
are then compared against a master set in order to certify an
installation, and provide timing information.  The master set is
available on request from the AIPS group, or via anonymous ftp.  For
further details, see \AIPS\ memo 73.  There are additional certification
tests used internally ({\tt VLAC}, {\tt VLAL}); contact the \AIPS\ group
for details on these.\medskip

\newsubsubsection{INSTEP4: Building Everything Else}

The fourth step of the installation process is much like {\tt INSTEP2}
and {\tt INSTEP3}, and it will attempt to compile and link all the
tasks in the \AIPS\ system.  As this includes about 302 separate
% @@@ check number
programs, this can easily take as long as, or longer than {\tt
INSTEP2}.\medskip

\newsubsubsection{Checklist}

This section contains a simple check list of the items covered in the
first two chapters.  If you make sure that you have completed all of
the below, you can save yourself a lot of trouble.  Note that most of
the files mentioned here are copied either from {\tt\$SYSUNIX}
({\tt\thisver/SYSTEM/UNIX}) or a vendor-specific area, \eg,
{\tt\thisver/SUN4/SYSTEM}.  Most of the items listed will be done by
{\tt INSTEP1}; items that definitely need to be done manually are in
{\it italics\/}.  \medskip

\item{$\bullet$} Convert critical shell scripts, including {\tt
        INSTEP1}, for Convex and Digital Ultrix systems only.  All files
        in {\tt\$INSUNIX}, and all {\tt *.SH} files in the
        architecture-specific system area are converted initially.
        Additional files copied to {\tt\$SYSLOCAL} also get converted
        later. 

\item{$\bullet$} Define {\tt\$HOST} (hostname), {\tt \$ARCH}
        (architecture), and {\tt \$SITE} (site name).  See item on
        {\tt HOSTS.LIST} below.  If an old {\tt INSTEP1.STARTED} file
        from a previous installation is found, {\tt\$SITE} and
        {\tt\$AIPS\_ROOT} may be extracted from it.

\item{$\bullet$} If Architecture is new, create {\tt \thisver/\$ARCH}
        directory and make {\tt LIBR}, {\tt LOAD}, {\tt MEMORY}, {\tt
        PREP}, and {\tt SYSTEM} areas.  Also make {\tt\$SYSLOCAL}
        which is {\tt \thisver/\$ARCH/SYSTEM/\$SITE}.

\item{$\bullet$} Copy subset of files in {\tt\$SYSUNIX} to the new
        {\tt\$SYSLOCAL}.  If {\tt\thisver/\$ARCH/SYSTEM} already
        existed, copy all files from there to {\tt\$SYSLOCAL} also.
        Convert some for ConvexOS and Ultrix shells.

\item{$\bullet$} Copy some {\tt\$SYSUNIX} files to the {\tt\$AIPS\_ROOT}
        area (offer to save older versions already there).  Run {\tt 
        AIPSROOT.DEFINE}.  {\it Insert a \/{\tt source LOGIN.CSH} in the
        \/{\tt .login} file (or a \/{\tt .~./LOGIN.SH} in the \/{\tt
        .profile})}.  

\item{$\bullet$} Make a symbolic link in {\tt\$SYSLOCAL} to the {\tt
        START\_AIPS} shell script.  For Convex/Ultrix, offer to convert
        shell on this file.

\item{$\bullet$} Define the \AIPS\ versions in {\tt AIPSPATH.CSH} and
        {\tt AIPSPATH.SH} (both of these in {\tt\$AIPS\_ROOT}).

\item{$\bullet$} Create {\tt\$NET0} ({\tt\$AIPS\_ROOT/DA00}, copy {\tt
        DADEVS.LIST} and {\tt NETSP} there, define this host's disks
        in these files, and make a directory here called {\tt\$HOST}. 

\item{$\bullet$} Copy the {\tt TPDEVS.LIST} file to {\tt\$NET0} and make
        entries in it for local tape drives.

\item{$\bullet$} Create the executables {\tt NEWEST}, {\tt
        PRINTENV} (maybe shell script for this) and {\tt PP.EXE} in
        {\tt\$SYSLOCAL}.

\item{$\bullet$} Make an entry in {\tt\$AIPS\_ROOT/HOSTS.LIST} for
        this host, and any of like architecture that will run \AIPS.

\item{$\bullet$} {\it For new ports, make sure all necessary local 
        directories have been created ({\tt \$QLOCAL}, {\tt \$YLOCAL},
        {\tt \$ZLOCAL})}.

\item{$\bullet$} {\it Check that the above local directories are defined
        as environment variables in both {\tt AIPSASSN.CSH} and {\tt
        .SH} in the site-specific section.  These files are in
        {\tt\$AIPS\_ROOT}.}

\item{$\bullet$} {\it New ports only: Check \/{\tt LIBR.DAT} and
        \/{\tt INCS.SH} in \/{\tt\$SYSLOCAL} and make sure you have
        included any new Q, Y, or Z areas local to your site, and the
        search path for included source text\/}.

\item{$\bullet$} {\it Edit the \/{\tt *OPT.SH} files in 
        \/{\tt\$SYSLOCAL} to reflect the host option syntax for
        compiling and linking.  Also edit {\tt \$SYSUNIX/FDEFAULT.SH}
        to set fortran options, and check {\tt \$SYSUNIX/OPTIMIZE.LIS}\/}.

\item{$\bullet$} Choose whether or not to use shared libraries on
        Sun/HP, and a separate set of debug libraries on Sun.

\item{$\bullet$} Make {\tt XAS} for X11 (windows) TV server if
        desired.

\item{$\bullet$} Make {\tt\$ARCH/INSTALL} and copy
        {\tt\$INSUNIX/INSTEP[234]} there.  Move there and get ready to
        start {\tt INSTEP2}.

\item{$\bullet$} {\it If there's an old version of\/ {\tt PRDEVS.SH} or
{\tt HOSTS.LIST\/}, merge them into the new versions.}

\item{$\bullet$} {\it Check the \/{\bf Vendor Specific Notes} to see if
        there are any special action items for your system\/}.
\medskip

\newsubsection{``Logicals'' or Environment Variables}

Throughout this document, \AIPS\ directories will often be referred to
as {\it logicals\/}; this term may be a bit confusing.  It originates
from the earlier VMS port of AIPS where extensive use was made of
``logical names''.  These are implemented as environment variables
under Unix.  In addition to pointing at source code directories, they
may also point at data areas, tape drives, TV display and graphics
devices.\medskip

\newsubsection{Directory Structure}

The directory structure of AIPS is descriped in considerable detail in
the AIPS programmers manual {\it Going \AIPS\/}, Appendix A.  A version
of this in La\TeX\ format may be found in
{\tt\$DOCTXT/APPENDIXA.TEX}\footnote*{\eightpoint printed copies are
                                        available from the AIPS Group in
                                        Charlottesville}.
For versions of \AIPS\ after {\tt 15APR91}, some of this structure has
been revised to allow for multiple hosts and architectures sharing the
same directory tree.

At NRAO, multiple (dated) versions of \AIPS\ need to exist side by side,
so we have adopted a scheme where the date of a given version (\eg, {\tt
\thisver}) is encoded in the directory under which that version is kept.
Under each such directory are (at least) the following:\medskip

\vbox{\settabs
\+\quad\quad X &SYSTEM\quad &\cr
\+&AIPS         & AIPS main programs and subroutines\cr
\+&APL          & Applications programs and subroutines\cr
\+&DOC          & Documentation area \cr
\+&HELP         & Help/Explain/Input files for tasks, verbs, \etc \cr
\+&HIST         & Code Management history files \cr
\+&INC          & Include files\cr
\+&Q            & Array Processor (or Pseudo-AP) tasks and routines\cr
\+&QY           & Tasks, routines that depend on both AP and TV \cr
\+&RUN          & Area for standard procedure files (DDT for example) \cr
\+&SYSTEM       & System and Machine specific files \cr
\+&Y            & TV-specific tasks and routines \cr
}\medskip

\noindent In addition, there are (as of \thisver) the following
architecture-specific areas for which the \AIPS\ group has performed
or received ports (at some point in time):\medskip

\vbox{\settabs
\+\quad\quad X &IBM3090\quad &\cr
\+&ALLN         & Alliant Systems\cr
\+&CRI          & Cray Research, Incorporated (UniCos)\cr
\+&CVEX         & Convex Systems\cr
\+&DEC          & Digital Equipment Corp; Ultrix on DecStations/DecSystems\cr
\+&HP           & Hewlett-Packard 9000 series 700 ``snake'' systems\cr
\+&IBM          & RS--6000 series systems running AIX\cr
\+&IBM3090      & Mainframes running AIX\cr
\+&SGI          & Silicon Graphics (not really a port)\cr
\+&SOL          & Sun-4 series (Sparc) running SunOS 5 ``Solaris''\cr
\+&SUN3         & Sun-3 series (Motorola 68020/68030) systems\cr
\+&SUN4         & Sun-4 series (Sparc) systems pre-``Solaris''\cr
}\medskip

\noindent (The IBM3090 port did not pass the DDT test for accuracy
due to the 370 class floating point format).  
% @@@ @@@ @@@ @@@ @@@ is this still true? @@@ @@@ @@@ @@@ @@@ @@@ @@@
Of all these, only CVEX, DEC, IBM, SOL, and SUN4 are actively
supported in-house by NRAO (\ie, we have these systems and they all
run \AIPS\ for us).  HP is supported via a guest account at an outside
site (you know who you are; we are grateful!) and has generally better
support than other non-in-house systems.  Dec ALPHA (OSF/1) will be
supported in the very near future.
% @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@
Under each of these directories there should be
the following architecture-specific (but host-independent)
areas:\medskip

\vbox{\settabs
\+\quad\quad X &TEMPLATE\quad &\cr
\+&ERRORS       & Has host-specific areas; not much used anymore \cr
\+&INSTALL      & for performing the installation; INSTEP2,3,4, logs, 
                  \etc\cr
\+&LIBR         & Object (random archive) Libraries (in subdirectories)
                  \cr
\+&LOAD         & Binary (executable) files \cr
\+&MEMORY       & POPS memory file (first, POPS-number-independent,
                  part)\cr 
\+&PREP         & for staging of temporary and listing files in
                  compilation\cr 
\+&SYSTEM       & Arch-specific shell scripts, \etc; SYSTEM/\$SITE is 
                  your \$SYSLOCAL area.\cr
\+&TEMPLATE     & Only for network installation; template system DA00
                  files.\cr 
}\medskip

\newsubsection{Software Overhaul and Data Compatibility prior to 15APR89}

The \AIPS\ application software was ``overhauled'' for the {\tt
15OCT89} release.  All Fortran language software was changed to use a
pre-processor and to appear to the compiler as ANSI-standard Fortran
77.  This should make little difference to the installation of \AIPS.
However, no user data files from previous releases may be used by the
{\tt 15OCT89} and later releases.  All data must be read into {\tt
15OCT89} and later releases from FITS disk or tape or from other
supported tape formats.  Also, all programs written by users at
non-NRAO sites prior to this release need to be overhauled.  Software
to assist in this is provided; see the file {\tt\$DOCTXT/F77CONV.TXT}
for more details.\medskip

\newsubsection{AIPS Versions}

Up to recently, the \AIPS\ system has been evolving continuously at
NRAO, and three separate versions of \AIPS\ were separately maintained
({\tt OLD}, {\tt NEW} and {\tt TST}).  Periodically, a new {\tt TST}
version was created, the previous {\tt TST} version redefined as {\tt
NEW}, and the previous {\tt NEW} version redefined as {\tt OLD}.  This
{\tt OLD} version was then distributed to non-NRAO sites as required,
after testing of the installation process and verification of
correctness via the DDT tests\footnote\dag{\eightpoint ``Dirty Dozen
Tests'', see \aips\ memo 73}.  This process, known internally as the
{\it quarterly update\/}, was (surprise) usually done every three
months.

The \AIPS\ systems are referred to by the date of their intended
release, \eg, {\tt \thisver}.  NRAO staff are encouraged to use {\tt
TST} since this is the version subject to the most changes.  For
visitors, we have recommend {\tt NEW}, which was changed only to fix
serious bugs.  In this way, the code we ultimately ship to customers
has been rather thoroughly exercised, at least on NRAO systems.

% @@@ @@@ @@@ @@@ @@@ Update as needed @@@ @@@ @@@ @@@ @@@ @@@ @@@ 
However, with the development of the \AIPS++ system imminent, the {\tt
15APR91} release was the last one issued on a quarterly basis.  NRAO is
issuing {\tt 15JUL93} and will issue at least one more version of
``old'' \AIPS, ({\tt 15JAN94}), but this will not be on the traditional
quarterly basis.  The decision to make further releases will be made as
needed.  Contact the \aips\ group at {\tt aipsmail@nrao.edu} for more
details.
% @@@ @@@ @@@ @@@ @@@ Update as needed @@@ @@@ @@@ @@@ @@@ @@@ @@@ 

Because of the large amount of disk space needed for each version (see
requirements below) most sites maintain only one release (\ie, {\tt
OLD=NEW=TST}).  However, some sites have found it very useful to bring
up a new version of AIPS defined that coexists with an older,
established version.  After the new version checks out, the old version
can be mothballed on tape.  However, versions of \AIPS\ starting at {\tt
15APR92} are incompatible with earlier versions and it is difficult if
not impossible to make them coexist.  Too many system-level directories
are in different places.  Also, as the {\tt HOSTS.LIST} format has
changed in {\tt 15JUL93}, it may be difficult to have it and older
versions {\tt 15OCT92} or {\tt 15APR92} coexist with it.\medskip

\newsubsection{Disk Space Requirements}

A full-blown \AIPS\ system with no files removed for disk space saving
will take anywhere from 135 Megabytes to close to 300, depending on
several factors.  Most of this is tied up in the binaries (executable
files, the {\tt *.EXE} files in the {\tt\$LOAD} area).  The source
code as distributed on tapes takes up considerably less, and in fact
the compressed {\tt tar} file for {\tt \thisver} when obtained via
internet ftp is only slightly more
% @@@ @@@ @@@ @@@ @@@ check it and fix! @@@ @@@ @@@ @@@ @@@ @@@
than 17 Megabytes, or 11 Megabytes for the version compressed with 
the GNU {\tt gzip} utility.  The uncompressed source code is about 57
megabytes, including the {\tt TEXT} area for documentation, \etc.
% @@@ @@@ @@@ @@@ @@@ check it and fix! @@@ @@@ @@@ @@@ @@@ @@@
\medskip

\newsubsubsection{Text Files}

The disk space required for all of the text files that come on the
installation tape is roughly 49 Mbytes.  However, quite a bit of this
is not required on disk for a Unix \AIPS\ installation.  The specific
areas that can be removed after the installation is complete
are:\medskip

{\ndot {\tt TEXT/PUBL}, Documentation}
{\ndot {\tt \thisver/DOC}, More documentation (over 4 Megabytes)}
{\ndot {\tt \thisver/HIST}, \AIPS\ history, code management, \etc}
{\ndot {\tt \thisver/SYSTEM/VMS}, VAX/VMS system code}
{\ndot {\tt \thisver/APL/DEV/VMS}, VAX/VMS Z-routines}
{\ndot {\tt \thisver/Q/DEV/FPS}, FPS Array Processor Hardware code}
{\ndot {\tt \thisver/Y/DEV/???}, Any TV's you don't have, \eg, 
        {\tt DEA} for DeAnza hardware (TV servers use {\tt
        SS})\medskip}\medskip

\noindent If you are really tight on disk space, you can always back up
the source code to tape and remove all fortran, c, and include
files:\medskip

\example{\%~find \thisver\ -name '*.FOR' -exec rm -f $\{\}\ \backslash$;}
\medskip

\noindent and similarly for the files {\tt *.C}, {\tt *.INC}, and any
{\tt *.o} or {\tt *.f} or {\tt *.c} files in {\tt \$PREP} left over
from your installation.  The VMS areas can be safely removed if you are
not going to use them (all-unix sites won't).

In addition, you can remove any {\tt \thisver/???/SYSTEM} areas that
do not match any of your systems and also any non-native Z routine
areas under {\tt \thisver/APL/DEV/}.  Do {\it not\/} attempt to remove
the {\tt HELP} and {\tt RUN} areas; they are necessary for the correct
functioning of AIPS.  \medskip

\newsubsubsection{Binary Files}

The disk space required for binary files (object libraries, program
object modules, executable modules and system files) can be much greater
than for the code.  It will depend on architectire, and other details
such as the options used when \AIPS\ is built, \eg, whether the {\tt -g}
option to include symbolic debugging information is used.  The bulk of
most \AIPS\ systems is taken up by the contents of the {\tt \$LOAD}
area, i.e. the executable or binary program files.  It is possible to
use the unix utility {\tt strip} to remove the symbolic debugging
information from the files {\tt \$LOAD/*.EXE}; how much space this saves
will be system dependent.  It will probably be significant, however.

There are some tasks (\AIPS ese for executables or binaries) that you
will probably never use or need.  Make sure you have a backup before
you delete anything, however!

There is now support for the use of \AIPS-specific shared libraries on
Sun and HP architectures.  This is achieved through special versions of
{\tt \$LIBR} and {\tt\$LINK} in the {\tt \thisver/\$ARCH/SYSTEM} area
(which will be copied to your {\tt\$SYSLOCAL} by the installation
procedure).  The file {\tt USESHARED} must exist in {\tt\$SYSLOCAL} in
order to turn this option on; if it does not exist, the procedures will
not create \AIPS\ shared libraries.  The first stage of the
installation, INSTEP1, will query you on whether you want this feature
or not.  Another file, {\tt NOSHARE.LIS}, must also exist.  It specifies
any programs that should {\it not} be built with shared libraries.

For shared libraries, the resultant size of the binaries is on the order
of 90 Megabytes.  If the system is built without using shared libraries
and in debug mode, the size will be closer to 300 Megabytes.  Stripping
these, and/or building without debug flags, will reduce the size
somewhat but nowhere near the former figure.  There is a trade-off,
however; if you use shared libraries, you will most likely need to
increase the swap space on your systems.  At NRAO, we typically have
between 70 and 105 megabytes of swap.  In a site with many workstations,
the savings from smaller binaries in {\tt\$LOAD} are more than offset by
the amount of disk space that has to be reserved for swap on each
system.\medskip

\newsubsection{System Directories}

The directory {\tt \thisver/SYSTEM/UNIX} contain procedures and
definitions for the programming, maintenance and execution of AIPS for
Unix (the older VMS command files are in {\tt \thisver/SYSTEM/VMS}).  In
addition, there are directories under {\tt \thisver/\$ARCH/SYSTEM} for
different flavors (architectures) of Unix.  Currently these include
Alliant ({\tt ALLN}), Convex ({\tt CVEX}), DECstation Ultrix/MIPS ({\tt
DEC}), HP 9000/7xx ({\tt HP}), IBM RS/6000 AIX ({\tt IBM}), IBM 3090 AIX
({\tt IBM3090}), Cray ({\tt CRI}), and Sun ({\tt SUN3} and {\tt SUN4},
virtually identical, and {\tt SOL} for SunOS 5.x).  Example: the Sun4
(sparc) area is {\tt \thisver/SUN4/SYSTEM}.  There are plans in the near
future for DEC-Alpha OSF/1 ({\tt ALPHA}), and there is an area for
Silicon Graphics ({\tt SGI}), but it has not undergone a formal port.

The installation procedure will require that a subdirectory be created
for site specific procedures and definitions.  This will be {\tt
\thisver/\$ARCH/SYSTEM/\$SITE} and is usually referenced by its
``logical'', {\tt\$SYSLOCAL}.  There is also a directory called {\tt
\thisver/SYSTEM/UNIX/INSTALL} where the Unix version of the 
\AIPS\ install procedures are stored.  Part of the procedure is to copy
the files {\tt INSTEP2}, {\tt INSTEP3}, and {\tt INSTEP4} from here to a
site- and architecture-specific area {\tt \thisver/\$ARCH/INSTALL}
(creating the directory if needed) from which much of the installation
for each architecture will be performed.  Procedures for performing
nightly updates (\ie, the so called ``midnight'' jobs) from the master
\AIPS\ site in Charlottesville are stored in {\tt
\thisver/SYSTEM/UNIX/UPDATE} and its subdirectories; you will most 
likely not need these.

There are in addition two directories under the {\tt CVEX} area of
Unix System code.  These reflect the different system requirements at
NRAO's two Convex sites (even though one of these is gone). \medskip

\newsubsection{Device and Machine Specific Code}

The \AIPS\ conventions for code that is of necessity specific to a
given system or device is that the routine name begin with one of the
letters Q, Y or Z.  The Q routines were originally for array processor
specific code, such as for Floating Point System's AP120 model; these
routines have evolved into pseudo-AP routines on general systems, and
into highly vectorizable machine specific code on computers that
support vector operations, such as Convex.  These routines are generally
good candidates for high levels of optimization.

The Y routines indicate dependence on a specific TV or image display
device.  This includes not only older devices such as the International
Imaging Systems (IIS) Model 70, 75 and IVAS, but more recently (and most
popular anymore) the \AIPS\ TV servers.  Since the {\tt 15APR92}
release, all TV servers use the same set of Y routines ({\tt\$YSS}).
NRAO has standardized on the XAS TV server which now has all the
functionality of the Sun-specific XVSS.  Considerable effort has been
expended to make XAS as fast as possible.  XAS should run on most, if
not all, X-window displays (for X11 Releases 4 and 5 and variants
thereof, including OpenWindows).

Finally, the Z routines contain code that is dependent on the
specifics of different operating systems and different hardware.

These routines will be described in some detail in the sections that
follow. \medskip

\newsubsubsection{Z-routines}

The directory {\tt \thisver/APL/DEV} and its subdirectories contain
operating system, architecture and device dependent source code.
Generic forms that are the same for all systems are kept in {\tt
\thisver/APL/DEV} itself, and as you descend the directory structure,
the more specific the code becomes: Unix versus VMS, Bell (probably
better if it were called SYSV) versus Berkeley Unix, Convex versus Sun,
and so on.  At the top level, some routines don't do more than call
other routines in the same area or lower levels, or some combination
thereof, and are all Fortran.
% @@@ There's at least one in C in 15JAN94...
In the Unix sub-tree, most of the routines are written in C.\medskip

\newsubsubsection{Y-routines}

Subroutines that deal only with the specifics of \AIPS\ TV display, or
Y-routines, are found in area {\tt \thisver/Y/DEV} and its
subdirectories.  The range of ``TV'' types covered ranges from the TV
servers that use windowing systems such as X11, to the older dedicated
image display devices from several different vendors.  There is also an
area containing stubbed versions ({\tt \thisver/Y/DEV/STUB}) for
installations with no TV or windowing system.  The most generic forms
are kept in {\tt \thisver/Y/DEV} with more specific code in the
subdirectories.  Current TV devices include:\medskip\medskip

\vbox{
{\ndot {\tt SS}: AIPS TV Servers, XAS, XVSS, or SSS; XAS over the network}
{\ndot {\tt IIS}: International Imaging Systems, Models 70 and 75
                (in separate subdirectories)}
{\ndot {\tt IVAS}: The IIS IVAS device}
{\ndot {\tt DEA}: DeAnza (Gould) TV displays}
{\ndot {\tt STUB}: Stubbed routines that do nothing}
{\ndot {\tt VTV}: Virtual TV, ``TV by wire'' over the network\medskip}\medskip
}

\noindent The {\tt VTV} area is only used if you use {\tt TVMON}; this
is not necessary if you follow the standard network scenario used by
\AIPS~ for multiple TV servers.  The IIS Model 70 actually formed the
model for the TV servers and their capabilities. \medskip

\newsubsubsection{Q-routines}

The most computationally intensive portion of the \AIPS\ source code has
been isolated into what we call Q-routines and resides in the
subdirectories of {\tt \thisver/Q/DEV}.  Originally, this was intended
to support code specific to array processors, such as those from FPS
(Floating Point Systems), but with the preponderance of fast,
inexpensive RISC processors, the attractiveness of such add-on devices
has diminished considerably.  

In the early days of the ``VAX'' era, a pseudo array processor library
({\tt \thisver/Q/DEV/PSAP}) was developed for installations with no
array processor (\ie, most).  These routines emulate an array processor
in memory.  Since then, they have become the standard for most Unix
installations.  Under the {\tt PSAP} area are directories for systems
that have vector capability such as Alliant and Convex.  There are also
other directories here for machine-specific code, usually modified for
reasons of precision or similar considerations.

As previously stated, there are a large number of directories that can
be safely removed.  For both the {\tt DEV/} and {\tt SYSTEM/} areas, you
need only keep the subdirectories relevant to your installation.
However, if you are porting \AIPS\ to a new operating system or
architecture, or dealing with a new windowing system or an unusual
computing architecture (\eg, multiprocessing or parallel), you may
find the code in some of the existing directories useful as
models.\medskip

\newsubsection{Programming and Execution Tools}

The directory {\tt \$SYSUNIX} contains many procedures and some programs
used in Unix \AIPS\ programming and operation.  Most of these are
written to be as generic as possible.  However, some may require
modification for a new port.  Most of these require that the
\AIPS\ programming environment variables be defined prior to their use.
This is normally done via the {\tt \$CDOLD}, {\tt \$CDNEW} or {\tt
\$CDTST} commands, whichever is appropriate; these are described later
in this document and essentially redefine on the fly the many
environment variables that point to the different directories.  For most
installations, this will only be done once, typically in the {\tt
.login} or {\tt .profile} file.

There are several other system directories in {\tt
\thisver/\$ARCH/SYSTEM} as already mentioned.  These may contain
architecture-specific versions of the procedures and/or programs.  {\tt
INSTEP1} will copy the most appropriate of these to a new {\tt
\$SYSLOCAL} area in a rational way, using {\tt
\thisver/\$ARCH/SYS\-TEM/\$SITE} as the directory for {\tt \$SYSLOCAL}.
If none is appropriate (\ie, you are doing a new port), choose the
closest or if necessary the generic {\tt \$SYSUNIX} files.  The couple
of C programs and the preprocessor (in the {\tt \$SYSUNIX} area,
currently {\tt NEWEST.C}, {\tt PRINTENV.C}, and {\tt PP.FOR}) will need
to be compiled and linked as part of the installation.  Again, this will
be attempted by the {\tt INSTEP1} procedure but you may have to re-do it
if it fails.  Note that if the Unix {\tt printenv} command is available
on your system, you can copy the {\tt SUN4} version of the {\tt
PRINTENV} shell script; this simply calls the Unix command.  A shell
script is automatically used on Suns, Dec/Ultrix, Convex, HP, and IBM
RS6000/AIX systems.

Rather detailed descriptions of each procedure/program and
its usage can be found as comments in the text.  Also, most are
designed to give you a synopsis of their usage if invoked incorrectly
(\eg, no arguments).  A brief description of each is given here.
First the procedures or shell scripts that will be copied to the
{\tt\$AIPS\_ROOT} area:\medskip

{\parindent=3.7cm
\item{\tt AIPS.BOOT\quad}  Commands to run at boot tim: starting {\tt
                TPMON} daemons; should be run under the {\tt aips}
                account, not {\tt root} (or at least make {\tt TPMON}
                set-uid to {\tt aips})
\item{\tt AIPSASSN.SH\quad} and {\tt .CSH}: Local overrides, 
                reserved-tv/message-terminal definitions 
\item{\tt AIPSPATH.SH\quad} and {\tt .CSH}: Path setting, version names
\item{\tt AIPSROOT.DEFINE\quad} Sets {\tt AIPS\_ROOT} in other scripts
                via {\tt sed} (used by {\tt INSTEP1})
\item{\tt HOSTS.SH\quad} and {\tt .CSH}: Define {\tt HOST}, {\tt SITE}, 
                {\tt ARCH} (uses {\tt \$AIPS\_ROOT/HOSTS.LIST})
\item{\tt INSTEP1\quad} Will be a symbolic link to the {\tt\$INSUNIX/INSTEP1}
                procedure. 
\item{\tt INSTEP1.STARTED\quad} holds definitions of {\tt SITE} and {\tt
                AIPS\_ROOT} from one run of {\tt INSTEP1} to the next.
                Also stores the \AIPS\ version, e.g. \thisver.
\item{\tt LOGIN.SH\quad} and {\tt .CSH}:  \AIPS\ setup to be called on
                login (calls {\tt HOSTS.*}, {\tt AIPSPATH.*} and {\tt
                AIPSASSN.*} in that order) 
\item{\tt PRDEVS.SH\quad} Defines names, types, descriptions of local
                printers (new for \thisver: all big print jobs can be caught
                and sent to a designated printer)
\item{\tt START\_AIPS\quad}  Starts up the \AIPS\ program (via {\tt
                AIPSEXEC}) 
\item{\tt START\_TPSERVERS\quad}  Starts up {\tt TPMON} daemons for 
                remote tapes (may be called via {\tt rsh})
\item{\tt START\_TVSERVERS\quad}  Starts up XAS or SSS (may be called 
                via {\tt rsh})
\item{\tt TVALT\quad}  Figure out your windowing system, if any
\item{\tt TVDEVS.SH\quad}  Define names of hardware TV's such as IIS,
                alternate load areas if any.
\medskip

\noindent The following shell scripts are always copied to
{\tt\$SYSLOCAL}:\medskip

\item{\tt CDVER.SH\quad} and {\tt .CSH}: Change \AIPS\ version and
                programming environment variables (called by 
                {\tt\$CDTST}, \etc)
\item{\tt CCOPTS.SH\quad} Define name and options for C compiler
\item{\tt ASOPTS.SH\quad} Define name and options for Assembler (if needed)
\item{\tt LDOPTS.SH\quad} Define how to link-edit, usually with Fortran command
\item{\tt INCS.SH\quad} Defines search path for {\tt INCLUDE} files for preprocessor
\medskip

\noindent And the following scripts are available in the generic
{\tt\$SYSUNIX} area:\medskip

\item{\tt AIPSCC\quad}   Runs local C compiler (uses {\tt
                         \$SYSLOCAL/CCOPTS.SH}). 
\item{\tt AIPSEXEC\quad} The script that actually starts \AIPS\ (called
                         by {\tt START\_AIPS}).
\item{\tt ALLRSH\quad}   Do a command on all \AIPS\ hosts via {\tt rsh}.
\item{\tt AREAS\quad}    (Re)Makes {\tt AREAS.SH} and {\tt .CSH} from
                         {\tt\$SYSAIPS/AREAS.DAT}.
\item{\tt AS\quad}       Runs local Assembler (uses {\tt
                         \$SYSLOCAL/ASOPTS.SH}). 
\item{\tt BATER\quad}    Starts up program BATER (\AIPS\ in batch mode).
\item{\tt COMLNK\quad}   Runs Compiler and Linker with appropriate
                         object libraries (uses {\tt SEARCH}, {\tt 
                         PP}, {\tt FC} and {\tt LINK}).  There are {\tt
                         SUN4} and {\tt SOL} versions of this script.
\item{\tt COMRPL\quad}   Runs Compiler only, not for main programs (uses
                         {\tt SEARCH}, {\tt PP}, {\tt AS} or {\tt CC} or
                         {\tt FC}). There are {\tt SUN4} and {\tt SOL}
                         versions of this script. 
\item{\tt CREADIR\quad}  Creates empty \AIPS\ directory tree based on
                         {\tt\$SYSAIPS/AREAS.DAT}.
\item{\tt DADEVS.SH\quad} Defines data disks from files {\tt NETSP} and
                         {\tt DADEVS.LIST} in {\tt\$NET0} 
\item{\tt DASETUP\quad}  Sets up data disks with aipsmgr/aipsuser 
                         ownership and permissions.  Not used at NRAO so
                         may need some work. 
\item{\tt DATOUCH\quad}  List data directories, causing them to be
                         mounted (if the automounter is used). 
\item{\tt FC\quad}       Runs local Fortran compiler (uses {\tt
                         FDEFAULT.SH} and {\tt FCLEVEL.SH} in
                         {\tt\$SYSUNIX}).  
\item{\tt FCLEVEL.SH\quad} Reads file {\tt OPTIMIZE.LIS} from {\tt
                         \$SYSLOCAL} or {\tt\$SYSUNIX} and determines
                         debug, optimize level for the program or
                         subroutine being compiled. 
\item{\tt FDEFAULT.SH\quad} Defines default compiler names, switches,
                         and optimization levels for fortran 
                         compilations ({\bf Needs filled in for new
                         ports}) 
\item{\tt LIBR\quad}     Builds/updates object libraries in {\tt
                         \$LIBR/*/} (uses {\tt \$SYSLOCAL/LIBR.DAT}).
\item{\tt LIBS\quad}     Generates library list needed for programs in a
                         given source code area; uses {\tt
                         \$SYSLOCAL/LIBR.DAT} (versions also in Sun, Sol
                         and HP local areas).
\item{\tt LINK\quad}     Runs local Linker (loader); uses {\tt
                         \$SYSLOCAL/LIBR.DAT} and {\tt LIBR} (versions
                         also in Sun, Sol, IBM, HP local areas). 
\item{\tt MAKEAT\quad}   generates file containing list of filenames
                         (uses {\tt \$SYSLOCAL/LIBR.DAT}).
\item{\tt PP\quad}       preprocess source code (for fortran, calls
                         {\tt \$SYSLOCAL/PP.EXE}).  Local version for
                         IBM. 
\item{\tt PWD\quad}      Show current working directory without 
                         automounter (\eg, {\tt /tmp\_mnt}) directory;
                         may fail for some configurations.  Uses
                         {\tt\$PWD}. 
\item{\tt RUN\quad}      Run programs other than {\tt AIPS} or {\tt
                         BATER}.  New for {\tt 15JUL93}: calls {\tt
                         DADEVS.SH}. 
\item{\tt SEARCH\quad}   find appropriate version of a module (calls
                         {\tt NEWEST}, uses files
                         {\tt\$SYSLOCAL/SEA\-RCH*.DAT}). 
\item{\tt SSSERVERS\quad} Start up Sunview version of \AIPS\ TV server.
                         (Sunview is 
\item{\tt STARTPMON\quad} Start up {\tt TPMON} daemon(s).  Called by
                         {\tt START\_TPSERVERS}.
\item{\tt SYSETUP\quad}  Initial or incremental setup of host system
                         areas.  Handy when adding a new \AIPS\ host.
\item{\tt TPDEVS.SH\quad} New for {\tt 15JUL93}: Defines tape names,
                         uses table {\tt \$NET0/TPDEVS.LIST}
\item{\tt WHICH\quad}    \AIPS\ wrapper for ``find'' command.
\item{\tt WHOUSES\quad}  Shows which libraries use a given routine.
                         Takes a {\it long\/} time.
\item{\tt XASERVERS\quad} Start up the XAS X11 \AIPS\ TV server.
\item{\tt ZDICC2\quad}   NRAO-specific Dicomed film recorder spooler.
\item{\tt ZLASCL\quad}   Sends graphics output to appropriate printer.
\item{\tt ZLPCL2\quad}   Sends text output to appropriate printer.
% @@@ probably not complete.  Check.  Also take out 15JUL93 refs...
\medskip

\noindent And there are three programs in {\tt\$SYSUNIX}:\medskip

\item{\tt NEWEST.C\quad} Find newest file in argument list
\item{\tt PP.FOR\quad} The Fortran Preprocessor for \aips
\item{\tt PRINTENV.C\quad} {copy of Berkeley {\tt printenv} for systems
                lacking it or systems where it can't handle the $200+$ 
                names used by \AIPS.}
}
\medskip

\noindent 
The scheme for figuring out what compiler optimize level and what debug
setting to use {\it for Fortran compilations only\/} differs from that
used for assembler (if any), C language, and links.  The compiler
settings are preset to some reasonable defaults for the architectures
the NRAO \AIPS\ group has had direct experience with (Convex,
DEC/Ultrix, HP 9000/7xx, IBM RS/6000, Solaris and Sun) in the {\tt
FDEFAULT.SH} file, and the optimize settings for different areas and/or
programs and/or subroutines are set in a text file {\tt OPTIMIZE.LIS}.
If you are porting to a new architecture, you need to study these files
and make appropriate entries in them.

\noindent
At least two of these three programs obviously have to be built prior
to using any of the other tools, \ie, before most of the installation
can proceed.  The {\tt INSTEP1} procedure will copy them to the {\tt
\$SYSLOCAL} area and try to build them there; if an existing {\tt
printenv} is found, a shell script will be built for {\tt PRINTENV}.
The rest of the tools assume that is where the binaries for these
programs will be found.\medskip

\newsection{Step by Step Installation Instructions}

\newsubsection{The AIPS Account}

In an installation where many people will be using \AIPS, it may be a
good idea to have a dedicated account to run \AIPS\ from.  A good
name for the account is {\tt aips} but this is not essential.  The
default login shell may be the Bourne shell, C shell, Korn shell, or
the GNU BASH shell, although the C shell is most commonly used.  There
have been some reports of problems with tcsh during the installation
process.  On the other hand, for a single user installation, creating
such an account is not necessary.

At NRAO, most \AIPS\ usage is conducted from this account, but AIPS
may also be executed or programmed from private accounts {\it provided
the \AIPS\ system directories are set up with the proper group and/or
world permissions\/}.  If you want everyone at your site to be able to
run \AIPS\ from their own account, you should consider setting up a new
group (\eg, {\tt aipsuser}) and adding people who are going to run
\AIPS\ to it; it need not be anyone's primary group.  As the only
alternative to this is to set the protection on memory file, system, and
data areas to world read/write ({\it this is a security risk and NRAO
does NOT recommend it\/}), you are {\bf strongly} encouraged to consider
the {\tt aipsuser} group approach..

If you have a large \AIPS\ installation, you may want to mimic NRAO's
approach and have an {\tt aipsmgr} account for the \AIPS\ manager, in
addition to the {\tt aips} account.  In that case, the {\tt aipsmgr}
account should be the owner of all files and directories associated with
\AIPS, and {\tt aipsmgr}, the {\tt aips} account (if any), and anyone
else wanting to run \AIPS\ should belong to the {\tt aipsuser} group
mentioned in the previous paragraph.  Then the various data and system
directories ({\tt\$NET0/*}, {\tt \$DATA\_ROOT/*}) should be set:\medskip

{\ndot to be owned by group {\tt aipsuser}, and} 
{\ndot {\tt chmod g+ws}, \ie, with group write enabled and the
        ``setgid'' bit on.\medskip}\medskip

\noindent The ``setgid'' bit causes files created in these areas to have
the same group ownership and permissions as the directories.  However,
note that for this ``setgid'' scheme to work, any disks that are
NFS-mounted should be mounted by the client with the {\tt grpid} option,
if available.  At NRAO, we mount \AIPS\ data disks with options {\tt
rw,grpid,hard,intr}.

The {\tt\$SYSUNIX/DASETUP} file has the details on how NRAO sets up
\AIPS-related accounts and ownership and protection on the important
directories.  It cannot be used if you use an automounter {\tt DATA}
map --- the {\tt root} account will probably have to set up the areas
and the automounter maps --- but is useful for setting up local disks.
Note that this script has not been used for some time at NRAO.

The \AIPS\ startup script by default sets the protection mask to {\tt
umask 002} which allows the owner, and members of the same group, read
and write access to the files and directories.  This is set in
{\tt\$SYSUNIX/AIPSEXEC}.  The {\tt ZCREA2.C} routine also sets a
protection mask {\tt PMASK} but this is wide open ({\tt 0666}).
Change these as needed but try to avoid inconsistencies.

The source and binary files for an \AIPS\ system may need to reside in
one partition.  The {\tt mv} command is used by the installation and
programming tools, and some older systems do not support moving files
across partitions.  Most modern systems tolerate this, however.  In a
network environment where more than one architecture is supported in the
same \AIPS\ directory tree, it may in fact be desirable to put the
architecture-specific areas on different machines.  As an example,
suppose you have a network of Suns, some using SUN4 and one using SOL.
You would then want the {\tt\$AIPS\_ROOT/\thisver/SOL} directory to be
on the Solaris machine itself; this can be easily accomplished via a
symbolic link:\medskip

\example{cd \$AIPS\_VERSION}
\example{mv SOL SOL.OLD}
\example{ln -s SOL /home/foo/aips/SOL}\medskip

\noindent Then you create the {\tt LIBR}, {\tt LOAD}, {\tt SYSTEM}, {\tt
INSTALL}, {\tt PREP}, {\tt TEMPLATE} and {\tt SYSTEM/\$SITE} areas in
the new directory on the solaris host and move stuff into them from the
old one.  

Another advantage of this scheme is that it reduces the disk space
requirements on the partition where the aips directory tree lives.

In addition to being quite compute intensive, \AIPS\ is also {\it
very\/} I/O intensive in many cases; the task {\tt UVSRT} is a good
example.  If you are concerned about performance, you may want to set up
the data areas on multiple disks and controllers in order to establish
as many independent data paths as possible and thereby reduce I/O
contention.  \AIPS\ is designed to distribute its scratch files over as
many of these disks as have sufficient space.  Also, if you follow this
path, you should remind your users to spread their data evenly across
these many disks so that this scratch file distribution can work
efficiently.\medskip

\newsubsection{Loading the Installation Tape}

In the distributed, networking world that most \AIPS\ users now live
in, there are many ways of loading an \AIPS\ distribution onto disk.
These include:\medskip

\item{$\bullet$} Reading from a Local Tape Drive
\item{$\bullet$} Reading from a Remote Tape Drive
\item{$\bullet$} Using the Internet and {\tt ftp}
\medskip

\noindent Each of these possibilities requires a slightly different
recipe in order to unpack the archive and get the sources in their
correct directories.  In all cases, however, you should be using the
\ttaips\ account (or the account --- perhaps your own --- that will be
the primary user of \AIPS) and should be in its login area or wherever
the root of the \ttaips\ directory tree will be.  

The {\tt tar} operation (see below) will create four files in this area:
a directory containing the \AIPS\ code ({\tt\thisver}), a second
directory for some ancillary files ({\tt TEXT}), a third directory for
future use ({\tt BIN}), and a symbolic link to the {\tt INSTEP1}
procedure for convenience.  The first directory contains a hierarchy
with subdirectories {\tt AIPS}, {\tt APL}, {\tt DOC}, {\tt HELP}, {\tt
HIST}, {\tt INC}, {\tt Q}, {\tt QY}, {\tt RUN}, {\tt SYSTEM} and {\tt
Y}.  In addition, architecture-specific directories already exist for
several systems.  There is also an empty {\tt UPDATE} area; ignore it
(we forgot to remove it).  You may want to remove any old {\tt TEXT}
area, unless you modified files in it (unlikely) in which case you
should move it prior to loading the tape or tar file.
\medskip

\newsubsubsection{Local Tape Drive}

This is the simplest to deal with.  Insert the distribution tape into
the drive and use {\tt tar} to unpack it:\medskip

\example{\% tar xvf /dev/nrst0}\medskip

\noindent This would do the trick on most Sun systems with the tape
drive on a SCSI bus; use {\tt /dev/nrmt0} for VMEbus based tape drives.


The tape drive names will be different on other systems:\medskip

\item{$\bullet$} On a Convex, you would use {\tt tpmount} to select a
                 tape drive (then {\tt tpqueue} and/or {\tt tpq} to see
                 which one it is if you have many), and use the device
                 name reported by the command. 
\item{$\bullet$} On the IBM RS/6000 series, the device name would be
                 {\tt /dev/rmt<n>} where {\tt <n>} is a number (0, 1,
                 2$\dots$).  Use {\tt smit tapes} on IBM's to see which 
                 tape drive is which.
\item{$\bullet$} On DecStations and Alpha systems, the device name might
                 be {\tt /dev/rmt<n>h} or {\tt /dev/nrmt<n>l} (for high
                 or low density).
\item{$\bullet$} For SunOS 5.x and HP systems, the device name would be
                 {\tt /dev/rmt/<n>ln} where {\tt <n>} is as above.
\medskip

\noindent If in doubt about tape names, check your system documentation
or ask your system administrator.  ``There is no such thing as a
standard Unix tape drive'' --- the author.

The {\tt v} flag in the argument to {\tt tar} is not necessary; it
just provides feedback on the unpacking by listing each file as it is
extracted from the tape archive.\medskip

\newsubsubsection{Remote Tape Drive}

This situation is a little trickier to do.  Some implementations of {\tt
tar} will support reading remote tape drives (\eg, GnuTar) but most will
not.  However, use of a few standard Unix utilities can do the trick:
\medskip

\example{\%  rsh tapehost 'dd if=/dev/rmt0 bs=20b' | tar xvBfb - 20}
\medskip

\noindent You use the appropriate network name of the remote system
with tape drive in place of {\tt tapehost}, and the correct tape
device name as argument to {\tt if=}, of course.  This command should
be given on the destination machine.  You can safely omit the {\tt v}
option if you do not want the verbose listing of all files as they are
unpacked.  On HP systems, use {\tt remsh} instead of {\tt rsh}.

Before you try this, check your local system documentation to make
sure the syntax of the {\tt dd} and {\tt tar} commands is as expected.
In the example above, the {\tt bs=20b} forces blocking in 20-block
chunks (\ie, 10k bytes), and the five letters after {\tt tar} force
extraction, verbose, force multiple reads per block if needed, specify
output filename, and specify blocking factor in that order.  The minus
following that tells it to use the standard input and the 20 is the
argument for {\tt b}, the blocking factor.

You should also make sure that the {\tt rsh} command will work; check
your documentation (manual pages, whatever) on {\tt rhosts} and/or
check your {\tt .rhosts} file in your login area.\medskip

\newsubsubsection{Internet and ftp}

NRAO now encourages sites to obtain \AIPS\ via {\tt ftp} over the
internet.  If interested in this means of getting \AIPS, contact the
\AIPS\ group at Charlottesville for details (send e-mail to {\tt
aipsmail@nrao.edu}).  Please note this is {\it not\/} ``anonymous''
ftp and a password is necessary; you will be provided with one when
you make arrangements to obtain \AIPS\ in this way.

If you used {\tt ftp} to get the \AIPS\ system, you will have ended
up with either one large compressed {\tt tar} file ({\tt
\thisver.tar.Z}), or many smaller ones ({\tt\thisver.tar.Z.01}, {\tt
.02}, \etc).  If you have many small files, just {\tt cat} them together
into one:\medskip

\example{\% cat \thisver.tar.Z.* >\thisver.tar.Z}\medskip

\noindent Once you have the large file, uncompress it and extract the
files from it as you would from a tape:\medskip

\example{\% uncompress \thisver.tar.Z}\medskip

\noindent or, if you got the gzipped version, use:\medskip

\example{\% gunzip \thisver.tar.gz}\medskip

\noindent Then:\medskip

\example{\% tar xvf \thisver.tar}
\noindent or:\medskip
\example{\% zcat \thisver.tar.Z | tar xvf -}\medskip

\noindent The second form can be used if your system has {\tt zcat}
(most do; some versions even work with gzipped files).  Once you are
confident that the archive unpacked correctly, you can remove the {\tt
.tar*} files from disk.  It wouldn't hurt to back them up first.\medskip

\newsubsection{Installation Step 1}

This step involves some editing, moving, and general setup.  There is a
shell script that will perform most, but not all, of the setup for you.
It will prompt you with a set of questions.  If you are porting 
\AIPS\ to a new system, it will still attempt to do most of the setup,
although more work will be required on your part after the procedure
finishes.

The rest of this section will describe the individual questions the
{\tt INSTEP1} procedure asks, what they mean, and what they actually
do ``behind the scenes''.  The intent here is to give the reader a
fuller understanding of what is necessary for an \AIPS\ port or
installation than the shorter {\it \AIPS\ Unix Installation
Summary\/}.

To get started, you should first make sure you are in the ``aips root''
area.  This should be where you unpacked the tape archive (regardless of
how you got it), and you should see the four files {\tt\thisver}, {\tt
TEXT}, {\tt BIN}, and {\tt INSTEP1}.  The directory you are in will be
defined by environment variable {\tt\$AIPS\_ROOT}.  

If for some reason the {\tt INSTEP1} symbolic link is {\it not\/}
there, just type:\medskip

\example{\%~ln -s \thisver/SYSTEM/UNIX/INSTALL/INSTEP1 INSTEP1}\medskip

\noindent It may be necessary on systems that do not support
symbolic links to actually copy the file.

Once you have reviewed the rest of this subsection, you then
start the procedure (just type its name, \ie, {\tt INSTEP1}).  The
shell script itself is fairly well commented and is divided into about
17 sections, each one numbered in the comments and (roughly)
corresponding to one of the following sections.\medskip

\newsubsubsection{Preliminaries: Convex, Ultrix Bourne Shells}

During the recent enhancements of the various shell scripts, certain
features, notably the use of shell functions, have been added that are
not available in some of the more primitive versions of the Bourne
shell.  The systems known to be affected are Convex (OS9) and Ultrix
(4.3) systems.

The {\tt INSTEP1} procedure has the smarts to figure this out, and will
attempt, on Ultrix and Convex systems, to convert certain critical shell
scripts to an alternative shell.  For Ultrix, this is {\tt /bin/sh5}
(the System V shell), and on Convex it is {\tt /bin/ksh} (the Korn
shell).  INSTEP1 writes a little shell script called {\tt sh-cvt} which
it places in the aips root area which simply adds a line at the
beginning of each shell script it operates on, e.g. {\tt \#!/bin/sh5}.

The following files will be converted.  As the first of these is {\tt
INSTEP1} itself, the process may get stuck after some or all of the
converting.  In the installation testing, this occured on ConvexOS but
all scripts apparently got converted anyway and a restart
succeeded.\medskip 

\item{1)} The installation scripts {\tt INSTEP1} through {\tt INSTEP4};
\item{2)} All {\tt *.SH} files in the {\tt CVEX/SYSTEM} or {\tt
          DEC/SYSTEM} areas\medskip

\noindent Later on, the {\tt sh-cvt} script will be used on additional
files. \medskip

\newsubsubsection{Protection Mask}

The procedure will now ask if the current {\tt umask} or protection
mask is acceptable:\medskip

\example{INSTEP1: The current umask (protection mask) is 0022}
\example{INSTEP1: (check the man page on umask if you don't know what
                  it is)} 
\example{INSTEP1: is this umask acceptable?}\medskip

\noindent You should answer with either {\tt Y} or {\tt
N}\footnote*{\eightpoint For all yes/no questions, the script will
   convert whatever you type to uppercase and only look at the first
   character.}.  
In general, restricting access to the files that will be created is a
good idea; the mask indicated above will deny anyone except the owner
of the files write access.  Alternately, the {\tt umask} can be set to
0002 which allows members of the same group write access.  Note that
\AIPS\ requires write access to some files (\eg, memory, system files
in {\tt \$DA00}, and of course data areas).  The setting of 0000 will
allow any user read and write access but this is not recommended for
security reasons.  (The bourne shell {\tt umask} command gives 4
digits unlike the c-shell equivalent, and some shells only show two
figures but they are the relevant two).

It is better to have all \AIPS\ users be a member of a group, \eg, {\tt
aipsuser} as outlined earlier in this document.  The Installation script
will attempt to set the ``set-gid'' bit on certain directories and set
the protection on them so that all members of the primary group of the
{\tt aips} account (or whatever account is doing the installation) will
have privilege to write to files created in them.  \medskip

\newsubsubsection{Host Name}

The installation script will attempt to find the Unix {\tt hostname}
command in your default path.  If not found, it checks if {\tt uname} is
available.  If neither of these is found, it will query you for the
hostname.  In this case you should enter the simple hostname with no
domain, \eg, {\tt orangutan} instead of {\tt orangutan.cv.nrao.edu}.  It
converts the string to uppercase and (where {\tt hostname} or {\tt
uname} is used) strips off any domain part of the hostname.

The name is kept in the environment variable {\tt HOME}.  It will be
defined by the file {\tt LOGIN.CSH} or {\tt LOGIN.SH} after the
procedure finishes.  

If your site uses fully qualified hostnames, e.g. the {\tt uname -n}
command (or {\tt hostname} on systems where {\tt uname} is not available
such as Convex) prints out {\tt orangutan.cv.nrao.edu} instead of just
{\tt orangutan}, you need to make sure there is an alias for your system
in the {\tt /etc/hosts} table, \eg:\medskip

\example{192.33.115.11\ \ \ \ orangutan.cv.nrao.edu orangutan}\medskip

\noindent Here, the second mention of ``orangutan'' is the alias.  Some
networks have the {\tt /etc/hosts} file distributed via NIS (yellow
pages) and others use the Domain Name Service (DNS).  Contact your
system administrator and find out where this information can be set and
have the alias inserted if it's not there already.  One way to find out
is to try, \eg, {\tt telnet orangutan} (replace with your hostname,
minus any domain) and see if it works.  If it does, then you don't need
to worry.  If not, have it fixed, otherwise the \AIPS\ TV, remote tapes,
and graphics and message servers will not work.  (There is a call in the
Z routines to {\tt gethostbyname()} and \ttaips\ will feed the
unqualified host name into it).

\newsubsubsection{Site Name}

The site name is used to set up certain site-wide files and
directories; when prompted, you should enter a string that can be a
valid filename.  At NRAO we use {\tt NRAOCV}, {\tt NRAOAOC}, {\tt
NRAOVLA}, and {\tt NRAOGB}.  The string you enter will be converted to
uppercase.  The site name is kept in environment variable {\tt SITE}.
This is stored in the file {\tt INSTEP1.STARTED} so you do not have to
enter it again if you interrupt the installation procedure and start
over.  If an old {\tt INSTEP1.STARTED} is found, the site name will ---
at your approval --- be picked up from it by {\tt INSTEP1}.
\medskip

\newsubsubsection{Architecture}

There is no general way of telling what type of computer a unix shell
script is running on, but {\tt INSTEP1} looks for a few telltale
hints.  The aim here is to get an environment variable {\tt ARCH}
defined, and create a directory of the same name, \ie, {\tt
\thisver/\$ARCH}, to hold subdirectories for binaries, libraries, and
the like.  The current known architectures are: 
\medskip % @@@ make sure it's updated!

{\parindent=2.5cm
\item{\tt SUN3\quad}    Sun Microsystems (Motorola 680x0), SunOS 4.x
                        (Solaris 1.x) 
\item{\tt SUN4\quad}    Sun Microsystems (Sparc), SunOS 4 (Solaris 1.x)
\item{\tt SOL\quad}     Sun Microsystems (Sparc), SunOS 5 (Solaris 2.x)
\item{\tt CVEX\quad}    Convex, ConvexOS
\item{\tt DEC\quad}     Digital Equipment Corporation DECstation/system,
                        Ultrix 4.3/DEC Fortran
\item{\tt IBM\quad}     IBM RS--6000 series, AIX 3.1 and 3.2
\item{\tt IBM3090\quad} IBM Mainframes, AIX
\item{\tt HP\quad}      Hewlett-Packard 9000/700 systems, HP-UX 8 or 9
\item{\tt ALLN\quad}    Alliant (Concentrix)
\item{\tt CRI\quad}     Cray Research, Inc. (UniCOS)
\item{\tt SGI\quad}     Silicon Graphics (SG--Irix)
\medskip
}

\noindent The {\tt INSTEP1} script can usually discriminate among all
of these, except for the last three.  The way it does so is somewhat
convoluted, but goes something like this.  First it sees if {\tt
/usr/bin/arch} exists.  If so, it sets {\tt ARCH} to the output
(uppercased) of this command.  This covers Sun3 and Sun4.  On Solaris
the directory is {\tt /usr/ucb/arch} so it looks there next.  If neither
of these are found, it checks for a directory {\tt /usr/convex} which is
usually only to be found on (surprise) Convex systems.  If we're still
batting zero, it looks for the {\tt uname} command, first in {\tt /bin}
and then in {\tt /usr/bin}.  If either of these exist, they are used to
get the architecture.

After all this, if the {\tt ARCH} environment variable is {\tt AIX}, it
is changed to {\tt IBM} and if it is {\tt ULTRIX}, it is converted to
{\tt DEC}.  If it's {\tt HP-UX} it is converted to {\tt HP}.  The script
then asks for confirmation on what it has found, or tells you that it is
an ``unexpected system'' or perhaps a ``system not familiar to this
script''.  If the script just plain guessed wrong, you can correct it at
this point (let us know so we can investigate and figure out where we
went wrong too).

If you are doing a new port of \AIPS, enter
{\tt NO} at this point.  Then the script will ask for the name of the
architecture, and if it's new, you will be asked to confirm.  Once you
confirm, here is what it does:\medskip

{\ndot Creates {\tt\thisver/\$ARCH} directory, makes it setgid}
{\ndot Creates subdirectories {\tt ERRORS}, {\tt ERRORS/\$HOST}, 
        {\tt LIBR} (for object libraries), {\tt LOAD} (for binaries),
        {\tt MEMORY} (for the \AIPS\ memory file), {\tt PREP}, {\tt
        SYSTEM} (system-specific shell scripts), and {\tt TEMPLATE} to
        hold templates of system setup files} 
{\ndot Makes all these subdirectories ``setgid''.\medskip}\medskip

\newsubsubsection{Create various Directories}

If you did not specify a new system, this step just checks that all
the directories mentioned in the previous section (on architecture)
exist.  If any don't, they are created and setgid as
appropriate.\medskip 

\newsubsubsection{Create SYSLOCAL Area}

This area is an architecture-specific area and so should exist
under {\tt\thisver/\$ARCH/}.  The {\tt INSTEP1} script will create a
directory using your site name, \ie~ {\tt\thisver/\$ARCH/SYSTEM/\$SITE}.
Thus it is the same for all hosts of the same type in a given
installation.  At the NRAOCV site, the {\tt\$SYSLOCAL} areas for the
different architectures are the same as {\tt\$SYSSUN}, {\tt\$SYSSOL},
and {\tt\$SYSIBM} just to make sure they work (otherwise we'd have two
copies and the ones in our local area would not get shipped).

Once the directory exists, any files (not directories) in the
{\tt\thisver/\$ARCH/SYSTEM} area are copied to it.  Then a set of
standard files are copied to this new {\tt SYSLOCAL} area from the
{\tt SYSUNIX} area {\tt\thisver/SYSTEM/UNIX}, only if they don't
already exist in the {\tt SYSLOCAL} area.  In this way, all the
necessary shell scripts and setup files are copied, but any
architecture-specific versions get to override the generic ones. 

The files conditionally copied from {\tt SYSUNIX} are: {\tt CDVER.CSH}
and {\tt .SH}, {\tt CCOPTS.SH}, {\tt LDOPTS.SH}, {\tt ASOPTS.SH}, {\tt
INCS.SH}, and {\tt LIBR.DAT}.  Some of these will need to be edited
after {\tt INSTEP1} completes, at least for new ports of \AIPS.

For Convex and DEC--Ultrix installations, some additional files are
converted to more reasonable shells at this point (see above).  These
are: any {\tt *.SH} files, and copies of {\tt AIPSEXEC}, {\tt LIBR}, and
{\tt LINK} from {\tt \$SYSUNIX}.

If you had modified any {\tt\$SYSLOCAL} files in a previous release of
\AIPS\ (either {\tt 15OCT92} or {\tt 15APR92}, not any earlier), you
should now look at differences between the distributed version and your
customized version.  Also, if you had added any purely local files, you
might want to copy them to the new {\tt\$SYSLOCAL} area.
\medskip

\newsubsubsection{Define the ``aips root'' Area}

As already mentioned, this area should ideally be the login area of the
{\tt aips} account.  It should also be the directory you were in when
you started {\tt INSTEP1} and where the {\tt\thisver} directory is
located.  If the environment variable {\tt AIPS\_ROOT} is not defined,
you will be given the name of the current directory (with {\tt
/tmp\_mnt} stripped in case you are using the automounter) and asked to
confirm if this is the AIPS\_ROOT area.  If not, you will be asked to
enter the directory name for it.  If what you tell it is not a
directory, you will be given the option of creating one.

If the {\tt AIPS\_ROOT} variable is already defined, it just asks you
if it is correct.  Again, you are given the option of re-entering it
(but not creating it) if it's wrong. 

Finally, the script will stop dead in its tracks if there is a period
(dot, ``.'') in the {\tt\$AIPS\_ROOT} pathname.  Such a name, \eg, {\tt
/u/j.doe/aips}, will cause serious grief to {\tt INSTEP2} and it's far
simpler to either rename the directory or pick one without a dot in its
name. 
\medskip

\newsubsubsection{Copy system files to the aips root}

There are currently 17 % @@@ count'em and check!!!  See INSTEP1
                       % script, stage 7 for the list.  
files that will be copied to the {\tt AIPS\_ROOT} area from
{\tt\$SYSUNIX}.  Most of these are bourne shell scripts; a few are c
shell scripts for users with the c-shell as their login shell, and one
is just a configuration file.  The script will copy them all to the
{\tt \$AIPS\_ROOT} area and set the execute bit on for the copied
version and off for the {\tt SYSUNIX} version.

If any of these files already exists in the {\tt\$AIPS\_ROOT} area, you
will be asked for each one, \eg:\medskip

\example{Warning!  Old PRDEVS.SH found in AIPS\_ROOT}
\example{Some older versions of AIPS\_ROOT files may be}
\example{incompatible with this version of AIPS, especially}
\example{if they predate the 15APR92 release}\medskip

\noindent For something like {\tt PRDEVS.SH} as in the above example,
you definitely want to preserve the old one (in the {\tt 15JUL93}
release, this file has some significant changes so you can't just use
the old version).  Also for {\tt HOSTS.LIST}, the format has changed in
{\tt 15JUL93}.  Some of the shell scripts will no doubt have changes and
you should compare old and new versions sometime before releasing 
\AIPS\ on your users. 
% @@@ Dates above...

The files copied are:\medskip

{\settabs 3 \columns \tt
\+ AIPSASSN.CSH         & HOSTS.SH      & START\_TPSERVERS \cr
\+ AIPSASSN.SH          & HOSTS.LIST    & START\_TVSERVERS \cr
\+ AIPSPATH.CSH         & LOGIN.CSH     & TVALT            \cr
\+ AIPSPATH.SH          & LOGIN.SH      & TVDEVS.SH        \cr
\+ AIPSROOT.DEFINE      & PRDEVS.SH     & AIPS.BOOT        \cr
\+ HOSTS.CSH            & START\_AIPS   &  \cr
}\medskip

Whereas before you were advised to create a file or symbolic link in
{\tt /usr/local/bin}, now the script will automatically make a symbolic
link in the {\tt\$SYSLOCAL} area called ``{\tt aips}'' that points at
the version of {\tt START\_AIPS} in {\tt\$AIPS\_ROOT}.  You may want to
make an additional one called ``{\tt AIPS}'' for those users who like to
work in upper case.

Finally, for DEC/Ultrix and Convex systems, you will be asked if you
want to shell-convert the {\tt \$AIPS\_ROOT/START\_AIPS} script.  If you
are only planning on having this installation support this one
(whichever) architecture, go ahead.  Otherwise (\eg, a mixed environment
of Suns and Convex) you should most likely copy the {\tt START\_AIPS}
file to all the relevant {\tt\$SYSLOCAL} areas, and run {\tt sh-cvt} on
the Convex or DEC version only.
% @@@ make this different next time; do it automatically.

\newsubsubsection{Run AIPSROOT.DEFINE}

This shell script will set the value of the {\tt AIPS\_ROOT}
environment variable automatically in all of the shell scripts that
need it.  If you do not specify the directory name for {\tt
AIPS\_ROOT} as an argument when you run the script, it prompts for the
name.  {\tt INSTEP1} will provide the name you already entered.
\medskip

\newsubsubsection{Set AIPS Version Names}

The standard shell scripts can accomodate up to three simultaneous
versions of \AIPS.  These are usually referred to as {\tt OLD}, {\tt
NEW}, and {\tt TST} and reflect NRAO's internal setup.  There will be
environment variables declared in the {\tt AIPSPATH.*} files that match
these names against actual versions of \AIPS\ (\eg, {\tt\thisver}).  The
{\tt INSTEP1} script first scans the {\tt AIPSPATH.SH} file to see what
the existing definitions are, prints these out and asks if these are
what the installer wants.  If you enter {\tt NO}, you will then be asked
what they should be.

For most sites, all three versions should be the same; this is the
default as shipped.  However, be warned that versions of \AIPS\ starting
with {\tt 15APR92} are {\bf incompatible} with earlier versions (\ie,
{\tt 15APR91} or earlier).  You should not attempt to mix them; memory
and other files will be in the wrong places and the {\tt\$CDTST}, \etc,
version-changing commands will not work if you do mix them.  There are
other incompatibilities, though these are more to do with the data and
techniques as opposed to system-type differences.  Check the recent 
\AIPS letters for details.

Once you have entered the revised version names, the script puts these
names back into both {\tt AIPSPATH.SH} and {\tt AIPSPATH.CSH}. \medskip

\newsubsubsection{Make DA00 (system file) Area}

Prior to {\tt 15APR92}, the \AIPS\ data areas had names like {\tt
DA00}, {\tt DA01}, and so on.  The first one was reserved for system
files, and the other ones were used almost exclusively for data files.
Having the system file area in the same scheme as the data areas often
led to some confusion.  

The system file area is of necessity host-specific, so the environment
variable {\tt\$DA00} now points to a directory {\tt
\$AIPS\_ROOT/DA00/\$HOST}.  Each host in your \AIPS\ network will have
its own private area like this.  The {\tt INSTEP1} script will also
allow group-write on the {\tt\$AIPS\_ROOT/DA00} and {\tt\$DA00} areas
as well as setting the ``setgid'' bit (this forces the
directory's group-ownership on files created in the directories).

The network scheme relies on the {\tt\$DA00} subdirectories for all
hosts being in the same directory, as various files will be hard
linked across them.  See the description of {\tt SYSETUP} later in
this document.  Also see the note in the next section %%% @@@ make
                                                      %%% sure it's
                                                      %%% still there!
on NFS mounts and the {\tt grpid} option.
\medskip

\newsubsubsection{Set up Disks (directories) for this host}

Since the {\tt 15APR92} release of \AIPS, the data areas are
by default organized so that they all reside under a single directory
called the {\tt DATA\_ROOT}.  On NRAO systems this is typically {\tt
/DATA}.  The convention for disks is that they take the (uppercase)
name of the host followed by an underscore and a number.  So on a host
{\tt lemur}, for example, the first two disks would be {\tt
/DATA/LEMUR\_1} and {\tt /DATA/LEMUR\_2}.  The reason for this change
in naming is to enable the \AIPS\ user to select disks from different
host machines at startup.

For most installations, the desired setup will be to make this area
something like {\tt\$AIPS\_ROOT/\-DATA/} and set up the data directories or
``disks'' as symbolic links pointing to existing \AIPS\ data areas.  The
{\tt INSTEP1} script now supports this and assumes you will want to take
this approach.

If your \AIPS\ ``network'' is only going to comprise one machine, you
can of course customize the files that specify data areas in any way
that you please.  If you plan on having a small network, then you can
either arrange to have the disks actually mounted --- presumably using
the Network File System or NFS --- on {\tt\$DATA\_ROOT/\$HOST\_n} (where
{\tt n} is 1, 2, 3, $\dots$) in the {\tt /etc/fstab} or {\tt
/etc/filesystems} or equivalent (see your systems administrator for more
details on these files), or you can simply insert symbolic links in the
{\tt\$DATA\_ROOT} area that point to the real disks, as described above.

However, if your \AIPS\ network is going to be in any way large (more
than 3 machines), then you will probably save yourself and your
systems administrator some work by using the {\tt automount} facility
available on most unix systems.  At NRAO, we have set up an
automounter ``DATA'' indirect map that greatly simplifies accessing a
large number of differently named AIPS data areas.  Here is a portion
of it: \medskip

\example{GORILLA\_1 -rw,grpid,hard,intr gorilla:/gorilla/aips/GORILLA\_1}
\example{GORILLA\_2 -rw,grpid,hard,intr gorilla:/gorilla/aips/GORILLA\_2}
\example{GORILLA\_3 -rw,grpid,hard,intr gorilla:/gorilla\_2/GORILLA\_3}
\medskip

\noindent and the DATA entry in the {\tt auto.master} map is:\medskip

\example{/DATA auto.DATA         -rw,grpid,hard,intr}

\noindent This shows that three disks from host {\tt gorilla} are
accessible from any machine using these automounter files (which we
distribute via NIS/YP) as {\tt /DATA/GORILLA\_1}, and so on.  Two of
these are on the same physical partition and are separated purely for
the owner's logistical use (different projects, \etc).  Note the {\tt
grpid} option above; it is essential in order to make the ``setgid'' bit
work correctly.

Systems that NRAO has used this automounter scheme successfully with
include: Sun3, Sun4, IBM RS/6000 (AIX 3.2, does {\it not\/} work for
version 3.1) Convex, DecStation (Mips/Ultrix 4.0, 4.3, and
Alpha/OSF--1).  It is possible to use a hybrid scheme with most systems
using the {\tt DATA} automounter map and some using explicit NFS mounts
at boot time, but it is preferable to have most systems using the
automounter.

The {\tt INSTEP1} procedure will ask for the name of the {\tt
DATA\_ROOT} area.  It will only ask for this the first time it is run.
The definition you enter will be inserted in {\tt AIPSASSN.CSH} and {\tt
AIPSASSN.SH}.  If the directory {\tt DATA\_ROOT} points to does not
exist, it offers to create it for you.  {\it Do not let it create this
directory if you plan on using the automounter\/}, as root privileges
may be required for that.

Then, if required, {\tt INSTEP1} copies the {\tt DADEVS.LIST} and {\tt
NETSP} files from {\tt\$SYSUNIX} to the {\tt\$NET0}) area (actually
{\tt\$AIPS\_ROOT/DA00}), and checks the latter file to see if this host
already has disks defined.  If not, it asks how many disks are to be
added for this host, and asks you to confirm the name of each one.  You
can elect to change any or all of the default names at this stage.

For each ``disk'', it first asks if you want to make it a symbolic link
to another directory.  If you do, you will be prompted for the name of
the directory the symlink should point at.  This can be quite useful if
you have existing \AIPS\ user data areas that you want to make
accessible.  Do {\it not\/} make a reference to an old {\tt DA00} area
from {\tt 15APR91} or earlier; that is a system file area and has no
user data.  

If you elect not to make a symbolic link, it offers to create the
directory if necessary, and will then automatically create the (empty
but {\it absolutely necessary\/}) {\tt SPACE} file in each one.

After all ``disks'' have been entered, you are encouraged by the {\tt
INSTEP1} procedure to inspect the two files mentioned in the last
paragraph.  The {\tt NETSP} file overrides some system parameters
previously set via the {\tt RUN SETPAR} program, \ie, the
{\tt\$DA00/SPC00000;1} file.  The {\tt TIMDEST} limits and the
reservation system --- where certain \AIPS\ disks can be restricted to
certain users or set only for scratch use --- are controlled from the
single {\tt NETSP} file for your entire network of \AIPS\ hosts.  The
{\tt DADEVS.LIST} file is for indicating which disks are required and
which are optional, as well as for user disk selection at startup (on a
per-host basis, \ie, select a set of hosts and get all disks from those
hosts only).\medskip

\newsubsubsection{Fill in the Tape Drive Names}

In previous (recent) versions of \AIPS, the tape drive assignments were
made in a rather complicated manner by editing a pair of shell scripts
{\tt AIPSASSN.CSH} and {\tt AIPSASSN.SH}.  With the {\tt 15JUL93}
% @@@ re-edit this for 15JAN94
release, that is no longer necessary.  There is a single, site-wide file
{\tt TPDEVS.LIST} that holds definitions of \AIPS\ tape drives for all
hosts in your network.  As with the other list files, it is plain text
and automatically set up for you by {\tt INSTEP1}.  This file will live
alongside {\tt DADEVS.LIST} in the {\tt\$NET0} area.

There are three columns of information in this file.  The first has the
hostname where the tape drive resides, in uppercase (no domain name,
just the simple host name).  The second contains the actual device name,
\eg: {\tt /dev/nrst0}.  The third (and subsequent columns) contains a
comment which is printed out at startup time.  Suppose on host {\tt
FROBB} (a sparc at SunOS 4.1.2) you had a single Exabyte tape drive on
the {\it SCSI\/} bus.  The line in {\tt TPDEVS.LIST} would look like:
\medskip

\example{FROBB\ \ \ \ \ \ /dev/nrst0\ \ \ \ \ \ \ \ Exabyte 8200}
\medskip

\noindent Then when you start up AIPS on frobb, you will see (after the
disk assignments message) another message:\medskip

\example{Tape assignments:}
\example{\ \ \ Tape 1 is Exabyte 8200 on FROBB}
\example{\ \ \ Tape 2 is REMOTE}
\example{\ \ \ Tape 3 is REMOTE}\medskip

\noindent The {\tt INSTEP1} procedure will prompt you for the tape names
on your local host only, and ask for a (human-readable) description of
each.  It is important that you read the machine-specific instructions
that {\tt INSTEP1} prints out, as most systems will overload the device
name with additional functionality.  

As an example, consider the attribute of {\it no-rewind on close\/}.
This is what forces the tape drivers {\it not\/} to rewind the tape
anytime the device is referenced in a {\tt close()} statement, and it is
essential that \AIPS\ use the correct device name to ensure this
(rewinding on close) does not happen.  On SunOS version 4, this is
ensured by prepending the name with the letter {\tt n}, \eg for the
first tape on a SCSI interface, the device name will be {\tt
/dev/nrst0} for the norewind device and this is the exact name you
should use.  However, on IBM RS--6000/AIX, the corresponding device name
would be {\tt /dev/rmt0.1}, {\bf but} you should use {\tt /dev/rmt0}
when entering the information in {\tt INSTEP1}.  The reason is that
\AIPS\ knows enough to add on the ``point-something'' for AIX device
names.

Here is a brief summary of the form of device names for known systems.
\medskip

\item{Sun4} {\tt /dev/nrst<x>} for SCSI devices, where you replace {\tt
            <x>} with $0, 1, 2, \dots, 7$ for the tape drive number.
            \AIPS\ will translate the number if higher density is
            desired; it is imperative that you enter the base number
            otherwise the density algorithm will get confused (not half
            as confused as you will though).  For Solaris 2 (SunOS 5),
            see Sol below. 
\item{Sun3} See Sun4 above.
\item{IBM}  {\tt /dev/rmt<x>} where {\tt <x>} is $0, 1, 2, \dots$ for
            the tape drive number.  Don't add the ``point--something'';
            \AIPS will do that.  The density selection {\it only\/}
            works for the standard rmt driver (\eg, third party drivers
            like {\tt wb} are not supported).
\item{CVEX} {\tt /dev/rmtxx} {\it literally\/}.  \AIPS\ will replace the
            {\t xx} with the appropriate numbers.  You must preserve the
            order, i.e. system tape drive zero must be \AIPS\ drive 1,
            system drive one is \AIPS\ drive two, \etc.
\item{DEC}  {\tt /dev/nrmt<x><d>} where {\tt <x>} is $0, 1, 2, \dots$
            for the tape drive number, and {\tt <d>} is the density: l
            for low, m for medium, h for high.  (This convention is used
            on Alpha/OSF--1 systems too).  Unfortunately the DEC tape
            routines do not perform density conversion on the device
            name, yet. 
\item{HP}   {\tt /dev/rmt/<x><d>nb} where {\tt <x>} is $0, 1, 2, \dots$,
            and {\tt <d>} is the density (l, m, h as for DEC).  The n is
            for norewind and the b is for Berkeley rules.  \AIPS\ will
            modify the {\tt <d>} according to the density desired on the
            fly.
\item{SOL}  {\tt /dev/rmt<x><d>n}, identical to HP except there is no
            ``b'' for Berkeley.  Again, \AIPS\ will modify {\tt <d>} on
            the fly depending on the density desired.
\medskip

\noindent The relevant code where the logic for the treatment of device
names can be found is {\tt ZMOUN2.C} in the various architectures.  If
you modify this code for your system, please let us have a copy of the
modified code along with a thorough description of your system (hardware
and operating system), tape controllers, tape drivers and the tape drive
itself.  Also remember that the rules for tape names and behaviour are
probably the least standardized thing in the Unix environment, and what
works for your drive may not work for someone else's. \medskip

\newsubsubsection{Make Preprocessor and other utility programs}

Before any programs, including the preprocessor, can be defined, the
procedure needs to know what the native Fortran and C compilers are on
the current host.  Its first guess is obtained from the {\tt
\$SYSLOCAL} file {\tt CCOPTS.SH} and the output of the {\tt\$SYSUNIX}
file {\tt FDEFAULT.SH}, which come preconfigured for several well-known
\AIPS\ architectures.  You will be asked to confirm if this guess is
correct or not.  For Sun3, Sun4, and Solaris--2 systems, if the C
compiler is not set to {\tt acc}, the script strongly urges you to
change it to this (ANSI compliant C compiler), as it is what NRAO now
uses in-house.

For new ports the first guesses at the compiler names may well be wrong.
If you enter {\tt NO}, it will ask you for the names of both compilers.
You can either enter the command name or the fully qualified path name,
\eg, {\tt f77} or {\tt /usr/lang/f77} on suns.  The latter form is
necessary if the compiler directory (in this case, {\tt /usr/lang}) is
not in your default path.  Note on Solaris--2, the compiler location is
in {\tt /opt/SUNWspro/bin}.

If you do not specify full pathnames for the compilers and they are not
in your default path, the {\tt INSTEP1} procedure will stop immediately.
You should either restart and specify the full pathnames, or modify your
{\tt PATH} to add the relevant area in your {\tt .login} or {\tt
.profile}, log in again, and restart.

There are currently three % @@@ make sure it still is true, NEWEST,
                          % PRINTENV, and PP.EXE
utility programs that need to be compiled before any of the 
\AIPS\ tools, including the compile and link scripts, can work.  These
are: \medskip

\item{1)} {\tt PRINTENV} to print out all environment variables;
\item{2)} {\tt NEWEST} to determine which of two files is newer; and
\item{3)} {\tt PP.EXE}, the Fortran pre-processor. \medskip

\noindent The first of these is only needed on systems that do not
have {\tt printenv}.  On all Suns, IBM RS/6000's, Convexes, HP's, and
DecStations, the {\tt INSTEP1} script will simply make {\tt PRINTENV}
a shell script that calls {\tt printenv}.  For all other systems, it
will copy the file {\tt\$SYSUNIX/PRINTENV.C} to
{\tt\$SYSLOCAL/printenv.c} and compile it.  The only qualifier on the
C compile command used is {\tt -o} to specify the output file.  You may
need to do this by hand if your {\tt printenv} command cannot handle
more than about 200 long (50--60 character) environment variables.  Most
systems can easily handle this load.

The second file is {\tt\$SYSUNIX/NEWEST.C} which again is copied (for
all architectures this time) to {\tt\$SYSLOCAL} as {\tt newest.c} and
compiled with the {\tt -o} qualifier to make {\tt NEWEST}.

Finally, the preprocessor source {\tt\$SYSUNIX/PP.FOR} is copied to
{\tt\$SYSLOCAL/pp.f} and a Z-routine to translate environment variables
{\tt\thisver/APL/DEV/UNIX/ZTRLOG.C} is also copied to the local area as
{\tt\$SYSLOCAL/ztrlog.c}.  The latter is compiled with the {\tt -c}
qualifier and a {\tt -I} reference to the \AIPS\ include area 
% @@@ omit for 15JAN94
(for the new --- in {\tt 15JUL93} --- {\tt AIPSPROTO.H})
% @@@ omit for 15JAN94
which should create {\tt ztrlog.o}.  On IBM RS/6000 and HP systems, the
trailing underscore in the declaration of {\tt ztrlog.c} is removed
before the compilation.  On Cray systems, this is also done and the
reference is converted to uppercase.  

Then the preprocessor itself is compiled and linked in one step,
including the {\tt ztrlog.o} object file.  For IBM's, the {\tt -lc}
option is added to force the linker to use the C language version of
{\tt getenv()} instead of the fortran version.

If any of these fail, you will have to investigate the problem and
compile these programs by hand.  \medskip

\newsubsubsection{Shared and Debug Libraries}

New in the {\tt 15JUL93} version
% @@@ remove above for 15JAN94
is the option, in {\tt INSTEP1}, to choose whether you want to build
``shared'' or dynamic \AIPS\ libraries, and in addition whether you want
to build a second set of libraries that are compiled completely in debug
mode.  The shared option is only available on Sun3, Sun4, Solaris, and
HP systems, and the debug option is available on Sun3, Sun4, and
Solaris. 

The advantage of using shared libraries is that it reduces the size of
the binaries (executables, files in the {\tt LOAD} area) considerably.
Depending on your system, the total size of the binaries may go from
over 300 megabytes to less than 100.  However, there is a trade-off with
the amount of swap space you will need.  At NRAO we have found it
necessary to use anywhere from 70 to 110 megabytes on Suns for swap
space (more on larger systems like the Sparc10).  Obviously, if you have
to increase the amount of swap on many systems, you will end up using
more disk space than you will save by reducing the size of the binary
files.  Conversely, on a single system or an \AIPS\ network of two or
three systems, the savings may be worth it.

On HP--UX 9.01 it has been noted that using shared libraries seems to
cause fatal errors in critical parts of \AIPS.  However, on an older
version of the OS (8), the initial port was able to make use of shared
libraries with no apparent side effects.  Caution on the relatively new
HP port of \AIPS\ is recommended and you may want to stick with the
non-shared libraries.  

Note that even if you ask for the shared libraries, the regular
non-shared versions have to be built anyway, so all it really takes to
convert a given task from one to another is a relink.  The mechanism for
deciding whether or not to link against shared libraries is the presence
or absence of {\tt \$SYSLOCAL/USESHARED} (contents or size don't
matter).  Also, there is a list {\tt\$SYSLOCAL/NOSHARE.LIS} containing
simple (basenamed) filenames of programs that must {\it not\/} be linked
against the shared libraries.  You can always add to this list if you
find a task that does not behave well with shared libraries.

Finally, the key on whether or not to generate a debug set of libraries
is determined by the presence or absence of the file {\tt
\$SYSLOCAL/DOTWOBIN} (somewhat inappropriately named; should be called
dotwolib instead).  This option will not only generate a second set of
libraries under the {\tt LIBRDBG} directory parallel to the {\tt LIBR}
area, but it will also leave the preprocessed source code around in the
{\tt\$PREP} area too, as it is necessary for debugging purposes to have
access to the source code.  

You most likely will not need the debug libraries.  This feature is
useful at NRAO, and probably at other sites where active \AIPS\ code
development or modification or debugging is occuring.
\medskip

\newsubsubsection{Create HOSTS.LIST and/or add this host to it}

This file is the hub of the ``network'' scheme for \AIPS.  It lists, for
a given site, all the hosts that {\tt aips} and/or the \AIPS\ TV server
will run on, their architectures, and a brief half-line summary of what
the machine is.  
% @@@ modify as needed below
For the {\tt 15JUL93} version, there is a format change in this file,
but it {\it should\/} be backwards compatible.  In other words, using
the new format will be possible in most cases for {\tt 15OCT92} and {\tt
15APR92} versions if you want to use them as well as {\tt 15JUL93}.

As supplied, the file looks like this:\medskip

% @@@ insert latest one here if it's changed.
\fortran
AIPS hosts.  Spacing/position is significant for columns 1 and 2.  The
first item must be in column 1 and there must be exactly two spaces
between it and column 2.

Fields: 1 = "+"  host runs AIPS and can/will run a TV server (e.g. XAS),
            "-"  host is a TV server only (does not run AIPS), and
            "="  host is an X11 display terminal (does not run AIPS).
        2 = hostname, uppercase (NOT qualified, i.e. FOO, not FOO.EDU)
        3 = architecture (CVEX, IBM, SUN4, SUN3, HP, ALLN, CRI, IBM3090,
                          DEC, SGI, ...)
              Note: byte order and f.p. format MUST be identical on all.
        4 = Site.  Use same string for all your entries at one site.
        5 = Default server for X terminal (ignored for AIPS hosts, TV
              servers) 
        6 = description (for people and your own benefit).

SAMPLE SETUP FOLLOWS (you can delete any lines starting with "*", and
        use a "+" or "-" in column 1 instead)

1  2          3       4        5           6
*  GOLDY      CVEX    MYSITE   NONE        Convex 3800, Computer center
*  ZIPPY      IBM     MYSITE   NONE        IBM RS/6000-560, Astro lab
*  HAPPY      SUN4    MYSITE   NONE        Sun 4/75 color, gx accellator
*  OLDIE      SUN4    MYSITE   NONE        Sun ELC mono, TV server
*  OTHER      DEC     MYSITE   OLDIE       DecStn 3100 color, TV display
\endfortran\medskip

\noindent These five machine entries are of course fictitious and are
for illustration.  The asterisks in column 1 are present for the {\tt
INSTEP1} procedure to detect and remove.

When {\tt INSTEP1} is run for the first time, it checks the {\tt
HOSTS.LIST} file to see if the first machine above (``goldy'') is still
in place.  If so, it removes all entries that start with an asterisk.
Then for each host it is run on, it asks for a short description.  Then
it inserts a line representing that host in the file.

You will then be asked if you want to add entries here for other hosts
of the same architecture that you want to run \AIPS\ on.  The script
will continue to ask you for hosts and descriptions, inserting them in
the file, until you enter a blank line for a host.  While you do have
to re-run {\tt INSTEP1} on a sample machine of each architecture in
your \AIPS\ network, you do {\it not\/} need to do so for the
additional hosts of the same architecture.

After you have entered all \AIPS\ hosts for the specific architecture,
the {\tt INSTEP1} script will allow you to enter both TV servers and TV
display machines for \AIPS\ in the same manner as you entered the
regular hosts.  Here a ``TV server'' is a computer that will run the
{\tt XAS} image display for \AIPS, but with the intent of displaying it
elsewhere.  Conversely, a ``TV display'' host is one that receives this
display.  Using the {\tt tv=} command line option of the 
\ttaips\ command, you can in fact redirect the display anywhere, \ie,
you are not restricted by the display hosts you put in this file.
However, it is useful to be able to specify, for a given TV display
host, which other host is its {\it default\/} TV server.  Then when the
startup scripts determine (from {\tt who am i} or variants thereof) what
system you are actually sitting in front of, they can automatically have
{\tt XAS} start up on the correct server host.

\medskip

\newsubsubsection{Make the X11 TV Server (XAS)}

You can choose to have {\tt INSTEP1} attempt to make the default
\AIPS\ TV server --- XAS --- for you.  This TV server should work on
all X11R4 and X11R5 based windowing systems (including OpenWindows
versions 2 and 3, DecWindows, Motif, and twm/tvtwm).

If you answer {\tt YES}, the script will unpack the archive in a
directory {\tt\thisver/Y/SERVERS/XAS}.  Then it will look for the X11
include and library areas.  It attempts to do so in a consistent way, by
first checking for the file {\tt lib/libX11.a} in a given area, and if
it finds that, double-checking to make sure {\tt include/X11/Xlib.h} is
in the same area.  It does this for:\medskip

{\ndot {\tt /usr/local}}
{\ndot {\tt /usr}}
{\ndot {\tt /local/X11R5} (NRAO-specific area)}
{\ndot {\tt \$OPENWINHOME} (looks in {\tt include}, not {\tt
        include/X11}}
{\ndot {\tt /usr/openwin} (likewise)\medskip}

\medskip\noindent The {\tt\$OPENWINHOME} and {\tt /usr/openwin} tests
are only done if the architecture is Sun3 or Sun4, and the former is
skipped if the environment variable is not defined.  Obviously this
set of areas could probably be more comprehensive, but complexity of the
script is a concern too.  If you think it guesses things incorrectly,
you may just want to skip this section and do it yourself by hand later.

If all this fails and it still cannot find the include and/or library
areas for X11, it will prompt you for them.  You should enter the {\it
exact} directory locations of the include and library directories for
your X11 installation.  

XAS can take advantage of the ``MIT shared memory'' option available in
some X11 servers.  {\tt INSTEP1} attempts to find the file {\tt
X11/extensions/XShm.h} in the include area previously specified.  If it
finds this, it automatically makes XAS with the shared memory code
enabled.  Otherwise it makes it without.  If the wrong choice is made,
you will have to edit the {\tt Makefile} in the {\tt\$YSERV/XAS/}
directory to change {\tt SHMOPT} to either blank or {\tt -DUSE\_SHM},
and then type {\tt make} to remake it.

% @@@ remove for 15JAN94

In older releases, the shared memory option in {\tt XAS} literally ate
up shared memory everytime it was killed until the system had to be
rebooted.  Also it was not smart enough to know not to attempt to use
shared memory when the X server and X display are on different hosts
(that's what the shared memory is for; it lets the server and display
clients communicate faster, and you can't do that if the processes are
not running on the same host).  All that is changed for {\tt 15JUL93}
and it now releases the shared memory areas cleanly when it is shut
down, and refuses to use shared memory on remote displays.

Once the include and library areas are known to {\tt INSTEP1}, it then
modifies the {\tt Makefile} to insert the revised definitions of {\tt
INCDIRS} and {\tt LIBDIRS}.  It also modifies {\tt SHMOPT} if necessary.
Then it defines {\tt LOAD} (the ultimate destination of the {\tt XAS}
binary) and calls {\tt make}.  This may or may not work.  If not, don't
panic.  Just look at the error messages, try to see if it's looking at
the correct library and include file area, and if all else fails,
contact an X11 guru.  If you can't find one, send email to {\tt
aipsmail@nrao.edu} and we'll do what we can to help.  However, a failure
in making XAS will {\it not\/} stop you from continuing with {\tt
INSTEP2} and the following steps.
\medskip

\newsubsubsection{Create Architecture-specific Install area}

In preparation for the next steps, the {\tt INSTEP1} procedure makes
an architecture-specific installation directory
{\tt\thisver/\$ARCH/INSTALL} and copies the files {\tt INSTEP2}, {\tt
INSTEP3}, and {\tt INSTEP3} there from the {\tt\$INSUNIX} area.  

It then lists out a set of instructions for editing and checking
various files.  Details of what these mean are expanded on in the {\it
\AIPS\ Unix Installation Summary\/} and is not repeated here in the
interests of conciseness. 
% plus I want to get this %#^*$%#% thing finished!
The important thing at this stage is to get {\tt INSTEP2} started as
soon as you can, as it can take a long time to finish.  So you should
check the compiler options, define the programming environment
variables, and start {\tt INSTEP2} as soon as you are ready.

\medskip
\newsubsection{Additional Setup for New AIPS Ports}

This section describes some steps that may be needed in addition to
the customization outlined at the end of the {\tt INSTEP1} script.
Most of it is only relevant if a new \AIPS\ port is being done, but
some sections may be of interest to those who want to --- or have to
--- develop or enhance the system.\medskip

\newsubsubsection{Local Source Code Directories}

If you are porting \AIPS\ to a previously untried architecture, you
will most likely have to create several local directories to hold the
necessary modifications to the code.  Even if you are not ``porting''
and the system is a pretty standard one (\eg, Sparc), you may need to
do this later (\eg, if you modify the tape Z routines to accomodate a
different type of tape drive).  At a mimimum, you will need:\medskip

\example{\thisver/APL/DEV/LOCAL     \hfill \rm (\$ZLOCAL)}
\medskip

\noindent as well as the various directories under {\tt
\thisver/\$ARCH} mentioned during the {\tt INSTEP1} procedure.  There is
really no need for the {\tt \$ZLOCAL} area on the common systems such as
Sun, IBM RS/6000, HP 9000/7xx, Dec/Ultrix, and HP.  If you are porting
to a new computer for which there is no system area (\eg, the equivalent
of {\tt \thisver/APL/DEV/UNIX/BELL/SOL} for Solaris 2), you may want to
create it instead of {\tt ZLOCAL}.  Then you will want to define a new
architecture in the various shell scripts that need it: {\tt
START\_AIPS}, {\tt FDEFAULT.SH}, {\tt TVALT}, {\tt \$SYSAIPS/AREAS.DAT}
(and remember to run {\tt \$SYSUNIX/AREAS} to regenerate the {\tt
AREAS.CSH} and {\tt AREAS.SH} files), and possibly others.  Just look to
see where the {\tt ARCH} variable is used/checked.

If you are going to port to a brand new, previously unsupported TV
device or server, you will want something like:\medskip

\example{\thisver/Y/DEV/LOCAL   \hfill \rm (\$YLOCAL)}
\medskip

\noindent However, almost all platforms will be able to use the {\tt
Y/DEV/SS} routines and the {\tt XAS} X window TV server.  

If for whatever reason you need to develop Q routines or
change the pseudo-AP (array processor) routines, you should also add: 
\medskip

\example{\thisver/Q/DEV/LOCAL   \hfill \rm (\$QLOCAL)}
\medskip

\noindent Note that in both the case of Q and Y routines, there are a
set of stubbed routines provided in each {\tt /DEV/} area.

If you create any of these areas, be sure to add them to the {\tt
AIPSASSN.CSH} and {\tt AIPSASSN.SH} files in {\tt \$AIPS\_ROOT} in a
section specific to your site, and for the Z, Q, and Y local areas, you
will need to modify {\tt LIBR.DAT} (see section 2.4.5). 
%%% @@@ CHECK that this is right!

The Z-routines are stored under {\tt\thisver/APL/DEV} (\ie, {\tt
\$APLGEN}) and this area has two main branches: {\tt UNIX} and {\tt
VMS}.  Under the former there are again two branches: {\tt BERK} for
Berkeley-like (BSD) systems and {\tt BELL} for systems based on AT\&T
System V.  There are a large number of routines (over 240 files) in the
top-level {\tt \$APLGEN} area; many of these are wrappers for the
machine-specific routines found in lower levels.  This also applies to
the other routines; the \AIPS\ group has tried to generalize the lower
level routines as much as possible, or even eliminate them.

Under the {\tt APL/DEV/UNIX/BELL} area, there are separate directories
for Cray ({\tt CRI}), Hewlett-Packard 9000 series 700 ({\tt HP},
Masscomp ({\tt MASC}), Silicon Graphics ({\tt SGI}, not a complete
port), and SunOS 5/Solaris 2 ({\tt SOL}).  Under the {\tt
APL/DEV/UNIX/BERK} area, there are directories for Alliant, Convex,
Decstation, IBM RS/6000, Sun, and Vax.  As above, there are
subdirectories for {\tt NRAO1} and {\tt VLAC1} in the {\tt CVEX} area
(for specifying that we have IEEE hardware).  However, the IBM 3090 area
is a subdirectory of the IBM RS/6000 area.  Similarly, we intend to make
the Dec-Alpha (OSF/1) area a subdirectory of the existing Dec/Ultrix
area.
% @@@ replace above for 15JAN94

To maintain the hierarchical structure, you should position your local
directory such that it accurately reflects your system, for example,
{\tt \thisver/APL/DEV/UNIX/BELL/SGI/MYIRIX} might be the choice for
an SGI system.  Our System V UNIX system support has improved
drastically with the advent of the SunOS 5 and HP ports.  Note however
that the IBM RS/6000 AIX port is firmly in the Berkeley area, despite
its system V nature (it just has excellent Berkeley support and 
\AIPS\ was ported to it before we rejuvenated our System V knowledge).

Y-routines are stored under {\tt\thisver/Y/DEV} and there is a directory
for TV servers ({\tt SS} which supports the screen servers XAS (for X11
including Sun's OpenWindows), SSS (Sun's Sunview only) and XVSS (Sun's
OpenWindows only).  There are older areas here too, including one for
Virtual TV ({\tt VTV}, when the display is on a remote TCP/IP system;
obsolete now).  Other areas are for older image display hardware such as
the IVAS and DeAnza.  These areas have already been listed at the start
of this document (Section 1.8.2).
%%% @@@ keep # up to date

If you have no TV or have one of the supported TV display devices
(including an X11 windowing system), then you probably won't need to do
any Y-routine development.  Use {\tt \thisver/Y/DEV/STUB} for no TV
support.  Otherwise, you should logically position your local Y-routine
directory as in the case of your local Z-routine directory.  You may
also safely elect to postpone any Y-routine development by using the
stubbed routines (see ``Object Libraries and Source Code Search Paths'',
section 2.4.4).
%%% @@@ keep section # up to date

If you do develop Y-routines, please make them {\it device specific
only\/} (if at all possible), not operating system specific or subject
to the availability of specific languages or compilers.  If you need to
make system calls in a Y routine, do it through the Z routines or make
up a new system-specific Z routine if you have to.  Also, try to
mimimize the amount of device-specific code and make as much use of the
generic Y routines as possible.

Finally, the Q-routines are stored under {\tt\thisver/Q/DEV}.  The
structure basically has two sub-trees, one for Floating Point Systems
({\tt FPS}) array processors, and the other for the so-called
pseudo-array processor routines.  The latter includes vectorized
routines for some architectures.  FPS models supported include:
\medskip

{\vbox
{\ndot {\tt 16B/120B}, for 16 bit model 120B array processors}
{\ndot {\tt 16B/5000}, for 16 bit model 5105, 5205, \etc}
{\ndot {\tt 32B/190}, for 32 bit model 190\medskip}\medskip
}

\noindent With the decline in use of Array Processors, the number of
areas for the pseudo-AP (PSAP) routines has grown where they now
outnumber the classical AP areas.  NRAO no longer has any active FPS
array processors that are used for \AIPS.  There are separate areas
under the {\tt \thisver/Q/DEV/PSAP/} directory for: \medskip

{\ndot {\tt ALLN} Alliant FX vector processors}
{\ndot {\tt CRI} Cray Research (UniCos)}
{\ndot {\tt CVEX} Convex vector processors}
{\ndot {\tt DEC} DecStation-optimized PSAP routines}
{\ndot {\tt IBM} RS/6000 (AIX) optimized PSAP routines; there is also
        a subdirectory for mainframe-specific routines ({\tt IBM/3090/}).}
{\ndot {\tt SUN} Sun 3/4 optimized PSAP routines}
{\ndot {\tt VMS} VAX/VMS specific PSAP routines\medskip}\medskip

\noindent
If you have no AP or if your system matches any of the subdirectories of
{\tt\thisver/Q/DEV/PSAP}, chances are you won't need a local Q-routine
directory.  For new ports, it's most likely you won't need one anyway as
the generic pseudo-AP routines will do a good job on most systems.
Otherwise, you should logically position your local directory in the
above scheme.  You may also safely elect to postpone any Q-routine
development by defining the {\tt\thisver/Q/DEV/PSAP} directory as the
only directory in your Q-routine search path (this is the default).
\medskip

\newsubsubsection{Environment Variables for Areas (``logicals'')}

Most of the directories in the \AIPS\ directory tree have an environment
variable associated with them.  This practice comes from the VMS version
where logical names were extensively used; these variables are often
referred to as ``logicals'', ``logical names'' or just ``areas''.  Most
of these are defined in {\tt AREAS.CSH} and/or {\tt AREAS.SH} (former
for C shell, latter for Bourne/Korn/BASH shell).  Both of these files
are automatically generated from the {\tt\$SYSAIPS/AREAS.DAT} file by
the shell script {\tt\$SYSUNIX/AREAS}.  Extensions to this scheme, such
as the {\tt ZLOCAL}, \etc, areas suggested above, should be inserted in
the files {\tt AIPSASSN.CSH} and {\tt AIPSASSN.SH} in the
{\tt\$AIPS\_ROOT} area.  Note that in the generic {\tt \$SYSUNIX}
versions of the {\tt CDVER.*} files, there is an {\tt echo} statement
which is designed to prompt you into putting the local definitions
there; this is somewhat outdated and you should probably remove it and
put the definitions in the {\tt AIPSASSN} files instead.

It should be noted that some UNIX systems may choke on the size of an
environment resulting from so many definitions.  This was mentioned
above in the {\tt INSTEP1} section on building the preprocessor and
other programs.  The limiting factor is the value of {\tt NCARGS} as
defined in the file {\tt /usr/include/sys/param.h}.  This is the maximum
number of characters that can appear in an argument list. Since the
environment is passed as part of the argument list, a large environment
can start to cause problems for ``wild card'' operations like {\tt ls
long\_directory\_path\_name/*}.  {\tt NCARGS} varies somewhat but on
most modern systems it is usually in excess of 24000.  ConvexOS (as of
release 9.0 at least) is an exception and is closer to 12000.  On
systems where it is smaller, you may find it necessary to eliminate some
of the definitions.  Alternately, you can want rebuild or reconfigure
your system kernel with a sufficiently large value for {\tt NCARGS}.
However, removing ``logicals'' for areas you may have deleted or don't
need is probably a simpler solution.\medskip

\newsubsubsection{Login Procedures}

After modifying {\tt AIPSASSN.*} above, you should have some feeling for
the \AIPS\ programming environment variables.  Throughout this document,
areas are usually referred to by their symbolic names, \eg, {\tt
\$SYSUNIX} rather than {\tt \thisver/SYSTEM/UNIX}.  You may find it
useful to print out a copy of {\tt \$SYSLOCAL/AREAS.CSH} (or {\tt .SH},
or better still {\tt \$SYSAIPS/AREAS.DAT}, their progenitor) to help
translate.

Almost all of the \AIPS\ procedures are written in Bourne shell syntax
and have been exercised under logins where the default shell is either
the Bourne shell, Korn shell, GNU Bash, or (most often) the C shell.
Depending on your choice of shell, either {\tt LOGIN.CSH} or {\tt
LOGIN.SH} should be incorporated into the login procedure for the AIPS
account via:\medskip

\example{source LOGIN.CSH \hfill\rm (C shell syntax for {\tt .login})}

\noindent or

\example{.~\$HOME/LOGIN.SH \hfill\rm (Bourne/Korn/Bash shell syntax for 
                                      {\tt .profile})}
\medskip

\noindent
There have been many problems with the use of {\tt tcsh} as a login
shell reported by several users; care should be exercised if you use
this shell.  Also, it is important to refer explicitly to {\tt LOGIN.SH}
to prevent the ``dot'' command from picking up the generic
{\tt\$SYSUNIX} version of the file (and telling you that {\tt
AIPS\_ROOT} is undefined!).  Any other accounts that intend on using
\AIPS\ should also have one of these lines --- or similar --- in their
login/profile file(s).  However, please note that you may run into file
locking problems and get multiple versions of {\tt AIPS1}, {\tt AIPS2},
\etc.  with multiple accounts and/or multiple groups.  In particular
watch for the protection mask on the {\tt /tmp} area; on some systems it
is set so as to prevent one user from deleting another user's file, even
though the protection mask on the file itself permits such.

The values for {\tt\$SYSLOCAL} and {\tt\$SYSUNIX} are generated by
{\tt AIPSPATH.SH} and its {\tt .CSH} sibling.  The environment
variable {\tt PATH} is extended to include the current working
directory (``dot'' or ``.''), followed by {\tt\$SYSLOCAL} and
{\tt\$SYSUNIX}.  These are inserted at the beginning of the variable,
unless the directories already appear in the {\tt PATH}.  
\AIPS\ definitions (environment variables) can be reset to whichever
version you want through typing {\tt\$CDOLD}, {\tt\$CDNEW} and
{\tt\$CDTST}.  These strange creatures are the lowest common denominator
solutions for all flavors of UNIX and shells.  They amount to executable
environment variables, something like symbols in VMS.  The path can be
restored to pre-\ttaips\ level by setting {\tt PATH} equal to the value
of {\tt TPATH}.

You may want to insert one of these {\tt\$CD...} in the {\tt .login} or
{\tt .profile} of the \AIPS\ account and any other accounts that will
use \AIPS.  It is not strictly necessary to do this, as it is mainly for
installation, programming and moving quickly around the directory tree.
You will need to at least call {\tt\$CDOLD} or {\tt\$CDNEW} or
{\tt\$CDTST} interactively before starting the installation as it will
fail otherwise.  Once done, it is worth looking at all the environment
variables (with {\tt printenv} or {\tt set}, probably piped through a
{\tt sort}) in case there are any errors.  
\medskip

\newsubsubsection{Object Libraries and Source Code Search Paths}

The \aips\ system has to a certain extent re-invented the wheel in this
area for Unix.  This is largely due to the early emphasis on VMS systems
which do not come by default with such a utility as the Unix {\tt make}.
So instead of editing a Makefile, the installer may have to edit files
called {\tt LIBR.DAT} and {\tt INCS.SH} (in {\tt\$SYSLOCAL}) which
perform much of the same purpose.  It is {\it critical\/} that this is
done right, as otherwise the resulting binaries (executable images) will
not work correctly, if they even get made in the first place.  These
setup files should have been copied to {\tt\$SYSLOCAL} from the
{\tt\$SYSUNIX} area or one of the architecture-specific {\tt SYSTEM}
areas.

Although it has been mentioned before in this document, it is worth
repeating that {\it for most standard configurations, no editing 
of\/ {\tt LIBR.DAT} is necessary\/}.  New ports, Convexes without IEEE
floating point hardware, systems with IIS/IVAS/\etc, TV's, array
processors and the like are the only reasonable candidates that you will
have to modify this file.
\medskip

\newsubsubsection{Setting up LIBR.DAT}

This file has two sections.  The first associates subroutine source
code directories with one or more object libraries.  The second
section specifies one or more object library link lists for each
program source code area.  The entire \AIPS\ directory hierarchy is
designed so that programs that need the same sets of libraries are
grouped in the same directories; this enables such a scheme to work.

There are several versions of {\tt LIBR.DAT} provided with \AIPS.  If
you are porting to a new system, you should look in the directories
under {\tt\$ARCH/SYSTEM} for all architectures for a system you may be
able to clone.  If none of these are suitable, you can always use the
generic {\tt\$SYSUNIX/LIBR.DAT} as your starting point, although this
will need more work.  It will have lines with {\tt ---something
important---}; these are lines that you have to change, and such
comments should be removed in your final version before starting {\tt
INSTEP2}. 

The first part of {\tt LIBR.DAT} is used to associate object libraries
(qctually Unix ``archive'' libraries, \ie, {\tt \$LIBR/*/SUB\-LIB})
with the directories containing the different categories of
subroutines.  The directories will be searched in a somewhat peculiar
order ({\it not\/} the order in which they are listed) to locate the
proper module to be used in the construction of the associated object
library.  For example, on the NRAO/CV \aips\ sun cluster (SunOS 4.1.2),
the search path for Z-routine source code is: \medskip

\vbox{
\example{Z-routines}
\example{ }
\example{\$LIBR/APLSUN/SUBLIB:0:\$APLSUN \hfill\rm (Sun specific)}
\example{\$LIBR/APLSUN/SUBLIB:0:\$APLBERK \hfill\rm (Berkeley (BSD) Unix)}
\example{\$LIBR/APLSUN/SUBLIB:0:\$APLUNIX \hfill\rm (Generic Unix)}
\example{\$LIBR/APLSUN/SUBLIB:0:\$APLGEN \hfill\rm (Generic)}
}
\medskip

\noindent
The format here is {\tt <aipslibrary>:<loadnumber>:<directory>}.  The
{\tt <loadnumber>} is only intended for when a site needs multiple TV's
(less common now, with workstations taking over from the IIS, IVAS,
DeAnza and other devices) and/or multiple sets of Q routines (also less
common, typically a VAX with AP and pseudo-AP versions).  There must be
{\it no leading, embedded or trailing blanks\/} in these search path
definitions.  For Suns that use dynamic libraries, the format is still
the same; the {\tt LIBR} and {\tt LINK} sun-specific shell scripts will
change {\tt SUBLIB} to {\tt SUBLIB.so} on the fly.

The {\tt MAKEAT} procedure has inbuilt assumptions about the way the
directory hierarchy is maintained.  Whenever a module is to be
compiled with {\tt COMRPL} or linked with {\tt COMLNK}, all the
subordinate directories are searched to see if there is a more
system-specific version of the module.  For instance, a {\tt COMRPL
\$APLUNIX/ZDATE.C} will find four different versions (at the time of
writing):\medskip

\example{APL/DEV/UNIX/BERK/IBM/3090/ZDATE.C}
\example{APL/DEV/UNIX/BERK/IBM/ZDATE.C}
\example{APL/DEV/UNIX/BERK/ZDATE.C}
\example{APL/DEV/UNIX/ZDATE.C}
\medskip

\noindent This list is sorted in reverse order and for each file in
the list, the directory is checked against those listed in the {\tt
SEARCH<n>.DAT} files in {\tt\$SYSLOCAL} ({\tt <n>} here corresponds to
{\tt <loadnumber>}).  The net effect of all these gyrations is that
the most specific version of the routine is chosen.  However, {\it the
mechanism currently depends on maintaining the relation between
directory depth and how machine specific each directory is\/}.  It
will fail if you do not follow the general scheme.

The {\tt \$LIBR} area itself contains only subdirectories (\eg, {\tt
\$LIBR/APLSUN/}) which serve as staging areas for object modules that
are to be added or replaced in the object libraries (Unix archive files)
using the host object librarian (\eg, {\tt ar}).  All of the archive
files have the same name, {\tt SUBLIB}, but simply reside in different
directories.  \AIPS\ only uses Unix archive files for object libraries,
hence this is what they are referred to as in the remainder of this
document.  On Suns and HPs, the shared library {\tt *.so} files 
% @@@ change for 15JAN94
used to be in, \eg, {\tt \$LIBR/APLSUB/SUBLIB.so} but now they 
% @@@ just delete above line?
are in, \eg, {\tt \$LIBR/APLSUB.so}.  This is partly to aid in the
possible moving of the \AIPS\ code, and a possible future binary
distribution of the system.  For Suns, see the documentation on the {\tt
LD\_LIBRARY\_PATH} variable.

For most installations, the {\tt <loadnumber>} will be zero in all
cases.  However, where there are two or more types of TV or
AP/PseudoAP's to be supported on a single system, the same object
module may be needed in multiple object libraries.  Below is an
example of this, where there are three TV's: an IIS model 70E, an IIS
IVAS, and the XAS X-windows TV.  \medskip

\example{Y subroutine source code search paths and object libraries:}
\example{ }
\example{Standard routines}
\example{ }
\example{\$LIBR/YSUB/SUBLIB:0:\$YSUB}
\example{ }
\example{Non-standard routines}
\example{ }
\example{\$LIBR/YNOT/SUBLIB:0:\$YNOT}
\example{ }
\example{Standard Screen Server TV Y-routines}
\example{ }
\example{\$LIBR/YSS/SUBLIB:0:\$YSS}
\example{\$LIBR/YSS/SUBLIB:0:\$YGEN}
\example{ }
\example{IIS Model 70 Y-routines}
\example{ }
\example{\$LIBR/YM70/SUBLIB:2:\$YM70}
\example{\$LIBR/YM70/SUBLIB:2:\$YIIS}
\example{\$LIBR/YM70/SUBLIB:2:\$YGEN}
\example{ }
\example{IIS Model IVAS Y-routines}
\example{ }
\example{\$LIBR/YIVAS/SUBLIB:4:\$YIVAS}
\example{\$LIBR/YIVAS/SUBLIB:4:\$YGEN}
\example{ }\medskip

\noindent
In this example, whenever an object module is generated from source code
common to the implementation of both the model 70 and IVAS, it gets
added or replaced in both {\tt\$LIBR/YM70/SUBLIB} and
{\tt\$LIBR/YIVAS/SUBLIB}.  Similarly, object modules common to all three
tv's are added/replaced in all three {\tt SUBLIB} libraries.  Note the
fact that the {\tt <loadnumber>} increments by 2 for TV's.  In the
linking stage, tasks that call the Y routines will be made into three
separate binaries or executable files, one for each TV.  The task for
the TV server will be put in {\tt\$LOAD}, that for the IIS Model 70 will
go in {\tt\$LOAD2} (same as {\tt\$LOAD/ALT2/}), and those for the IVAS
will go in {\tt\$LOAD4} (same as {\tt\$LOAD/ALT4/}).  This obviously has
disk space consequences.

Note that the normal action of a compile in \AIPS\ using the standard
{\tt COMRPL} shell script is to simply place the {\tt .o} or object file
in the {\tt\$LIBR/whatever/} directory.  They are later archived (and
{\tt ranlib}'d if needed) by other tools before any linking is performed
(by {\tt COMLNK}).

The following is the {\tt\$LIBR} directory structure as it existed on
the NRAO-CV Convex C1 (before we retired it), from which the above
segment of {\tt LIBR.DAT} was extracted.  The subroutine areas from
which the object libraries were generated are given on the right:
\medskip

\vbox{\tt\settabs
\+\quad\quad&\$LIBR/APLCVEX/SUBLIB\quad&\$APLNRAO1,\$APLCVEX,\$APLBERK,\$APLUNIX,\$APLGEN\cr

\+&\$LIBR/AIPSUB/SUBLIB  & \$AIPSUB\cr
\+&\$LIBR/APLCVEX/SUBLIB & \$APLNRAO1, \$APLCVEX, \$APLBERK, \$APLUNIX, \$APLGEN\cr
\+&\$LIBR/APLNOT/SUBLIB  & \$APLNOT\cr
\+&\$LIBR/APLSUB/SUBLIB  & \$APLSUB\cr
\+&\$LIBR/QNOT/SUBLIB    & \$QNOT\cr
\+&\$LIBR/QSUB/SUBLIB    & \$QSUB\cr
\+&\$LIBR/QVEX/SUBLIB    & \$QVEX, \$QPSAP\cr
\+&\$LIBR/YIVAS/SUBLIB   & \$YIVAS, \$YGEN\cr
\+&\$LIBR/YM70/SUBLIB    & \$YM70, \$YIIS, \$YGEN\cr
\+&\$LIBR/YNOT/SUBLIB    & \$YNOT\cr
\+&\$LIBR/YSUB/SUBLIB    & \$YSUB\cr
\+&\$LIBR/YSS/SUBLIB     & \$YSS, \$YGEN\cr}\medskip

\noindent There is nothing special about the {\tt\$LIBR} subdirectory
names other than being as self-explanatory as possible.  However, the
library name {\it must\/} be {\tt SUBLIB}.  If the directories do not
exist, {\tt INSTEP2} will automatically create them based on the
contents of {\tt LIBR.DAT}.  NOTE: {\it if for some reason a directory
is not created,\/ {\tt COMRPL} {\it will\/} check for it and attempts to
create it, crashing if this fails.  This behaviour is different from
previous versions
% @@@ change for 15JAN94
and it can happen if {\tt LIBR.DAT} is not set up correctly\/}. 
\medskip

\newsubsubsection{Program and Object Library Mappings}

While the first part of {\tt LIBR.DAT} relates subroutine directories
to one or more object libraries, the second part maps the program
(task) source code areas to the object libraries that should be
included in the argument list for the linker (loader).  The separation
between the two areas is delimited by the line:\medskip

\fortran
AIPS stand alone program source code search paths and link libraries:
\endfortran
\medskip

\noindent Object libraries are often repeated in these lists.  This is
to account for the single pass nature of some UNIX linker/loaders
(usually {\tt ld}).  Libraries must often be cycled several times to
resolve all external references.  For example, the object library
containing modules generated from the {\tt\$APLSUB} source code area
need to be cycled at least twice in the lists for every program source
code area.  This is because routines used from the other object
libraries specified in the lists often call {\tt \$APLSUB} routines.
The required order of the link lists that appear in the various
distributed versions of {\tt LIBR.DAT} have been determined empirically
and with rare exceptions, should apply to most systems.  IBM/AIX (on
RS/6000 machines) is an exception as the loader there uses multiple
passes to resolve all undefined references; so the IBM version of {\tt
LIBR.DAT} does not have any duplicate libraries in these lists.

A default list is required in {\tt LIBR.DAT} for each of the
standard program source code areas.  For Unix, These are:\medskip

{\settabs 6 \columns \tt
\+& \$AIPGUNIX  & \$AIPNOT      & \$AIPPGM      & \$APGNOT\cr
\+& \$APGOOP    & \$APGUNIX     & \$APLPGM      & \$QPGM\cr
\+& \$QPGNOT    & \$QPGOOP      & \$QYPGM       & \$QYPGNOT\cr
\+& \$YPGM      & \$YPGNOT      & \$YPGVDEV\cr}\medskip

\noindent Different lists are distinguished by a number code ({\tt
<loadnumber>} above) inserted between the object library and area, and
delimited with colons.  Default lists are indicated by the number code
{\tt 0} and executable files (binaries) generated using them are
stored in the default load library, {\tt\$LOAD}.  Depending on the
configuration of TV's and AP's, you may need alternate lists with
non-zero {\tt <loadnumber>}s (from 1 to 9).  As mentioned briefly
above, the purposes of these additional numbers are to create
alternative versions of certain programs that use tht Y and/or Q
routines for each alternative TV and/or AP.  The binaries for these
programs are stored in {\tt\$LOAD<n>} where {\tt <n>} is the {\tt
<loadnumber>}.  This environment variable will translate to {\tt
\$LOAD/ALT<n>}.  {\it Only \/{\tt\$LOAD1} through \/{\tt\$LOAD3} are
defined by default on most configurations so you may have to add extra
definitions to \/{\tt \$AIPS\_ROOT/AIPSASSN.*} or \/{\tt 
\$YSLOCAL/CDVER.*}\/}; see the sample section in these files for host
{\tt NRAO1} for an example ({\tt LOAD4} is defined there).

The alternate lists and load module areas are only required on those
systems where more that one type of array processor or TV device is to
be implemented, or both.  Most \AIPS\ programs use neither Q-routines
nor Y-routines (\eg, {\tt\$APLPGM} and {\tt\$APGNOT}) and their load
modules are always stored in the default load area.  Other programs will
use Q routines, Y routines or maybe both.  There are areas for each of
these possibilities, and additional areas for not-standard programs
(those that don't quite comply with \aips\ coding conventions but are
too useful to do without), and the Object-Oriented Fortran areas.  These
areas have environment variables {\tt\$QPGM},{\tt\$QPGNOT}, and
{\tt\$QPGOOP}, {\tt\$YPGM} and {\tt\$YPGNOT}, and {\tt\$QYPGM} and
{\tt\$QYPGNOT}.

As an example purely to illustrate this scheme, take a system with 2
different types of TV devices (\eg, TV server and IVAS) as well as 2
different array processors ({\it real\/} and {\it pseudo\/}).  On such
a system, 4 different combinations of array processor and TV device
dependency are possible:\medskip

{\ndot {\it real\/} AP with TV server ({\tt\$LOAD})}
{\ndot {\it pseudo\/} AP with TV server ({\tt \$LOAD1})}
{\ndot {\it real} AP with IVAS TV ({\tt\$LOAD2}), and}
{\ndot {\it pseudo\/} AP with IVAS TV ({\tt\$LOAD3})\medskip}
\medskip

\noindent The programs that depend on Q-routines wil be linked once
with the object libraries for the {\it real\/} array processor,
creating one load module (binary or executable file), then linked
again with the {\it pseudo\/} array processor object library, creating
a second load module.  The load areas that the resulting binaries are
kept is indicated in parentheses in the itemized list above.

Programs that depended on the Y routines will similarly have two
versions of each program built, and programs that depend on both Q and
Y routines will have four versions built.  

The convention of associating TV and AP device numbers with {\tt
<loadnumber>} is cast in stone.  TV device type 1 is {\it always\/}
associated with {\tt <loadnumber>=0} and {\tt 1}, TV device type 2 with
{\tt <loadnumber>=2,3} and so on (do not confuse these TV device numbers
with the TV {\it instance\/} number that corresponds to a given image
catalog).  On the other hand, it does not matter whether the AP or PSAP
is specified first, and on most unix systems only the PSAP routines will
be used.  So on such systems if you specify two types of TV device, you
would use {\tt <loadnumber>}s zero and two.

The way to implement this for the program section of {\tt LIBR.DAT} is
illustrated best by an example.  Here is how it would be done for a
system with an IIS model 70, an IVAS and the TV server:\medskip

\fortran
QYPGM => Standard tasks that call both Q-routines and Y-routines

w/ IIS Model 70 Y-routines

$LIBR/QSUB/SUBLIB:0:$QYPGM
$LIBR/QVEX/SUBLIB:0:$QYPGM
$LIBR/YSUB/SUBLIB:0:$QYPGM
$LIBR/YM70/SUBLIB:0:$QYPGM
$LIBR/APLSUB/SUBLIB:0:$QYPGM
$LIBR/APLCVEX/SUBLIB:0:$QYPGM
$LIBR/APLSUB/SUBLIB:0:$QYPGM

w/ IIS Model IVAS Y-routines

$LIBR/QSUB/SUBLIB:2:$QYPGM
$LIBR/QVEX/SUBLIB:2:$QYPGM
$LIBR/YSUB/SUBLIB:2:$QYPGM
$LIBR/YIVAS/SUBLIB:2:$QYPGM
/wherever-you-keep-proprietary-libraries/XANTH.LIB:2:$QYPGM
$LIBR/APLSUB/SUBLIB:2:$QYPGM
$LIBR/APLCVEX/SUBLIB:2:$QYPGM
$LIBR/APLSUB/SUBLIB:2:$QYPGM

w/ TV Server Y-routines

$LIBR/QSUB/SUBLIB:4:$QYPGM
$LIBR/QVEX/SUBLIB:4:$QYPGM
$LIBR/YSUB/SUBLIB:4:$QYPGM
$LIBR/YSS/SUBLIB:4:$QYPGM
$LIBR/APLSUB/SUBLIB:4:$QYPGM
$LIBR/APLCVEX/SUBLIB:4:$QYPGM
$LIBR/APLSUB/SUBLIB:4:$QYPGM
\endfortran
\medskip

\noindent In this case, when programs from the {\tt\$QYPGM} area are
linked, they are linked three times, once with the IIS model 70 object
library, then with the IVAS library (note the nonstandard location)
and a third time with the TV Server library.  The resultant executable
modules are stored in the separate load libraries, {\tt\$LOAD},
{\tt\$LOAD2} and {\tt\$LOAD4}.  This is done automatically whenever a
{\tt COMLNK} is performed to compile and/or link a task.

Note that for IVAS TV's, a proprietary library is required.  If you have
an IVAS, you should edit {\tt LIBR.DAT} to set its location
appropriately.  The Convex default version of this file has NRAO's
location for this file in Charlottesville; this has to be changed before
starting {\tt INSTEP3}.

Many of the \AIPS\ programming procedures make use of {\tt LIBR.DAT}
either directly or indirectly.  These include {\tt COMRPL}, {\tt
COMLNK}, {\tt LIBR}, {\tt LIBS}, {\tt LINK}, {\tt MAKEAT} and {\tt
SEARCH}.  These are described briefly in the tables earlier (section
1.9)
%%% @@@ keep section # up to date
and also in the extensive comments in the shell scripts themselves.

Using {\tt LIBR.DAT}, all of a given \AIPS\ implementation's source code
search paths (except for ``INCLUDE'' files), object code libraries, link
lists and load module areas can be mapped in a single, easily
maintained file.  The only other files that need customization for
compiling are the options files {\tt CCOPTS.SH}, {\tt ASOPTS.SH} where
relevant, {\tt FDEFAULT.SH}, and {\tt LDOPTS.SH}.
\medskip 

\newsubsubsection{INCS.SH}

The file called {\tt INCS.SH} sets the search path for the {\tt
INCLUDE} files for Fortran modules by the source code preprocessor,
{\tt PP}.  Any statement of the form\medskip

\example{ INCLUDE 'INCS:filename'}

\noindent will trigger the preprocessor into searching a list of
directories for the include files.  Installers with VMS background will
immediately see the origin of this usage, as on such systems {\tt INCS}
is a logical name implementing a search path.  {\tt INCS.SH} simply
defines the environment variable {\tt\$STDINCS} as the search path.

The way this works in practice is that the {\tt PP} script will call
{\tt INCS.SH} (for fortran files only, of course), and it will also set
{\tt INCS=\$STDINCS} if the environment variable {\tt INCS} is not
already defined.  Then {\tt PP} searches each directory in {\tt INCS}
until the first include file matching the indicated filename is found.
This way, it is possible to override the default definition, if you
should ever have to do that.

For most standard configurations, the {\tt INCS.SH} file is already
set up and needs no modification.  Usually the only include file in a
system-specific include area will be {\tt DAPC.INC} which sets the
pseudo-AP array sizes.  On older systems these were small, but the
default (\eg, for Suns) is now larger, typically 5 Megabytes.

%%% is this too detailed?  Maybe described elsewhere?  (INCS/PP stuff)

{\tt\$INC} is the root of the hierarchical include file directory
structure.  Like the Z-routine and {\tt SYSTEM} trees, it is based on
the operating system and for new ports it may be necessary to create a
purely local directory for your system.  (With recent ports, we have
generally found this to be unnecessary, as both the {\tt\$INCSOL} and
{\tt \$INCHP} areas are empty).  System specific include files are
mostly those used in the pseudo array processor library.  Check for a
subdirectory in the {\tt\$INC/NOTST/} directory that matches your
system.  If found and it's not empty, check the {\tt INCS.SH} file to
make sure it defines {\tt STDINCS} such that the system-specific include
area is searched first.

(You should also note the Pseudo Array Processor's size in the file
{\tt DAPC.INC}; this needs to match the number you set for the second
AP memory in the {\tt RUN SETPAR} menu (item 29) such that the total
number of kilowords in regular AP (64) plus 2nd AP (\eg, 192) matches
the size of the arrays declared in that include file; in this example,
that would be {\tt APSIZE=262144}, {\tt PKPWD2=192}).  For most modern
RISC systems, an AP size of {\tt APSIZE=1310720} or $1.25$ megawords is
appropriate, which makes {\tt PKPWD2=1216}.

Chances are you won't need a purely local include file directory if
you are simply using the vanilla pseudo AP library or a preconfigured
system like Sun, Solaris, Dec, IBM, HP, or Convex.
\medskip

\newsubsubsection{Compiler and Loader Options}

Each Unix system seems to have slightly different commands and options
for compiling (fortran and C) and loading/linking.  To address this,
the \AIPS\ system includes shell scripts to set both the command and
options as well as \aips-specific default values.  These files
are:\medskip

{\ndot {\tt ASOPTS.SH} for assembler (if you need it)}
{\ndot {\tt CCOPTS.SH} for the C compiler}
{\ndot {\tt FDEFAULT.SH} and {\tt OPTIMIZE.LIS} for the Fortran
        compiler, and} 
{\ndot {\tt LDOPTS.SH} for the loader\medskip}\medskip

\noindent Three of these should have been copied from {\tt\$SYSLOCAL} by
the {\tt INSTEP1} shell script, and you should edit them there.  The
other two, {\tt FDEFAULT.SH} and {\tt OPTIMIZE.LIS} are in
{\tt\$SYSUNIX}.  The comments in these files make it relatively easy to
edit and change them as appropriate.

The issue of compiler optimization levels can be tricky.  Faulty (\ie,
too much) optimization for only a few modules can cause big headaches.
On some architectures (Sun, IBM RS/6000 for example), we have had some
success with turning optimization on just about everywhere.  For most
pre-configured systems, the options files will come set to suitable
values, but you should check them anyway, if necessary, reading the
manual pages on the Fortran, C and loader/linker ({\tt ld}) commands if
you are unsure about the options.

In the {\tt\$SYSUNIX} area, the files {\tt FDEFAULT.SH} and {\tt
OPTIMIZE.LIS} help specify and centralize the Fortran compiler settings
and optimization details.  The former stores the default Fortran command
name and standard options for a number of architectures (Sun3 and Sun4,
Solaris, DEC, IBM, IBM3090, HP, Convex, Cray, Alliant, SGI; last three
may be out of date).  It also defines up to 9 levels of optimization.
The latter stores the information on which programs, or subroutines, or
areas, or architectures, or most combinations thereof.  The latter file
specifies default optimization and debug levels for various parts of
\AIPS, and exceptions to the rules.

Speaking of exceptions, the Q routines are a notable one.  It is
desirable to throw whatever optimization your system allows at these
subroutines.  The most significant gains in performance will result from
optimizing the contents of {\tt \$QPSAP} (see \AIPS\ memo 71, for
example).  Watch out, though: compiler options and even their meanings
may change from one system to the next, and even from one operating
system version to the next.\medskip

\newsubsubsection{Preliminary Programs --- NEWEST and PRINTENV}

There are three programs that are needed prior to starting the
rebuilding of \AIPS.  One of these, the preprocessor, is described in
the next section.  The other two are {\tt NEWEST} and {\tt PRINTENV}.
The purpose of the former is to determine which of a given set of files
has been created most recently.  The latter is a replacement for the
Berkeley {\tt printenv} for some systems that lack it (yes, there are
--- or were --- some).  {\tt INSTEP1} should have already built these
for you; if it did this successfully --- and they work --- skip this and
the next section (and treat yourself to a small banana split).

If you have to make these by hand, here is how.  Copy the source for
these to the {\tt\$SYSLOCAL} area and rebuild them thus: \medskip

\example{\% cd \$SYSLOCAL}
\example{\% cp \$SYSUNIX/NEWEST.C newest.c \hfill\rm (note lowercase!)}
\example{\% cc -O -o NEWEST newest.c}\medskip

\noindent If your system has {\tt printenv}, then copy the Sun version
of the trivial shell script:\medskip

\example{\% cp \$SYSSUN/PRINTENV .}\medskip

\noindent but, {\it if and only if your system does not have\/} {\tt
printenv}, you should instead type:\medskip

\example{\% cp \$SYSUNIX/PRINTENV.C printenv.c \hfill\rm (again, lowercase)}
\example{\% cc -O -o PRINTENV printenv.c}\medskip

\noindent Then, after verifying that the programs work ({\tt INSTEP2}
will do this for you, don't worry) you can delete the {\tt .c}
(lowercase) files. \medskip

\newsubsubsection{Source Code Preprocessing}

\AIPS\ currently uses a preprocessor on all systems to convert the
Fortran code to generic Fortran 77.  The preprocessor includes:
\medskip

\item{$\bullet$} locating {\tt INCLUDE} statements, then searching for
        and inserting the text from the specified external file;
\item{$\bullet$} detecting ``local'' include text at the beginning of
        the file, storing the text and its name away in memory, then
        inserting the text wherever specified via {\tt INCLUDE}
        statements; 
\item{$\bullet$} substituting {\tt REAL} for {\tt HOLLERITH} type
        declarations, which are used for storing 4 (always) hollerith
        characters per element (regardless of host word size).
% @@@ remove ``new'' for 15JAN94
\item{$\bullet$} New for \thisver: Up to three levels of hierarchical
        include files can now be referenced; some of the code actually
        uses this.  You will see the message ``** New version of PP
        invoked: 3--level INCLUDEs'' during each preprocessing.
\medskip

\noindent {\tt INSTEP1} should have attempted to generate the
preprocessor.  If it succeeded and produced a {\tt PP.EXE} file that
seems to work in {\tt INSTEP2}, you can skip the rest of this section.
However, if for some reason it failed and you have to build it
manually, read on.

To generate the source code preprocessor binary {\tt PP.EXE} which is
in turn called by the source code preprocessor script {\tt PP}, do the
following:\medskip

\example{\% cd \$SYSLOCAL}
\example{\% cp \$SYSUNIX/PP.FOR pp.f}
\example{\% cp \$APLUNIX/ZTRLOG.C ztrlog.c}

\medskip\noindent
{\tt ZTRLOG.C} is a routine that translates environment variables that
is needed by the preprocessor.  If you are using AIX (IBM's version of
Unix), or HP--UX, or UniCos (Cray), or any other system where an
underscore is {\it not\/} appended to the name of C routines when they
are called from Fortran, you will need to strip out the trailing
underscore from {\tt ztrlog.c} thus:\medskip

\example{\% mv ztrlog.c ztrlog.tmp}
\example{\% cat ztrlog.tmp | sed 's/ztrlog\_/ztrlog/' >ztrlog.c}
\example{\% rm ztrlog.tmp}\medskip

\noindent This is what {\tt INSTEP1} does to remove the underscore.
Additionally, on UniCos systems, you need to convert the references to
{\tt ztrlog} to {\tt ZTRLOG} (uppercase).  This part may have worked so
before you do this, check if it left a {\tt ztrlog.c} file in
{\tt\$SYSLOCAL}.

Next compile the two source files with:\medskip

\example{\% cc -c -O ZTRLOG.c}
\example{\% f77 -O -o PP.EXE PP.f ZTRLOG.o}\medskip

\noindent You may have to substitute a different command in place of
{\tt f77} (\eg, {\tt fc} on convex, {\tt xlf} on IBM/AIX, \etc).  The
{\tt -O} is for optimization.

The procedure {\tt PP} operates on fortran ({\tt .FOR}), C ({\tt .C}),
and assembler ({\tt .S}) files.  It only runs the {\tt PP.EXE} program
on fortran files; for the other files, the operation may be a simple
copy to files with lowercase file ``type'', e.g. {\tt FOO.f}, or in
some cases (IBM/AIX, HP) with some filtering of C source code.  In the
case of Fortran modules, {\tt PP} sets {\tt\$INCS} to whatever is in
the variable {\tt\$STDINCS} if it is not already set to something (see
the description of {\tt INCS.SH} above).  If there is already a {\tt
FOO.f} or whatever, it will be overwritten by the new file that {\tt
PP} or {\tt PP.EXE} creates.

(The next version of \AIPS\ will support the AIX qualifier that causes
the loader to postpend underscores to external references automatically,
so this little indirection will be unnecessary).

\medskip

\newsubsection{Installation Step 2}

\newsubsubsection{Running INSTEP2}

Change directory to {\tt\thisver/\$ARCH/INSTALL}.  This directory should
have been created by {\tt INSTEP1}; if not, create it and copy files
{\tt INSTEP2}, {\tt INSTEP3}, and {\tt INSTEP4} there from the
{\tt\$INSUNIX} area (or make symbolic links).  These are shell scripts
that do most of the work for the remaining installation steps.  {\tt
INSTEP2} will create any missing directories in which to store binary
files (object libraries, executable modules, etc.) and compile all the
subroutines required by \AIPS\ on the host system based on the
specifications given in {\tt\$SYSLOCAL/LIBR.DAT}.  So it is important to
have this edited {\it before\/} your first (and hopefully only) run of
{\tt INSTEP2}.  To start things rolling, simply type: \medskip

\example{\% \$CDTST}
\example{\% INSTEP2}

\medskip
\noindent The first command is necessary to define the 
\AIPS\ environment variables, if they have not already been defined.
Depending on the version you want, you may substitute {\tt\$CDNEW} or
{\tt\$CDOLD} here.

{\tt INSTEP2} will first check for the existence of the directories in
which binary files will be stored and if not found will attempt to
create them.  These existence/creation operations are very fast, but the
source code compilation phase can take quite some time.  The versions of
\AIPS\ starting with {\tt 15OCT92} release have slower compilation times
than earlier versions, in part because of the extra functionality made
available by {\tt OPTIMIZE.LIS}.  On an unloaded Sun 3 system or a
Convex C--1, this can mean the better part of a day, or more.  On an IBM
RS--6000/560 or a HP 9000/735, it will only be a bit over two hours.

One thing to watch for is that if all of the {\tt\$LIBR/*}
subdirectories are not created, {\tt INSTEP2} can crash when it tries to
create the directory (it's actually {\tt COMRPL} that does this).  This
generally occurs if {\tt LIBR.DAT} was not set up correctly the first
time and {\tt INSTEP2} has to be repeated.  If you find yourself in this
situation, you should either remove all the subdirectories and their
contents from {\tt\$LIBR} and start {\tt INSTEP2} from scratch, or
create the missing directory by hand.  In the latter case, you may have
to mess with the list ({\tt *.LIS}) files.

Another thing to watch for with {\tt INSTEP2} (and the following steps)
is that there have been reported problems with them when they are called
from the Korn shell.  These have not been verified recently, however,
probably largely because the {\tt INSTEPn} files are explicitly bourne
shell scripts (or ksh or sh5 for Convex or Ultrix, respectively).  If
you come across this behaviour (and you shouldn't anymore) the simplest
solution to this is to get into a generic bourne shell (or C shell) by
typing {\tt sh} (or {\tt csh}) before starting the {\tt INSTEPn}
procedure (where {\tt n} is 2, 3, or 4).

Sometimes the generation of the {\tt .LIS} files goes wrong, and you end
up with an empty file.  If you find any of these, you should promptly
interrupt the {\tt INSTEP2} processing, remove the empty files and
restart (after you have checked for sufficient disk space on the
relevant filesystem --- and in {\tt /tmp}).

The values of {\tt BYTFLP}, {\tt SPFRMT}, {\tt DPFRMT}, {\tt TTYCAR}
as well as other system constants and parameters which are set in the
system-specific version of {\tt ZDCHI2} should be checked (see section
%%% @@@ keep this section reference current
3.3), if you are doing a port to a new system.  They are set correctly
for the already-supported architectures, although you may want to set
the Convex one accordingly; if you have IEEE hardware, use the {\tt
\$APLNRAO1} or {\tt \$APLVLAC1} version of {\tt ZDCHI2} instead of the
generic {\tt\$APLCVEX} version.

% @@@ does the above belong elsewhere?

{\tt INSTEP2} will cycle through all the major subroutine source code
areas in the following order: AIPSUB, APLSUB, APLOOP, APLGEN, YGEN,
YSUB, YNOT, APLNOT, QDEV, QSUB, QNOT, QOOP.  For each, it will execute
the procedure {\tt\$SYSUNIX/MAKEAT} to generate ``at'' files containing
lists of path names to all subroutine source code modules pertinent to
the host implementation.  For example, {\tt MAKEAT \$APLGEN} will
ultimately produce the file {\tt APLGEN.LIS} containing a list of all
the subroutine source code found in the directory {\tt\$APLGEN} and
below that is relevant to the host implementation.  The path names
selected are determined by the directory search paths defined in
{\tt\$SYSLOCAL/LIBR.DAT}.

The ``at'' files are then used by the procedure {\tt\$SYSUNIX/COMRPL}
to drive the mass compilation phase.  As each subroutine is compiled,
the resulting object module is staged to one or more {\tt\$LIBR}
subdirectories, again based on {\tt LIBR.DAT}.  For example, object
modules generated from {\tt\$APLGEN/}$\dots$\ subroutine source code
is staged to the proper {\tt\$LIBR} subdirectory defined for such
modules.  After all subroutines are complied for, say {\tt\$AIPSUB},
the procedure {\tt\$SYSUNIX/LIBR} is invoked to build an object
library ({\it archive\/} file in UNIX parlance) from all the object
modules found in the directory {\tt\$LIBR/AIPSUB}.  On Suns where you
have chosen to use shared libraries (\ie, created an empty file
{\tt\$SYSLOCAL/USESHARED}), the {\tt\$SYSLOCAL} version of {\tt LIBR}
is used instead; this generated both static ({\tt SUBLIB}) and shared
or dynamic ({\tt SUBLIB.so}) versions of the libraries.

If you are making debug libraries on a Sun, there is an extra area
{\tt\$AIPS\_VERSION/\$ARCH/LIBR\-DBG} that contains a parallel set of
directories to the {\tt\$LIBR} area.  Then each compilation is done
twice, first with any debug or no-opt settings overridden, then with
no-opt and debug and nopurge forced on the compile.  The first version
of the object file generated goes in the regular staging area and the
second (debug) version goes in the {\tt LIBRDBG/*/} area.  As the debug
compile is performed last, it also leaves the source code in the
{\tt\$PREP area} unless you override the settings in the usual
configuration files.  Note that the trigger for generating the separate
set of debug libraries is the presence or absence of the file {\tt
DOTWOBIN} in the {\tt\$SYSLOCAL} area, and that it is only currently
supported on Suns (including Solaris).

{\tt COMRPL} marks each successfully compiled file in the ``at'' files
by prefixing a dash ({\tt -}) to the name.  In the event of an
interruption (system crash, whatever) {\tt INSTEP2} can be restarted and
will resume with the next module as if nothing had happened.  {\tt
INSTEP2} will also stop whenever {\tt COMRPL} fails on a given module.
This allows you to investigate and take corrective action and resume the
process simply by running {\tt INSTEP2} again.  Alternatively, you could
edit the respective ``at'' file, marking the problem routine as done
(i.e., prefix {\tt -} to its path name), restarting {\tt INSTEP2} and
work on the problem routine later.  See also the {\it Known Problems\/}
chapter for those problems that you can ignore.  In particular,
corrective action should be taken before {\tt INSTEP2} finishes
processing the respective ``at'' file since its next step is to build
the respective object library.

The object libraries are built for single pass linking using unix
commands {\tt tsort} and {\tt lorder}.  That is, the ordering of the
object code in the library is such that the loader can resolve all
references in a single pass.  A missing object module can perturb the
single pass ordering.

The object libraries built by {\tt INSTEP2} via the procedure {\tt LIBR}
all have the same name, {\tt SUBLIB} (\eg, {\tt\$LIBR/AIPSUB/SUBLIB}).
For Suns and HPs, the shared libraries are located directly in the
{\tt\$LIBR} area itself with names like, \eg, {\tt APLSUB.so}.
{\tt INSTEP2} will also check for the existence of the {\tt SUBLIB} for
a given major subroutine source code area and if found, will {\it
completely\/} skip it, regardless of residual unprocessed path names in
the respective ``at'' file.  The reason for this is that, once the {\tt
SUBLIB} object libraries exist, the procedure {\tt LIBR} merely replaces
(or adds) object modules in the library without any consideration to
ordering.

If you find yourself in a situation where a given {\tt SUBLIB} was
built prematurely, simply change to the respective {\tt\$LIBR}
subdirectory, type {\tt ar x SUBLIB} (or equivalent) to extract all
object modules, and delete {\tt SUBLIB}.  Rerunning {\tt INSTEP2} will
cause any residual unprocessed subroutine path names in the respective
``at'' file to be processed and subsequently invoke the procedure {\tt
LIBR} to rebuild the object library with single pass ordering.

The procedure {\tt COMRPL} (compile and replace), despite its name,
never actually puts the object modules in the object libraries.  It only
stages the object module to one or more of the {\tt \$LIBR} (and
possibly {\tt \$LIBRDBG}) areas.  Object library updating is only done
either manually or by the procedure {\tt LIBR} (which is called if
needed by {\tt COMLNK}; see {\tt INSTEP3}).  Recall that the object
library lists for programs from the various program source code areas
are also defined in {\tt\$SYSLOCAL/LIBR.DAT}.  One of the design
features of {\tt LIBR} is that it locks the target {\tt SUBLIB} to avoid
collisions that often result in corrupted object libraries, if there are
multiple users performing compiles and links.  Most sites will not need
this feature.\medskip

\newsubsubsection{Device Names (Logicals)}

Since {\tt INSTEP2} can take quite a while to complete, while it's
grinding away is a good time to address the definition of device names
for the execution of \AIPS\ programs (if you have not done so
already).  The files {\tt AIPSASSN.CSH} and {\tt AIPSASSN.SH} are used
to define the \AIPS\ system device names in the form of environment
variables.  In older versions of \AIPS, there was an important site- and
host-specific section at the end of these files where tape drives and
other things were defined.  Now with {\tt 15JUL93}, the tape drives are
% @@@ update above as needed
defined in the {\tt TPDEVS.LIST} file so you no longer have to insert
them in the {\tt AIPSASSN} files.  

However, they are still useful if you need to define any of the
following: reserved terminals (optional), special task message
terminals (optional), and dedicated graphics terminals (optional).
These files are the best location for overriding default definitions for
things like the {\tt FITS} area, and temporary printing and plotting
areas. 

You should see a section that looks like this at the end of the {\tt
AIPSASSN} files:
\medskip

\fortran
#                                       Host specific definitions
#                                       ~~~~~~~~~~~~~~~~~~~~~~~~~
#                                       LWPRINTER?, TASKTTn, RESSTTn, 
#                                       TEKTKn, TAAC1, and modification
#                                       of any of the foregoing.
if [ "$SITE" = "NRAOCV" ] ; then
#                                       NRAO Charlottesville.  These
#                                       definitions are shown here only
#                                       for illustrative purposes.  You
#                                       should delete this section and
#                                       insert definitions appropriate
#                                       for your site. 
#                                       --------------------------------
    : This is _the_ standard site
#
#
elif [ "$SITE" = NRAOAOC ] ; then
#                                       NRAO Array Ops Ctr, Socorro, NM.

\endfortran\medskip

\noindent and so on.  If you need to perform any customization (and this
is unlikely), substitute your site name and host names for {\tt NRAOAOC}
and {\tt YUCCA}, \etc.
\medskip

\newsubsubsection{Data Areas}

There must be at least one user data area for \AIPS\ user data.  Since
the {\tt 15APR92} release, these areas are defined at \AIPS\ startup on
the fly, depending on the contents of {\tt \$NET0/DADEVS.LIST} and the
{\tt da=} option on the command line.  The former defines the data areas
(``disks'' in \AIPS\ parlance) and whether they are required or
optional.  The latter selects which areas in this file the user wants to
use for the duration of the \AIPS\ session.

There are ways of overriding or selecting a subset of the \AIPS\ disks
in the {\tt DADEVS.LIST} file; see below.  Also the file
{\tt\$NET0/NETSP} sets {\tt TIMDEST} (expiry time) limits and user
reservation numbers for the same disks.
override this information

The environment variable {\tt DA00} will be defined (by the {\tt
AIPSASSN.*} files) as the full path name of a directory where 
\AIPS\ ``system'' files are to be stored.  These are distinct from the
``user'' files in the data areas mentioned above and should not be
confused with them.  As outlined in section 2.3.10,
% @@@ make sure this reference is correct 
the {\tt INSTEP1} procedure will create this area as
{\tt\$AIPS\_ROOT/DA00/\$HOST} for each host.  

The {\tt DADEVS.SH} shell script is called by both {\tt START\_AIPS} at
\AIPS\ startup time, and by the {\tt RUN} shell script whenever one of
the standalone \AIPS\ programs such as {\tt FILAIP} is run.  It ({\tt
DADEVS.SH}) is what takes the {\tt da=} option, the current hostname,
and the {\tt DADEVS.LIST} file, and makes a list of data areas from
these inputs.  The method used to select disks assumes the hostname
where the disks are physically mounted is embedded in its name
somewhere, \eg, {\tt \$AIPS\_ROOT/DATA/FOOBAR\_1} for data area number
one on host {\tt foobar}.  Then, the disks selected for the user will
be:\medskip

\item{1)} Any ``required'' areas indicated by a $+$ in {\tt DADEVS.LIST}
\item{2)} Any areas containing the name of the local host; and
\item{3)} Additional areas selected by name, \eg, {\tt da=foobar}
\medskip

\noindent It is possible to set up host-specific versions of {\tt
DADEVS.LIST} by copying it to the {\tt\$DA00} area for a given host and
changing it, and it is even possible for a user to copy it to their
personal home area as {\tt .dadevs} and customize it.  The {\tt
DADEVS.SH} script looks first for the personal version, then for a
host-specific version, and only then will it use the site-wide version.

However, these practices have two disadvantages: (1) the administrative
overhead of changing the disk configuration increases linearly with the
number of such files (it's easier if you stick with one site-wide file);
and (2) users making their own {\tt .dadevs} files will be asking the
\AIPS\ manager to change the system-wide {\tt NETSP} file anytime they
change their private data areas (otherwise they cannot reserve these
areas for their own usernumbers and get the default {\tt TIMDEST} or
time destroy parameters).  Of course there are obvious advantages as
well.

It is best {\it not\/} to put the user data areas on the same file
system (partition, logical volume, disk, whatever you call it) as the
\AIPS\ distribution itself.  The latter will incorporate the system
files in {\tt \$AIPS\_ROOT/DA00/\$HOST/} and you do not want users
filling up this same file system and preventing the \AIPS\ accounting
file from expanding; this would make \ttaips difficult or impossible to
run.  Of course, you can always relocate the {\tt\$AIPS\_ROOT/DA00}
directory itself elsewhere, and put a symbolic link in its place
pointing at the new location.

For the user data areas, it is good practice to keep separate 
\AIPS\ disks on separate partitions (if you have more than one), except
if you create additional areas for separate projects or other
organizational reasons.  The first user data ``disk'' (what 
\ttaips\ says is ``disk 1'') is where certain user files are stored:
message files, save/get files.  For this reason, it may be desirable to
specify one (or more) ``required'' disks in the {\tt DADEVS.LIST} file
--- and make it clear to users who insist on their private {\tt .dadevs}
that they will be responsible for maintaining multiple copies of their
message and save-get files if they change the required disk(s) to
optional or remove them in the {\tt .dadevs} file.  Also, when (not if!)
space on disk 1 is exhausted, \AIPS\ usage can be impaired just as for
the system file area mentioned in the previous paragraph.
% @@@ is it still mentioned?

The network scheme \AIPS\ operates in has a convention where all data
disks (from number 1 up) on a given host are defined as {\tt
\$DATA\_ROOT/\$HOST\_n}.  For example, in NRAO's Charlottesville
setup, the workstation called {\tt lemur} has two disks, and the
entries in {\tt DADEVS.LIST} for it and the required {\tt polaris}
disk are:\medskip

\fortran
+  /DATA/POLARIS_1
-  /DATA/LEMUR_1
-  /DATA/LEMUR_2
\endfortran\medskip

\noindent The automounter is used at this site and the
{\tt\$DATA\_ROOT} is of course {\tt /DATA} which is also the name of
the automounter map that enables these disks on different machines to
be mounted on demand --- and dismounted after several minutes of
inactivity.  

The {\tt da=} option to the {\tt START\_AIPS} shell script will
typically generate something similar to this:\medskip

\example{baboon\%\ {\it aips da=lemur}}
\example{\rm (stuff about printer omitted here for clarity)}
\example{Data disk assignments:}
\example{\ \ \ Disk 1 is /DATA/POLARIS\_1}
\example{\ \ \ Disk 2 is /DATA/BABOON\_1}
\example{\ \ \ Disk 3 is /DATA/BABOON\_2}
\example{\ \ \ Disk 4 is /DATA/LEMUR\_1}
\example{\ \ \ Disk 5 is /DATA/LEMUR\_2}
\medskip

\noindent This example is run on a system called {\tt baboon} which has
two \AIPS\ disks or data areas.  The user has requested that the disks
from host {\tt lemur} be used as well, and in the NRAO--CV environment,
the {\tt polaris} disk is required and listed first in the {\tt
DADEVS.LIST} file.  The requirement for selection based on the {\tt da=}
arguments is that they ({\tt lemur} in the above example) be found in
the disk name (uppercased).  Also, the checking criterion is the
existence of the empty {\tt SPACE} lock file.  If it is not detected ---
for whatever reasons ---, the procedure simply says that disk is not
available and proceeds to try the next one.  Suppose {\tt BABOON\_1} had
been dismounted for some reason.  Then there would have been 4 disks
selected in the example above, and \AIPS\ internally would know them as
disks 1 through 4, instead of 1 through 5 and including the {\tt
BABOON\_1} disk.

When running \AIPS, users can set the adverb {\tt BADDISK} to prevent
scratch file creation on {\tt\$DA01} or any other disk.  There is an
\AIPS\ system parameter that allows only scratch files to be created on
a given disk.  Such a disk can be specified in {\tt \$NET0/NETSP} by
setting the first reserved user number as -1 (values in this file
override whatever is set via the {\tt SETPAR} program).  You may find it
useful to establish one or more such scratch disks in your 
\AIPS\ system.  Furthermore, the same system parameter can be set such
that only specified user numbers (up to 8 per disk) are allow to create
files (of any type) on a particular disk.  Note that currently {\tt
BADDISK} is restricted to at most 10 values; your users may want to
restrict the number of disks they include with the {\tt da=} option so
they can make use of the adverb.
\medskip

\newsubsubsection{Tape Drives}

\AIPS\ tape drives are numbered, not names, and referenced by the
\ttaips\ program via an integer parameter such as {\tt INTAPE}.  The
definition of all tape drives is centralized in one single file,
{\tt\$NET0/TPDEVS.LIST}.  A shell script ({\tt TPDEVS.SH}) is called by
various other scripts such as {\tt START\_AIPS} and {\tt
START\_TPSERVERS} to define environment variables which contain the
actual device names.  Normally, a user of \AIPS\ need never know these
device names.  Not so the installer, however$\dots$

Tape device names vary considerably from one system to another, and
there are many conventions for encoding low/high density, raw mode,
drive number \etc, on the many Unix systems \AIPS\ runs on.  As an
example, on a Convex, device {\tt /dev/rmt12} means the first drive on
the system, ``raw'' mode, no rewind on close (required modes for use
with \AIPS\ programs) and a density of 1600 BPI.  The device alias for
the same tape unit with the same properties except 6250 BPI, is {\tt
/dev/rmt16}.  On the other hand, on an IBM RS--6000, the same device
names would be {\tt /dev/rmt0.5} and {\tt /dev/rmt0.1} respectively.

The {\tt INSTEP1} procedure has fairly detailed commentary on the form
of tape device names for the major systems that \AIPS\ is already ported
to.  For new ports, you should look up the manual pages or equivalent
for such things as {\tt mtio}.  If all else fails, try {\tt man -k
tape}. 

The sample {\tt TPDEVS.LIST} file in {\tt\$SYSUNIX} (not the one copied
to your {\tt\$NET0} area) shows common device names for the 
architectures NRAO uses in-house.  Note that for most systems, the
norewind device is explicitly used (except for IBM RS6000/AIX, where the
``{\tt .1}'' is appended by the \AIPS\ mounting software).  In the case
of Suns (SunOS 4, not 5), it is also important to use the lowest number.
Example: for an Exabyte 8200 on a Sun, use {\tt /dev/nrst0} instead of
{\tt /dev/nrst8} even though they are essentially equivalent.  The
density selection algorithm inside \AIPS\ can get confused easily if you
fail to follow this advice.

Another feature that UNIX systems often lack is the notion of
``allocating'' a given tape drive to a specific user or process.  That
is, tapes can be read and/or written (unless write protected) by
anyone on the system as long as the drive is not already opened by
some other process.  Convex systems offer a VMS-like tape mounting
utility ({\tt tpmount} and {\tt tpqueue}) that we use to prevent
collisions.  \ttaips\ uses file locking on a temporary disk file to
attempt to implement this, but that does not protect against
collisions with non-\ttaips\ users.

In older versions of \AIPS, the ``verbs'' to issue software mounts or
dismounts were often unnecessary.  However, that is no longer the case.
The \AIPS\ Z (machine specific) routines that handle tape mounts ({\tt
ZMOUN2} in the various machine-specific directories) in most cases will
query the device and report back what it thinks is being mounted.  This
feedback can be beneficial to the user who mistakenly tries to mount the
wrong tape drive.  This Z routine will undoubtably require local
development if a tape allocation scheme (other than convex) is supported
on your system and you want to or must use it.  The Z-routines for Sun,
IBM, HP, Convex, and DEC should not require modification.  
\medskip

\newsubsubsection{Remote Magnetic Tapes}

The concept of remote tapes has been built into \AIPS\ itself in the
form of two adverbs that appear in the inputs list for the {\tt MOUNT}
command.  These are {\tt REMHOST}, the name of the remote host, and {\tt
REMTAPE}, the \AIPS\ tape number of the drive you want on that remote
host.  Note that the host name as input to \AIPS\ is necessarily
uppercased, but the Z routines will convert it to all lowercase before
it gets anywhere near the network (\ie, before the call to {\tt
gethostbyname()}).  There are two additional ``slots'' for remote tape
devices defined, \eg, a system with one local tape unit will have 
\AIPS\ tapes 2 and 3 for use as connections to remote tape drives.

To make this scheme work, two things are needed: a transport mechanism,
and a daemon or daemons at the remote end.  To this end, the {\tt TPMON}
task was created.  This is a standalone task that is started by the {\tt
START\_TPSERVERS} shell script (it calls an intermediate script but that
is not relevant here).  This task uses Berkeley Sockets to communicate
over a TCP/IP network; the sockets are names {\tt AIPSMT0}, {\tt
AIPSMT1}, and so on.  Most if not all System V flavors of Unix that we
have ported \AIPS\ to in recent years do support some form of Berkeley
sockets, hence the Z routines for dealing with them are in the
{\tt\$APLUNIX} area.

To find out how many of these sockets you will need, pick the host with
the most tape drives (say 4).  Add one to this (for FITS disk access
across the net) and this is the total number of service names you need,
in the example here, 5.  Then you want to add these to either the {\tt
/etc/services} file, or the YP/NIS master version of the file if that is
how your network supplies it (we do).  Here is a typical services list:
\medskip

\fortran
AIPSMT0         5010/tcp                  # AIPS remote tapes
AIPSMT1         5011/tcp
AIPSMT2         5012/tcp
AIPSMT3         5013/tcp
AIPSMT4         5014/tcp
SSSIN           5000/tcp                  # AIPS TV server inet sockets
msgserv         5008/tcp        MSGSERV   # AIPS Message Server
tekserv         5009/tcp        TEKSERV   # AIPS TekServer
\endfortran
\medskip

\noindent (note the presence of the required TV server, tektronix
graphics, and message server sockets too).  We recommend that you try
and use these service numbers if possible; this may prove useful if you
ever need us to log in to your system remotely to fix a problem (we can
then get your system to use our local TV and tek servers, or vice versa,
which might be invaluable).

The way remote tapes now work is that there will be $n+1$ instances of
{\tt TPMON} started up on each host, where $n$ is the number of tape
drives on the system.  The first one will handle remote requests for
access to {\it FITS\/} disk files.  The second one handles requests for
\AIPS\ tape drive 1, the third for tape 2, and so on.

These {\tt TPMON} ``d\ae mons'' will get started on the local host for
the first time when \AIPS\ is started for the first time.  Thereafter, a
startup of \AIPS\ will cause the system to check if they are still
running; if some are missing, they will be restarted.  You can also have
them start at boot time by having your sysadmin insert a call to {\tt
AIPS.BOOT} in the {\tt /etc/rc.local} or equivalent file; this should be
run as your \AIPS\ account, {\it not\/} as root.

Users can, with the {\tt tp=} command-line option, have the system issue
a command (using {\tt rsh}, or {\tt remsh} on HP's) to a remote host to
make sure the {\tt TPMON} daemons are running.  This is usually to give
the user peace of mind that the d\ae mons on the remote host are indeed
working, and that there won't be any breakdown in socket communication.
As mentioned above, on each host there will be two additional tape
``drives'' defined as {\tt REMOTE} listed in the startup messages.  This
allows up to two local users to access one remote tape drive each, or
one user access to two remote tape drives.

As stated in the previous section, the use of the {\tt MOUNT} command is
{\bf required}; you should inform the \AIPS\ users of this (it was not
always required in older versions, and old habits die hard).  This
applies to both local and remote tape drives.  After a remote tape drive
has been mounted, the I/O to it is performed via the sockets and {\tt
TPMON} which of course uses the \AIPS\ Z routines on the host in
question.  So remote tapes are supported for any machine that runs
\AIPS\ and has a working set of tape Z routines.

In the {\tt 15OCT92} version of \AIPS, the tape related Z routines for
Suns (Sun-supplied SCSI Exabytes and HP DAT), Convexes (9-track), IBM
RS/6000's (IBM Exabyte, IBM and HP 9-track, and HP DAT --- with AIX
3.2), and DecStations (TK50, maybe Exabyte too?) were overhauled and
many bugs have been eliminated.  Well, we did it again for {\tt
15JUL93}, improving robustness, eliminating bugs, doing as much testing
as we possibly could on the equipment at our disposal, and more.  We
also added support for Solaris 2.x and HP, though we could not perform
testing on the latter.  On Suns with HP DAT drives, we had to patch the
kernel to make sure the system knew that DAT drives were capable of
backspacing; this was apparently not the default so be wary.  

Also, be careful of third party drives; while many of these are perfect
plug-compatible replacements for what the workstation vendors offer,
sometimes they are marketed on the assumption that you will only ever be
using {\tt tar} or {\tt dump} or {\tt backup}\footnote*{\eightpoint
% this comment to aid in reformatting
        On IBM RS/6000 systems, some Exabyte 8500 systems from third
        party vendors cannot be recognized by AIX as dual-density
        drives, for example (SMIT will tell you it's an 8200).  AIPS
        will allow you to force high density settings on 8200's on IBMs
        precisely for this reason.  There are many other horror stories,
        so be careful out there!}.
\AIPS\ is a very tough test of any tape drive and relies on being able
to backspace by file and record (block).

\medskip

\newsubsubsection{Reserved Terminals}

An \AIPS\ feature that you may or may not want (probably not) to take
advantage of is the concept of reserved terminals.  This is a terminal
that is reserved for {\tt AIPSn} (\eg, {\tt AIPS1}) use.  Historically,
such terminals were near an old-style TV display or graphics terminal
and \AIPS\ has the ability to increase the priority (or niceness, in
Unix parlance) of the {\tt AIPS} tasks running on such a reserved
terminal.  This feature (elevated priority) has not been used at NRAO
for some time, and the use of dedicated \AIPS\ reserved terminals only
survives on our last remaining convex (yucca) at the AOC site.  Yucca is
destined for mothballing some time in 1993 at which time we will have no
reserved terminals left at any NRAO site (we have reserved workstations
instead!). 

The environment variables {\tt RESSTT1}, {\tt RESSTT2}, \etc, are used
to specify which terminals are ``reserved''.  These are purely optional
and can be added later simply by defining them in your {\tt
AIPSASSN.CSH} and {\tt AIPSASSN.SH} file.  Note that there are two
examples of reserved terminals in the NRAO site-specific examples in
these files in the {\tt NRAOAOC} section for host {\tt YUCCA}.

Unfortunately, reserved terminals must have a specific and fixed device
name, which preculudes the use of most windows on workstations as
reserved terminals.  It would be possible to implement a scheme similar
to {\tt TEKSERVER} for this purpose, but there has been little interest
expressed in this possibility at this point in time.\medskip

\newsubsubsection{Message Terminals}

As in the case of reserved terminals, the use of message terminals is
also purely optional.  These are terminals that are devoted to
displaying the messages from \AIPS\ tasks that are running as
subprocesses (``child'' processes).  These are normally associated
with reserved terminals.  The environment variables {\tt TASKTT1},
{\tt TASKTT2}, \etc, specify the device names.

This may be a luxury that you cannot afford since it requires that the
terminal be connected to a port, but taken out of the interactive group.
This makes it otherwise useless.  However, it doesn't have to be a very
smart terminal.  In fact, at NRAO we used recycled and otherwise
obsolete terminals as \AIPS\ message terminals.  Nevertheless, these
terminals still tie up a port.  Like reserved terminals, message
terminals can be added later by simply defining them in your {\tt
AIPSASSN.SH} and {\tt .CSH} files.  Like reserved terminals, they have
to be fixed device names.  

However, there is a software/X11 equivalent of message terminals
described in the next section.\medskip

% @@@ move above to after next section?  Needs reorganized sometime

\newsubsubsection{MSGSRV and TEKSRV, the Message and Graphics Servers}

In addition to the {\tt XAS} imaging server, \AIPS\ provides two
additional windows in an X11 environment (including OpenWindows, Motif,
DecWindows, HP VUE, \etc).  These are {\tt TEKSRV}\footnote*{\eightpoint
                                           Originally called TEKSERVER},
% placeholder comment
a graphics server, and {\tt MSGSRV}, a server for \AIPS\ messages from
tasks.  These are modelled after the early \AIPS\ VAX and Convex setups,
where there were dedicated terminals for messages and graphics.

However, with the wide availability of networked windowing systems,
these virtual counterparts of the early dedicated terminals can accept
input from more than one \AIPS\ session, and they are not restricted to
either the host the underlying client programs are running on, or the
display host that the X server runs on.  The way in which this is
achieved is via internet sockets using the {\tt tekserv} and {\tt
msgserv} services which were shown in the above example of the {\tt
etc/services} file or YP/NIS services map.

{\tt TEKSRV} serves as the graphics tablet for the \AIPS\ sessions that
a user originates on any hosts in the \AIPS\ network from the
workstation that the user sits in front of.  Any tek-related commands
such as {\tt TKSL} will cause the graphics to appear in the window.
Note that {\tt TEKSRV} uses the tektronix-emulation feature of the
standard X11 {\tt xterm} client (which also has vt100 emulation; text
and graphics appear in two separate windows).

{\tt MSGSRV}, the message server, 
% @@@ change as appropriate
is being released for the first time in the {\tt 15JUL93} release.  It
% @@@ change as appropriate
serves as a collection point for the messages from {\it tasks\/} that
are started from within \AIPS.  In fact, it can receive messages from
many \AIPS\ sessions simultaneously, and in most cases it is able to tag
the messages with the host from which they originate.

When the {\tt XAS} server is started for a given \AIPS\ session, the
message and tektronix servers are also started.  Hence a given message
server or tek server is always associated with the matching TV number as
assigned by {\tt TVDEVS.SH} based on the list in {\tt HOSTS.LIST}
(possibly supplemented with hardware TVs in {\tt TVDEVS.SH}).  The
programs are started by the {\tt XASERVERS} shell script.  By default
they use the {\tt xterm} terminal emulator, but of course any reasonable
terminal emulator can be used for {\tt MSGSRV}, \eg, decterm, hpterm,
cmdtool, or aixterm.  For {\tt TEKSRV} however, none of these other
than {\tt xterm} will do, as they lack the tektronix emulation and
cannot display graphics.  It is a good idea to get your \AIPS\ users
familiar with the two faces of {\tt xterm} before they are exposed to
{\tt TEKSRV} by holding the control key down and pressing the middle
mouse button to see the {\tt xterm} menu relevant to tektronix graphics.

It is possible to specify, via environment variables, which terminal
emulator you want.  The relevant variables are:\medskip

{\ndot {\tt AIPS\_TEK\_EMULATOR}, default {\tt xterm}}
{\ndot {\tt AIPS\_MSG\_EMULATOR}, default {\tt xterm}\medskip}\medskip

\noindent You can set either of these to the string {\tt none} and this
will inhibit the indicated server from ever starting.

Unlike its sibling {\tt TEKSRV}, there has been no attempt made to
retrofit the {\tt MSGSRV} functionality into {\tt SSSERVERS}, given that
SunView is not available in Solaris version 2 and the widespread use of
OpenWindows and X11 on Suns.  Sites that are still running SunView are
strongly advised to consider using either generic X11 (preferably
release 5 or 4), or OpenWindows version 2 or 3, in its place.

The {\tt TEKSRV} and {\tt MSGSRV} environment variables {\tt TKDEV},
{\tt TKDEVnn}, {\tt TTDEV} and {\tt TTDEVnn}, are set automatically at
startup time by the \AIPS\ scripts (as are the {\tt TVDEV} and {\tt
TVDEVnn} variables).  Note that there is now support for up to 240 TV,
tek, and message servers for any one \AIPS\ site, as well as up to 15
``remote'' (\ie, tektronix-compatible graphics) terminals (241 through
255).

When a user starts up \AIPS\ from a properly configured workstation
running X, the XAS TV, {\tt TEKSRV} graphics and {\tt MSGSRV} message
windows should pop up automatically.  If you have not set any X
resources for these windows, they will probably all pile on top of each
other on the top left of the screen, though this will depend somewhat on
your window manager.  It is possible to override such things as
position, font, geometry, foreground and background colors, icon
location, and so on using resources {\tt AIPSmsg} and {\tt AIPStek}.
Here is an example of these, and additional {\tt AIPStv} resources, from
the author's personal {\tt .Xdefaults} file, with additional annotation
explaining some features:\medskip

\fortran
!
! AIPS: AIPStv for XAS, AIPSmsg for MSGSRV, AIPStek for TEKSRV.
!                                       inhibits shared memory if zero:
AIPStv*useSharedMemory: 1
!                                       Don't use as many colors
AIPStv*maxGreyLevel:    189
!                                       Initial location and size
AIPStv*geometry:        518x518-0-125
AIPStv*iconGeometry:   +635+100
AIPStv*cursorShape:     30
!                                       Cursor and Graphic plane colors
AIPStv*cursorR:          0
AIPStv*cursorG:        255
AIPStv*cursorB:        255
AIPStv*graphics1R:     255
AIPStv*graphics1G:     255
AIPStv*graphics1B:       0
AIPStv*graphics2R:      16
AIPStv*graphics2G:     255
AIPStv*graphics2B:       0
AIPStv*graphics3R:     255
AIPStv*graphics3G:     171
AIPStv*graphics3B:     255
AIPStv*graphics4R:       0
AIPStv*graphics4G:       0
AIPStv*graphics4B:       0
!                                       Message Server defaults
AIPSmsg*background: maroon
AIPSmsg*foreground: bisque
AIPSmsg.vt100.geometry: 81x24-0-0
AIPSmsg*iconGeometry: +780+100
AIPSmsg*iconName: MSGSERV
AIPSmsg*pointercolor: red
AIPSmsg*savelines: 500
AIPSmsg*scrollBar: True
AIPSmsg*tekInhibit: True
!                                       TekServer defaults
AIPStek*background: navyblue
AIPStek*foreground: yellow
AIPStek*scrollBar: off
AIPStek*iconGeometry:    +710+100
AIPStek*iconName:        TEKSERV
AIPStek*pointercolor:    red
AIPStek*tekGeometry:      768x585
\endfortran
\medskip

\noindent Most of the keywords shown above are self-describing.  For
additional details, see the help files for {\tt TEKSERVER}, {\tt
MSGSERVER}, and {\tt XAS} in {\tt\$HLPFIL}, or just type, \eg, {\tt HELP
MSGSERVER} from within \ttaips.

Finally, while it is possible to use {\tt TVPL} to plot graphics in the
overlay planes of the TV servers, there is an order of magnitude speedup
in plotting that results from using {\tt TKPL} and the {\tt TEKSRV}
window instead. \medskip

\newsubsubsection{Graphics Terminals}

In AIPS, a {\it graphics\/} terminal means a Tektronix 4010/4012
compatible device.  Among the possible command line arguments to the
\AIPS\ startup procedure is the {\tt REMOTE} option, which will define
the user terminal as the device for graphics terminal I/O.  If \AIPS\ is
started up with this option and any {\tt TK*} verbs or tasks are
executed, the user terminal will be used for graphics terminal I/O.
Many Tektronix emulation terminals, such as retrographics, visual 102G,
Selanar, \etc, can be used in this way.  \AIPS\ tek devices 241 through
255 are set aside for remote use and are pre-defined in the shell
scripts as shipped; no customization should be necessary.

Alternatively, independent graphics terminals may be defined.  As in
the case of message terminals, the physical graphics terminals defined
in this way must be taken out of the interactive group and are
otherwise dumb devices.  The files {\tt AIPSASSN.SH} and {\tt .CSH}
define these in the site- and host-specific section at the end.
The relevant names are {\tt TEKTKn} where the {\tt n} corresponds to a
reserved terminal; the scheme assumes that dedicated graphics
terminals are associated with a dedicated reserved terminal for
\AIPS\ use (see above).

The use of these features will be ``slim to none'' in a workstation
environment, as the various screen servers (TV, tek, message) will make
their use unnecessary.  However, they have their uses in setups where
extensive use is still made of the types of graphics terminals mentioned
above. 
\medskip

\newsubsubsection{TV Display Devices}

All TV servers, including workstations that will use XAS (or SSS),
should be defined in your {\tt HOSTS.LIST} file.  As {\tt INSTEP1}
should have configured this file for you, it should not be necessary to
modify this file yourself, except to add additional \aips\ or tv hosts,
tv servers, or tv displays.
% @@@ edit as needed below
With the {\tt 15JUL93} release, this is a new feature, as the {\tt
TVDEVS.SH} file had to be modified in previous releases.
% @@@ edit as needed above
The only exception to this is for ``hardware'' TV devices such as the
IIS, IVAS, and DeAnza image displays.  These devices need to be defined
in a site- and host-specific section in {\tt TVDEVS.SH}.  There is a
sample section in this file for {\tt YUCCA} at the {\tt NRAOAOC} site
that defines the IIS model 70 tv for our last remaining Convex at the
AOC.  Refer to the file and its comments for additional details.
% @@@ is that a cop-out?  Need to show it here?
However, for such hardware devices, you will have to define two
environment variables:
\medskip

\item{$\bullet$} {\tt TVHOSTS} which defines the hardware TV's in the
                  traditional \AIPS\ sense, \eg, {\tt yucca+iis} for an
                  IIS display {\tt /dev/iis} on host {\tt yucca}; 
\item{$\bullet$} {\tt TVALTS} which lists all types of hardware TV
                  device used, and the corresponding {\tt <loadnumber>}
                  (see section 2.4.5), \eg {\tt iis:2}. 
%%% @@@ keep section reference current
\medskip

\noindent For additional details, you should read the comments at the
top of {\tt TVDEVS.SH}.  Note that you need to create image catalogs for
all TVs defined in {\tt HOSTS.LIST} {\it and\/} the {\tt TVHOSTS}
environment variable in {\tt TVDEVS.SH}.  These are set up for you when 
you {\tt RUN FILAIP} and then call the shell script {\tt SYSETUP}.

The maximum number of TV devices for a single \AIPS site is 255,
although the number of {\tt TEKSRV} windows is restricted to 240 (see
section above on graphics terminals).  The scheme of having a double
level of indirection (where the source code effectively does a {\tt
getenv(getenv("TVDEV"))} to get the actual TV name) has been preserved,
but the installer no longer has to specify these apart from the {\tt
HOSTS.LIST} file; the {\tt TVDEV} and {\tt TVDEVxx} names are defined
automatically on \AIPS\ startup.

It may be worth consulting \AIPS\ memo 74 to get an understanding of the
ATNF setup, most of which has been incorporated into \AIPS\ as of {\tt
15APR92}.  At the time of writing, the old \AIPS\ memo 66 is badly in
need of a rewrite and should probably not be consulted as it can be very
misleading in the context of the {\tt 15APR92} and later \AIPS\ releases.
\medskip 

\newsubsubsection{Batch Error Terminal/File}

If you elect to have \AIPS\ batch streams (\ie, where jobs run
sequentially with lower execution priority), a provision should be made
for catastrophic error logging.  The environment variable {\tt
BATCH\_OUT} should be defined as either a terminal or a simple disk file
for this purpose.  The system console may be a good choice, but a simple
disk file will do just as well.  This is defined in {\tt AIPSASSN.SH}
and {\tt .CSH} and defaults to {\tt /dev/console}. 
\medskip

\newsubsubsection{Printers and Plotters}

The printer setup is now (almost) completely specified in the file
{\tt PRDEVS.SH} in the {\tt\$AIPS\_ROOT} directory.  As shipped, this
file --- or the relevant part of it --- looks like this:\medskip

% @@@ insert latest version here
\fortran
#-----------------------------------------------------------------------
# PRDEVS.SH -- Define AIPS Printer devices
#-----------------------------------------------------------------------
# The format of this file is fairly simple and self-explanatory.  For
# customization, set the variables accordingly for your site.
#
# If you set the BIGPRINT variable, jobs larger than BIGTHRESH lines
# (default 1000 if BIGTHRESH is not set) get diverted to the BIGPRINT
# printer regardless of what printer the user requested.
#-----------------------------------------------------------------------
#                                       Number of printers
LPDEVS=4; export LPDEVS
#                                       For each printer, specify its 
#                                       name, a description and its 
#                                       type.  The name is its printcap
#                                       entry (what you type for xxx in
#                                       "lpr -Pxxx file"), the type is
#                                       one of QMS (for printers that 
#                                       use QUIC, i.e. QMS and Talaris),
#                                       PS (postscript), PREVIEW for 
#                                       pageview or ghostscript screen
#                                       previewers, or TEXT for other 
#                                       plain text printers.
#
#                                       Sample setup is shown here ONLY
#                                       for illustration.  Change it!
#                                       Remove next line when done.
echo "Edit $AIPS_ROOT/PRDEVS.SH for your site"
#
#                                       Big printer for large jobs.
#                                       This should be a printer NUMBER.
#                                       Remove BIGPRINT/BIGTHRESH to
#                                       disable this feature.
BIGPRINT=1; export BIGPRINT
#                                       jobs with more than this number
#                                       of lines get sent to BIGPRINT
#                                       regardless of what printer is
#                                       chosen on startup.
BIGTHRESH=1000; export BIGTHRESH
#                                       EXAMPLE printers only!
#                                       Printer 1, suppose it's a QMS
LPDEV1=lp; export LPDEV1
LPDESC1="The QMS printer in the computer lab"; export LPDESC1
LPTYPE1=QMS; export LPTYPE1
#                                       Printer 2, say a postscript
LPDEV2=ps; export LPDEV2
LPDESC2="Postscript printer in Astro room"; export LPDESC2
LPTYPE2=PS; export LPTYPE2
#                                       Printer 3, say a previewer
LPDEV3=pageview; export LPDEV3
LPDESC3="Sun OpenWindows PAGEVIEW previewer"; export LPDESC3
LPTYPE3=PREVIEW; export LPTYPE3
#                                       Printer 4, the GNU PS previewer.
#                                       Note ZLASCL looks for programs
#                                       "ghostview" or "gs" in the $PATH
LPDEV4=ghostscript; export LPDEV4
LPDESC4="GNU Ghostscript/Ghostview X-windows previewer"; export LPDESC4
LPTYPE4=PREVIEW; export LPTYPE4
#                                       Default is the first printer.
LPDEV=LPDEV1; export LPDEV
\endfortran
\medskip

\noindent
The shell scripts {\tt ZLASCL} and {\tt ZLPCL2}, formerly where you had
to do this sort of customization, are now very general and the only
things they need to know about are (1) the name and location of {\tt
fpr} or {\tt asa} or an equivalent filter to process fortran carriage
control characters, and (b) the name and location of a
text-to-postscript filter such as {\tt lwf}, {\tt mp}, or {\tt pstext}.
These three are all public domain and can be obtained from several ftp
archives on the internet; contact your local computer/network guru for
details on what you have and/or what you can get.  See the comments at
the top of the two shell scripts (in {\tt\$SYSUNIX}) for more details.

If your PostScript printer can handle plain text sent directly to it via
the {\tt lpr} or {\tt lp} command, then you should specify {\tt cat} as
the text-to-postscript filter in {\tt ZLPCL2}.  Usually, such print
queues have an internal filter that detects non-postscript files, and
does a sensible conversion on them before sending them to the printer.
Some experimentation may be in order as the \AIPS\ printed output may
assume a wide (130 or so columns) printer.

These shell scripts now completely handle the dispensing of the text
and graphics files to the appropriate printers.  The types of printer
known are {\tt TEXT}, {\tt PS} for postscript, {\tt QMS} for QUIC
printers (QMS, Talaris), and {\tt PREVIEW} which is a special class
that allows you to use a postscript previewer instead of a printer for
your graphical output. 

The printer selection is achieved in one of two ways.  If there is
only one printer specified in {\tt PRDEVS.SH}, then of course that has
to be ``the'' printer.  If there are more than one, however, the
default action is to pop up a menu to the user at \AIPS\ startup,
using the {\tt LPTYPEn} descriptions, and ask for a number.
Alternately, users can use the {\tt pr=<n>} command line option when
starting \AIPS\ to select a printer by number and bypass the menu.

Once a printer has been selected, the shell scripts will handle text
and graphics output in the most sensible way.  Suppose the user
selected a PostScript printer.  Then any text (such as {\tt PRTMSG}
output) will be filtered through the text-to-postscript filter
specified in {\tt ZLASCL} and spooled to the appropriate printer.  Any
PostScript graphics (from {\tt LWPLA}) will be sent directly without
any filtering.  Finally, if QMS output is detected (such as the output
of {\tt QMSPL}), the script emits an error message and looks at the
list of printers to see if there is a QMS printer defined anywhere.
If it finds one, it sends the QMS graphics file to that printer with
another warning message sent to the user.  This scheme also applies if
the user has selected a text or QMS printer and some QMS or postscript
output is detected.

% @@@
For the {\tt 15JUL93} release, there are a couple of new features
available for printing.  First of these is the ability to force large
print jobs to go to a designated printer.  This is used extensively at
the AOC site to prevent too many hundred-page listings from tying up the
smaller postscript printers and using a fast line printer for them
instead.  By setting the variables {\tt BIGPRINT} and {\tt BIGTHRESH},
you can enable this feature, and by {\it not\/} defining them, you can
inhibit it.  The former variable is the number of the ``big'' printer,
and the latter is the number of lines (calculated by {\tt wc}) that is
the maximum for the other printers.

% @@@
The second new feature for {\tt 15JUL93} is the addition of color
PostScript.  If you have a color PS printer, you can set its type to
{\tt PS-CMYK} in the {\tt PRDEVS.SH} file instead of just plain {\tt
PS}, and the script will then be able to catch color output (such as
from the new task {\tt TVCPS} and send it directly to the color printer.
Conversely, monochrome output, \eg, from {\tt LWPLA}, accidentally
directed at a color printer will be caught and directed to the first
listed regular (non-color) PS printer.

Laser printers are the best supported plotting devices in \AIPS.
Tasks exist for generating graphics output for a variety of laser
printers and graphics languages including {\tt QMSPL} (QMS or Talaris,
QUIC language), {\tt LWPLA} (LaserWriter/PostScript) and {\tt CANPL}
(Canon LBP--8).  Note that there is no support in the {\tt
ZLASCL/ZLPCL2} and {\tt PRDEVS.SH} scheme for Canon printers.  This
would have to be added by a site with a Canon printer (obviously).
{\tt QMSPL} and {\tt CANPL} make use of the {\tt ZLAS*} routines to
create, open, close and dispose laser printer output files. 

A task still exists that has fallen into disuse at NRAO but still may be
useful at other \AIPS\ sites.  It is called {\tt PRTPL} and it calls a
subroutine {\tt ZDOPRT}.  Several versions of {\tt ZDOPRT} can be found
in {\tt\$APLVMS} for various printer-plotter devices (\eg, Versatec,
Printronix).  The {\tt ZDOPRT} routines {\it will require local
development for Unix systems\/} since NRAO has never had such devices on
any of its Unix \AIPS\ systems, past or present.

Alternatively, if you have a (non-PostScript) laser printer with
graphics capability, you may want to use the task {\tt QMSPL} and the
{\tt ZLAS*} routines as models for a task to exploit it.  Some
modification to the {\tt PRDEVS.SH} file and the {\tt ZLASCL} and {\tt
ZLPCL2} scripts will then be needed.  \medskip

\newsubsection{Installation Step 3}

\newsubsubsection{Running INSTEP3}

The {\tt INSTEP3} procedure tends to be fairly short, typically taking
from 10 minutes to over an hour, depending on the computer and compiler.
It is quite significantly shorter than {\tt INSTEP2}.  To initiate {\tt
INSTEP3}, simply type:
\medskip

\example{INSTEP3}\medskip

\noindent As with {\tt INSTEP2}, it is vital that the programming
``logicals'' be defined {\it before\/} you start it.  The purpose of
{\tt INSTEP3} is to compile a selected subset (about 20) of all the
possible programs in the \AIPS\ system (approximately 300 and still
growing).  They are also linked one or more times with one or more
object library lists as determined by {\tt LIBR.DAT} (for multiple TV
types or AP types).  The resulting executable modules are moved to the
appropriate {\tt\$LOAD} (or {\tt\$LOADn}) directory.  The subset
represents:\medskip

\item{$\bullet$} the stand-alone program {\tt FILAIP} which creates
        the \AIPS\ system files and initializes all but the POPS
        memory files;
\item{$\bullet$} the stand-alone program {\tt POPSGN} which initializes
        the POPS memory files that are created by {\tt FILAIP};
\item{$\bullet$} the stand-alone programs {\tt SETPAR} (general) and 
        {\tt SETTVP} (TV oriented) for setting values in the system 
        parameter file created by {\tt FILAIP};
\item{$\bullet$} the system specific \AIPS\ startup program {\tt
        ZSTRTA}; 
\item{$\bullet$} the tasks {\tt DISKU} and {\tt NOBAT};
\item{$\bullet$} the subset of tasks originally known as the {\it
        Dirty Dozen\/} which includes UVLOD, IMLOD, UVSRT, UVMAP,
        COMB, APCLN, SUBIM, CCMRG, ASCAL, MX, VTESS, PRTAC, UVDIF 
        and FITTP; and
\item{$\bullet$} tasks TPMON, TEKSRV, and MSGSRV.
\medskip

\noindent {\tt INSTEP3} begins by double-checking that the source code of
these programs exists, and building an ``at'' file called {\tt
INSTEP3.LIS} containing the source code path names.  It then drives the
shell script {\tt COMLNK} which in turn compiles the programs and links
the resulting object module with the {\tt\$LIBR/*/SUBLIB} files as
prescribed in {\tt\$SYSLOCAL/LIBR.DAT}.
\medskip

\newsubsubsection{Running FILAIP}

Once {\tt INSTEP3} has completed, you will need to execute (in this
order) {\tt FILAIP}, {\tt POPSGN} and {\tt SETPAR}.  For those systems
with hardware TV display devices it will be necessary to execute {\tt
SETTVP} as well (it's not necessary for the screen servers); however,
this can wait until you are ready to actually load images to the device
(but should be done before running the {\tt SYSETUP} script).  To
execute {\tt FILAIP}, simply type:\medskip

\example{RUN FILAIP}

\medskip\noindent
The generic procedure {\tt RUN}, which resides in the directory
{\tt\$SYSUNIX}, is simply an aid to running (via an {\tt exec}
command) the various standalone tasks outside of {\tt AIPS} and {\tt
BATER}.
% @@@
As of {\tt 15JUL93}, the procedure will call the {\tt HOSTS.SH}, {\tt
AIPSPATH.SH}, and {\tt AIPSASSN.SH} files in the {\tt \$AIPS\_ROOT}
area.  It also calls the {\tt DADEVS.SH} file in {\tt \$SYSUNIX} so that
all the data areas are defined.  For most programs, it's just the first
data disk that matters, but {\tt RUN} does support the {\tt da=}
argument in exactly the same way as the {\tt START\_AIPS} script, if you
should need this.

It uses the environment variable {\tt\$AIPS\_VERSION} to find the file
(in the {\tt LOAD} subdirectory of same).  To change \AIPS\ versions,
use {\tt\$CDOLD}, {\tt\$CDNEW}, and {\tt\$CDTST} prior to running these
programs. 

It is essential that you make sure the \AIPS\ ``disk 1'' area, reported
by {\tt RUN} as it starts up, exists and is writable by the installation
account.  While most of the files will be created in the host-specific
system area {\tt\$DA00}, one (the message file for user 1) has to be
created in {\tt\$DA01}.  If there is already a message file for user 1
there, {\tt FILAIP} will not overwrite it.

If you are running {\tt FILAIP} for the first time, it will emit a brief
copyright notice.  Then it asks you for the number of disks and catalog
entries per disk.  The number of disks gets overridden via the {\tt
DADEVS.SH} file (it sets {\tt NVOL} as the number of disks), so just
enter 15 (the maximum you can have in any one \AIPS\ session).  It is
highly recommended that you use private catalogs by negating the number
of catalog entries.  Otherwise, all \AIPS\ users will share one (very
large) catalog which is a single point of failure.  Also, catalogs are
extensible so the number itself is not critical.\medskip

\fortran
# disks, # cat entries/disk (<0 => private catlgs) (2 I)
15 -100
\endfortran

\medskip\noindent Next, you will be asked the maximum number of
simultaneous \AIPS\ users allowed (up to 12), as well as the number of
\AIPS\ batch queues (if any) you want. \medskip

\fortran
# interactive AIPS, # batch queues (2 I)
8 2
\endfortran

\medskip\noindent Each \AIPS\ session, interactive or ``batch'', has
its own unique memory file to store values of adverbs and other things,
and {\tt FILAIP} needs to know how many of these to create.  They are
created in {\tt\$DA00} which is of course host-specific.  Once you
create them for one system, you can use {\tt SYSETUP} to copy them to
all other hosts of the same architecture, after you copy some of them 
to a template area first: {\tt cp [ABMST]*
\$AIPS\_VERSION/\$ARCH/TEMPLATE/}; see the section below on ``{\it
Setting up a Template Area}'').  The ``POPS'' number of your
\AIPS\ session will match the memory file you get.  The number created
is always the sum of the interactive \AIPS\ and batch queues $+ 1$, so
in the above example 11 memory files will be created.  You can have a
maximum of 15 (hex {\tt F}) memory files.  It is hard to expand the
number of memory files later so be generous with these parameters.  You
can always use {\tt SETPAR} (below) to restrict these numbers later.

Since the {\tt 15APR92} release, the memory file has been split in two.
The first part is independent of ``POPS'' number or \AIPS\ session and
it is stored in {\tt\$AIPS\_VERSION/\$ARCH/MEMORY/MEC00001;1}.  The
other part is dependent on the POPS number and so there are more than
one of them.  They are stored in the host-specific system area
{\tt\$AIPS\_ROOT/DA00/\$HOST/MEC0000n;1} where the {\tt n} will be the
hex number from one to whatever.  {\it Both of these areas and the files
in them must be writable by anyone who will use your \AIPS\ system\/}.

The next two questions ask how many TV (image display) and graphics (tek
or TK) devices you want to set up, and how many tape drives you want to
use.  These should correspond to the numbers of (a) AIPS hosts plus TV
servers defined in {\tt HOSTS.LIST}, (b) 255 for the number of graphics
devices, and (c) the maximum number of tape drives on any of your hosts
plus 1 (for now):
\medskip

\fortran
# TV, # TK devices (2 I)
10 255
# tape drives (I)
4
\endfortran

\medskip\noindent
If you specified one or more TV's, you will be asked for some basic
information on each TV, \eg:\medskip

\fortran
Image device No. 1 #gray, #graph, #img/gray, #ISUs (4 I)
4 4 64 0                        (this is for an IIS)
Image device No. 2 #gray, #graph, #img/gray, #ISUs (4 I)
3 4 256 0                       (this is for an IVAS)
Image device No. 3 #gray, #graph, #img/gray, #ISUs (4 I)
2 4 256 0                       (this is for a TV server)
Image device No. 4 #gray, #graph, #img/gray, #ISUs (4 I)
2 4 256 0                       (this is for a TV server too.)
Image device No. 5 #gray, #graph, #img/gray, #ISUs (4 I)
2 4 256 0                       (so is this.  Yeah, it's tedious)

(inputs for 6 through 10 omitted for sanity)
\endfortran

\medskip\noindent For installations with large numbers of TV servers,
this procedure is a bit painful; our apologies, the \AIPS\ group will
try to make it a bit easier for the next release.

These four quantities are: The number of grayscale image planes ({\it
not\/} bitplanes), the number of auxiliary graphics planes, the number
of gray or color levels per image plane, and the number of image storage
units.  Don't worry about what this last item is; you probably don't
have one and are not likely to see one except at the VLA/AOC sites of
NRAO.  Finally, {\tt FILAIP} terminates with this message:
\medskip

\fortran
FILAI1: Init POPS memory files 1 through 11 with program POPSGN
FILAI1: Done!
STOP:
\endfortran

\medskip\noindent
When {\tt FILAIP} completes, on some versions of SunOS you may see what
appears to be the rather scary looking message:
\medskip
\fortran
 Note: Following IEEE floating-point traps enabled; see ieee_handler(3M): 
 Overflow;  Division by Zero;  Invalid Operand; 
 Sun's implementation of IEEE arithmetic is discussed in 
 the Numerical Computation Guide.
\endfortran
\medskip

Do not be concerned about this, as it says the traps are {\it
enabled\/}, not that any occured.  If you see the message here, you will
probably see it everytime you finish \ttaips\ or any of the 
\AIPS\ standalone tasks.

{\tt FILAIP} will create a number of system files in the {\tt\$DA00}
area.  The table below summarizes these files and their purpose:
\medskip
{\settabs
\+ACf00000;1\quad\quad & Number \quad & Description \cr
\hrule \vskip 1.5pt \hrule \vskip 3pt
\+File type & Number & Description\cr
\vskip 3pt\hrule\vskip 3pt
\+ACf00000;1    & 1     & Accounting file \cr
\+BAf00q0n;1    & 1--?  & Batch text files; q is queue number, n is POPS
                          no. \cr 
\+BQf00000;1    & 1     & Batch queueing file \cr
\+ICf00000;1    & 1     & ``Image'' catalog file for Tek graphics \cr
\+ICf0000n;1    &\#TV's & Image catalog for each tv, $1 <= n <= \#TV's$
                          \cr 
\+IDf0000n;1    &\#TV's & TV lock file (for who currently has it open)
                          \cr 
\+PWf00000;1    & 1     & Password file \cr
\+SPf00000;1    & 1     & System parameter file (use {\tt SETPAR} to
                          change)\cr 
\+TCf00000;1    & 1     & ``Show and Tell'' file for running
                          tasks\cr 
\+TDf00000;1    & 1     & Task data file; communication from spawned
                          tasks to \AIPS\cr
\+TPf0010n;1    &\#tapes& Tape lock file to avoid contention\cr
\vskip 3pt \hrule \vskip 1.5pt \hrule
}
\medskip\noindent
In the above table, the third letter of each filename (indicated by
{\tt f}) indicates the data format version; the current letter for
this is {\tt C}, hence the accounting file will be {\tt ACC00000;1},
and likewise for the other files.  Format type ``A'' was introduced as
of {\tt 15OCT86}, ``B'' at {\tt 15JAN87}, and ``C'' at {\tt 15OCT89}.
Prior to that numbers were used.

{\tt FILAIP} will also create the file {\tt MSf00100.001;1} in the
{\tt \$DA01} area.  This is the message file for user 1 (the 
\AIPS\ system manager).  As mentioned at the start of this section, the
first \AIPS\ ``data disk'' area {\tt\$DA01} needs to exist and be
writable prior to running {\tt FILAIP}.  \medskip

\newsubsubsection{Passwords}

Among the files created by {\tt FILAIP} is a password file.  All
passwords are initially blank except for user \#1 which is reserved for
the AIPS manager.  The password for user \#1 is initially {\tt AMANAGER}
(yes, upper case; the checking is case sensitive).  Since the password
entry for user \#1 is initially non-blank, whenever programs run as user
\#1, the password will be required.  The stand-alone utility programs
such as {\tt FILAIP}, {\tt POPSGN}, {\tt SETPAR}, {\tt SETTVP}, \etc.
all run as user \#1 by default.  For example, if after successfully
running {\tt FILAIP} as described above, you were to re-run it, the
first prompt you would get would be for the password (since the password
file now exists).  When typing the password, it will not be echoed on
the terminal and you will only be given a few chances to get it right
before the program will give up and exit.

Passwords may be changed for the current user via the {\tt PASSWORD}
verb in \AIPS.  If the password is forgotten for user \#1, the only
recourse is to delete the entire password file and recreate it via the
program {\tt FILINI}. 

The default setup for the network scheme is to have one instance of
the password file created, and have it hard-linked in the {\tt\$DA00}
areas of the other hosts.  Thus, a change of password for one user on
a given host will automatically change it on all hosts.
\medskip

\newsubsubsection{Running POPSGN}

{\aipsfont POPS\/} is the command language of \AIPS.  The {\aipsfont
POPS} memory files created by {\tt FILAIP} must be initialized as a
separate step.  If you fail to do this, \AIPS\ won't have the foggiest
idea what you're talking about, not even the {\tt EXIT} command.  This
is the sole purpose of the program {\tt POPSGN} which prompts you for
its inputs.  To execute {\tt POPSGN}, simply type:
\medskip

\example{RUN POPSGN}

\medskip\noindent
The following is an example execution of {\tt POPSGN} that will
initialize the memory files created from the {\tt FILAIP} example above.
What you type is in {\bf BoldFace}, computer response in {\tt
typewriter}:
\medskip

\example{\% {\bf RUN POPSGN}}
\example{Data disk assignments:}
\example{\ \ \ Disk 1 is /DATA/ORANGUTAN\_1}
\example{\ } 
\example{Starting up POPSGN (RELEASE OF 15JUL93)}
\example{Enter Idebug, Mname, Version (1 I, 2 A's) (NO COMMAS)}
\example{\bf 0 POPSDAT NEW}
\example{> \hskip 6cm \it (press RETURN when you see this)}
\example{POPSG1: Popsgen complete}
\example{POPSG1: Orang \ 15JUL93 NEW: Cpu= \ \ \ 1.53
                                    \ Real= \ \ 12.0
                                    \ IOcount= \ \ \ 49}

\medskip\noindent
The {\tt Idebug} response should always be zero.  Your response for
{\tt Mname} should always be {\tt POPSDAT} (yes, uppercase).  A file
called {\tt POPSDAT.HLP} is stored in the directory {\tt\$HLPFIL}
which contains the initialization values for the various parameters
and adverbs that will be stored in the memory files.  {\tt POPSGN}
will accept a different name and version for this file, but until you
know what you're doing, don't try it\footnote*{\eightpoint In order
        to add  adverbs and/or verbs to the \AIPS\ command set,
        {\tt\$HLPFIL/POPSDAT.HLP} (or a copy of it) must be modified to
        incorporate the new definitions and {\tt POPSGN} must be rerun
        to re-initialize the POPS memory files; See the ``Going AIPS''
        programming manuals for more on adding verbs and adverbs.}.

The final input to {\tt POPSGN} is the version name of the memory
files to initialize.  This should be given as {\tt OLD}, {\tt NEW} or
{\tt TST}, whichever corresponds to the release of \AIPS\ that you are
installing.

After entering this information, {\tt POPSGN} will grind away for a
while and eventually issue a {\tt >} prompt.  Simply type a carriage
return at this point.  

The next step is to run the program {\tt SETPAR} and perhaps {\tt
SETTVP} as well to set any parameters not initialized correctly by {\tt
FILAIP} during its creation of the system parameter file.  Then copying
various files to a template directory should be done for network sites,
and the {\tt SYSETUP} shell script can then be run to set up the system
({\tt\$DA00}) areas for all the other hosts.  \medskip

\newsubsubsection{Running SETPAR and SETTVP (and maybe SETSP)}

Even though {\tt FILAIP} creates the system parameter file and
initializes some of the parameters, it does not initialize all of them.
For the moment, it is not particularly crucial to set the remaining
parameters, as there are halfway-sensible defaults already set.  

In test-installing \AIPS\ on many systems, the author has found that
items 19 and 29 in the {\tt SETPAR} list, \ie\ the local system
identification (name) and the second AP size, are the ones that
definitely need set before using \AIPS.  The former is a 20-character
string that describes the host you are installing \AIPS\ on, the first 6
of which get printed out whenever an \AIPS\ task completes.  The latter
is determined by the value of the variable {\tt PKPWD2} in the file {\tt
DAPC.INC} in either the system-specific include area (\eg, {\tt
\$INCSUN}), or the generic include file area {\tt \$INC}.  The default
value on Suns is 1216 which gives a total pseudo-AP size of 5 Megabytes.
However, the {\tt SETPAR} default is zero which can {\it
significantly\/} reduce \AIPS\ performance for any other than the
smallest tasks.

The following is an example execution of SETPAR and the parameter values
are from our \AIPS\ environment on a typical NRAO-CV SparcStation IPX {\tt
orangutan}:
\medskip
% @@@ update if needed
\fortran
% RUN SETPAR
Data disk assignments:
   Disk 1 is /DATA/ORANGUTAN_1
 
Starting up SETPAR (RELEASE OF 15JUL93)
Enter:  1=Start Over, 2=Change parameters, 3=Change DEVTAB, 4=Quit      
2
  1  No. of AIPS data disks                  7
  2  No. of tape drives                      3
  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                 4
 11  No. of words in AP (in 1024s)          64
 12  No. of TV devices available            31
 13  No. of graphics devices available     240
 14  No. of X dots per mm on printer     7.830
 15  No. of X dots per mm on tektronix   5.000
 16  No. of POPS allowed access to TVs      15
 17  No. of POPS allowed access to TKs      15
 18  No. entries in private catalogs       500
 19  Local system identification (A20)  Orang (NRAOCV IPX)
 20  Maximum user number (<= 4095)        4095
 21  TIMDEST minima disks  1 -  3 days   14.  14.  14.                  
 21  TIMDEST minima disks  4 -  6 days    7.  90.   1.                  
 21  TIMDEST minima disks  7 -  9 days   14.  14.  14.                  
 21  TIMDEST minima disks 10 - 12 days   14.  14.  14.                  
 21  TIMDEST minima disks 13 - 15 days   14.  14.  14.                  
 22  TIMDEST limit: SAVE/GET files       365.
 23  TIMDEST/EXIT limit: messages          3.
 24  TIMDEST limit: scratch files          3.
 25  TIMDEST limit: empty CA files       0.250
 26  No AP batch starts: weekend hours   0.000 0.000                    
     No AP batch starts: weekday hours   0.000 0.000     
 27  AP roll interval minutes            5.000
     AP patience: (1)*N+(2)*N*N minutes  5.000 1.000
 28  Line printer width (72 - 132)         132
 29  Pseudo-AP 2nd memory (1024s)         1216
 30  Max length of "short" vector            0
 31  Graphics (TK) screen size: x, y      1024   780
 32  Graphics (TK) character size: x, y     14    22
 33  Disk & reserved users or -1 scratch (9 I)
     Disk  2 Users    0
     Disk  3 Users    0
     Disk  4 Users    0
     Disk  5 Users    0
     Disk  6 Users    0
     Disk  7 Users    0
     Disk  8 Users    0                                                 
     Disk  9 Users    0                                                 
     Disk 10 Users    0                                                 
     Disk 11 Users    0                                                 
     Disk 12 Users    0                                                 
     Disk 13 Users    0                                                 
     Disk 14 Users    0                                                 
     Disk 15 Users    0                                                 
Enter number to change or  0 = Print, -1 = Return
-1
Enter:  1=Start Over, 2=Change parameters, 3=Change DEVTAB, 4=Quit
4
\endfortran

\medskip\noindent
Most of the parameters are self-explanatory whereas others require
explanation beyond the scope of this document.  Most systems will have
fairly similar parameters apart from some of the more obvious cases.

The disk parameters shown above are irrelevant, as they get overridden
by (a) the data area definitions created at \ttaips\ startup generated
from the {\tt DADEVS.SH} script and reported to the user on the screen,
and (b) the values in the {\tt \$NET0/NETSP} file.  The number of disks
is obviously variable, hence item 1 above is meaningless; it gets
overridden by the {\tt NVOL} environment variable set by {\tt DADEVS.SH}
on \ttaips\ startup.  Likewise, item 21 --- the TIMDEST parameters ---
are dictated by the values in the {\tt NETSP} file.  If users at your
site use the personal {\tt .dadevs} file to point at areas that are {\it
not\/} referenced in {\tt NETSP}, then the values shown by {\tt SETPAR}
for the number that corresponds to that particular data area will be
used instead, so in this instance it may be wise to set some suitable
default parameters for private data areas in item 21.  Finally, item 33
is again overridden by the values in {\tt NETSP}.

It would be wise to check that item 12, the number of TV devices, is set
to the number of TV servers and TV devices actually used at your site,
or better still set it higher than this so you don't forget to increase
the number when adding a new host.

However, the AP memory parameters are worth mentioning.  There are two:
items 11 and 29 in the list above. %%% Make sure this is right! may %%%
change it later???  The value for {\it No.~of words in AP (in 1024s)\/}
should be non-zero even if you have no AP on your system.  The pseudo AP
routines depend on this parameter as well and pseudo AP installations
should leave this value as {\tt 64}.  The {\it Pseudo-AP 2nd memory
(1024s)\/} parameter should be set at {\tt 1216} for most systems
without ``real'' AP's.  This gives a total pseudo AP memory size of 5
Megabytes.  Most of the pseudo AP implementations take advantage of this
parameter.  If you change this upwards, you will also need to change the
corresponding values in the {\tt DAPC.INC} include file used in your
installation, and if the include file changes, recompile all routines in
the {\tt\$QPSAP} area, as well as rebuilding all tasks that call them
(areas {\tt QPGM}, {\tt QPGNOT}, {\tt QYPGM}, and {\tt QYPGNOT}).  Check
what value is in the {\tt DAPC.INC} file for your architecture and set
this parameter accordingly.

{\tt SETTVP} is used to set TV specific parameters, and the following
somewhat archaic example execution is largely historic, as it shows the
parameters for the IIS model 70 (on our now disassembled Convex C1
system at NRAO-CV).  Installations with only TV servers can skip the
following examples, as the TV servers and \ttaips\ now have a protocol
for dynamically deciding on most of these parameters.  Only if you
modify the servers, \eg, to allow for more than two image planes, would
you have to delve into the {\tt SETTVP} program.

There were three types of TV supported on this 
system: an IIS model 70E, an IIS IVAS, and the AIPS TV server on remote
workstations.  Here are the values for the IIS as reported by the last
released version of \AIPS\ to run on that Convex:
\medskip

\fortran
% RUN SETTVP
Starting up SETTVP (RELEASE OF 15OCT92)
Enter 1=Init, 2/3=Change parms, 4=ISU, 5=quit and the TV # (2I2)
2 1
1  No. of gray-scale planes         (I)     4
2  No. of graphics overlay planes   (I)     4
3  No. of images / gray-plane       (I)    64
4  X,Y size of TV planes (pixels) (2 I)   512   480
5  Maximum gray-scale intensity     (I)   255
6  Peak intensity out of LUT        (I)   255
7  Peak intensities in/out of OFM (2 I)  1023  1023
8  X,Y min. scroll increments     (2 I)     1     1
9  Maximum zoom: (>0) power of 2    (I)     3
      (< 0) Max factor = 1 - MAXINT
10 Type of split-screen allowed     (I)     4
      1=Vert, 2=Hori, 3=Either, 4=Both
11 # X,Y pixels in TV characters  (2 I)     7     9
12 X-axis image write mode(s)       (I)     1
      0 - None, 1 -> Right, 2 -> Left
13 Y-axis image write mode(s)       (I)     2
      0 - None, 1 -> Up, 2 -> Down
Enter number to change, 0=print, -1=return (I2)
\endfortran
\medskip\noindent
The X,Y size of TV planes is set here to $512 \times 480$ because the
IIS was set in hardware to only display 480 lines (we had a film recorder
connected that required this).  Other IIS TV's may have 512 lines
configured most likely.

Before showing the values of the parameters for the other TV's, some
parameters should be explained further.  The first three have already
been described in the section on {\tt FILAIP}.  The terms LUT and OFM
stand for Look-up table and Output Function Memory, both of which can be
regarded as color tables (in a simpified way).

The following shows the parameters for an IIS IVAS display:\medskip

\fortran
1  No. of gray-scale planes         (I)     3
2  No. of graphics overlay planes   (I)     4
3  No. of images / gray-plane       (I)   256
4  X,Y size of TV planes (pixels) (2 I)  1024  1024
5  Maximum gray-scale intensity     (I)   255
6  Peak intensity out of LUT        (I)   255
7  Peak intensities in/out of OFM (2 I)  1023  1023
8  X,Y min. scroll increments     (2 I)     1     1
9  Maximum zoom: (>0) power of 2    (I)     3
      (< 0) Max factor = 1 - MAXINT
10 Type of split-screen allowed     (I)     4
      1=Vert, 2=Hori, 3=Either, 4=Both
11 # X,Y pixels in TV characters  (2 I)    13    19
12 X-axis image write mode(s)       (I)     1
      0 - None, 1 -> Right, 2 -> Left
13 Y-axis image write mode(s)       (I)     2
      0 - None, 1 -> Up, 2 -> Down
\endfortran

\medskip\noindent And finally, here are the parameters for the \AIPS~
TV servers:\medskip

\fortran
1  No. of gray-scale planes         (I)     2
2  No. of graphics overlay planes   (I)     4
3  No. of images / gray-plane       (I)   256
4  X,Y size of TV planes (pixels) (2 I)  1142   800
5  Maximum gray-scale intensity     (I)   199
6  Peak intensity out of LUT        (I)   255
7  Peak intensities in/out of OFM (2 I)   255   255
8  X,Y min. scroll increments     (2 I)     1     1
9  Maximum zoom: (>0) power of 2    (I)   -15
      (< 0) Max factor = 1 - MAXINT
10 Type of split-screen allowed     (I)     0
      1=Vert, 2=Hori, 3=Either, 4=Both
11 # X,Y pixels in TV characters  (2 I)     7     9
12 X-axis image write mode(s)       (I)     3
      0 - None, 1 -> Right, 2 -> Left
13 Y-axis image write mode(s)       (I)     3
      0 - None, 1 -> Up, 2 -> Down
\endfortran

\medskip\noindent
Having the right numbers set in {\tt SETTVP} is no longer vital with the
implementation of an answerback protocol between the TV server and the Y
routines except for item 3 (this is at least true for XAS).

Of course, if your system has no TV display device and no TV servers,
you need not concern yourself with {\tt SETTVP}.

Finally, there is a new program (since the {\tt 15APR92} release) called
{\tt SETSP} that large sites will find invaluable.  It uses a file
called {\tt\$NET0/SPLIST} to query the system parameter files on a
large number of hosts.  Here is an excerpt from ours:\medskip

\fortran
AIPS_ROOT:DA00/ATEN/SPC00000;1
AIPS_ROOT:DA00/BABOON/SPC00000;1
AIPS_ROOT:DA00/BACH/SPC00000;1
AIPS_ROOT:DA00/ORANGUTAN/SPC00000;1
\endfortran
\medskip

\noindent Basically, there is one entry for each host listing in
(a weird hybrid of VMS and Unix) \AIPS\ syntax the filename of the
system parameter file for that host.  When you {\tt RUN SETSP}, it reads
this list and looks at all these files.  You can then look at one of the
{\tt SETPAR} parameters and see the values for {\it all\/} the hosts in
one go.  You can also set a value (same one across all hosts).  The only
disadvantage is that the {\tt SPLIST} file must be maintained by hand.
However, sites like NRAO and the ATNF have found it to be well worth the
slight inconvenience.

The {\tt SETSP} program is {\it not\/} automatically compiled by {\tt
INSTEP3}; if you want it, you must either complete {\tt INSTEP4} or
manually compile it with a {\tt COMLNK \$AIPPGM/SETSP.FOR} command.
\medskip

\newsubsubsection{Setting up TEMPLATE areas and running SYSETUP}

Once you have run {\tt FILAIP}, {\tt POPSGN}, {\tt SETPAR}, and {\tt
SETTVP} for one host of a given architecture, you should create a {\tt
TEMPLATE/} directory under {\tt\$AIPS\_VERSION/\$ARCH/} if it does not
already exist, and copy a subset of the files into it (while they are
``virginal'', \ie, untouched by \AIPS).  The following line should do
it:\medskip

\example{\% cp \$DA00/[ABMST]* \$AIPS\_VERSION/\$ARCH/TEMPLATE/}
\medskip

\noindent You of course only need to go through this if you have more 
than one host of the same architecture.  If you only have one system,
but plan on adding another later, it is still best to set up the area at
this point.

Now you are ready to run the {\tt SYSETUP} script.  First it will ask
you for the \AIPS\ manager account name (default {\tt aipsmgr}), and
the \AIPS\ user group name (default {\tt aipsuser}).  You should be
installing \AIPS\ from the manager account, although you may elect to
have the manager and {\tt aips} accounts as one and the same.  If
installing \AIPS\ from a personal account, set yourself up as the 
\AIPS\ manager, at least for now.  For simplicity you may want to select
the default group for the account you installed \AIPS\ from as the
group.  If you created a group specifically for \AIPS\ users earlier in
the installation, you should use that group.

Next it asks for the master host name.  This should be the host name
of the system you just installed \AIPS\ on.  If you have correctly
configured the {\tt HOSTS.LIST} file and extracts all hosts from it
that match the current value of {\tt \$SITE}.  Then it operrates in a
loop on all hosts in the list (skipping the one you indicated as the
master).  

For each host, it will check for the existence of several directories
and set appropriate protections (user and group allowed write access)
and setgid bits on them.  If the {\tt\$DA00} area for that host does not
exist, it gets created.  It checks what architecture the host belongs to
and sets that in the variable {\tt\$arch} (lowercase).  Then it copies
the files {\tt\$AIPS\_VERSION/\$arch/TEMPLATE/[ABMST]*} to the
{\tt\$DA00} area for that host.  This gets the accounting file, the
batch files, memory files, system parameter and space lock file, task
control file and tape files.  These have to be host-specific by their
nature.

Then it will insert hard links in the host's {\tt\$DA00} area to the
master machine's gripe, password, and image catalog/lock files ({\tt
GR}, {\tt PW}, {\tt IC} and {\tt ID} types).  Finally it checks the
architecture-specific area for that host to make sure the memory file
is there.

Obviously, the strategy to adopt in a network \AIPS\ setup is to run
the installation procedure to at least {\tt INSTEP3} on one system
from each architecture you plan on supporting.  Then make sure the
template areas for all architectures are set up and (from any of the
hosts that you just installed \AIPS\ on) call the {\tt SYSETUP} script
and let it do the work.  

Once it is finished, you will need to run {\tt SETPAR} on each host in
turn to at least set the site name.  Most other parameters can either
be set via {\tt SETSP} later (after {\tt INSTEP4} which builds it) or
are set now from the {\tt DADEVS.LIST} or {\tt NETSP} files.
\medskip

\newsubsubsection{Exercising AIPS}

The sections that follow will describe the various aspects of 
\AIPS\ that will need to be tested to ensure that your new installation
performs correctly.  It also includes some information that will be
helpful if any debugging needs to be performed.

It is recommended that in addition to checking for the usual things
(see if it starts up, look at a few inputs, and so on), that you run
the so-called DDT tests.  This will definitively tell you how well
your installation of \AIPS\ is working, both in terms of accuracy and
timing.  If you are porting \AIPS\ to a new system previously untried
by NRAO or anyone else you know, it is {\it especially} important that
you perform this step.
% @@@
However, please note that the DDT test underwent significant changes
shortly after the {\tt 15JUL93} release of \AIPS\ was frozen, and at the
time of writing, there exists a new version of this procedure and a new
definition of the \AIPS mark.  Contact the \AIPS\ group for details on
how to get these if you have ported \AIPS\ to a new system.
% @@@
When you have them, please communicate the results of your DDT tests to
the \AIPS\ group.  We strive to keep those results in our memos and
databases (and give you credit for it, of course!)

\medskip

\newsubsubsection{AIPS Start-up Procedure}

After all this work you are {\it almost} finally poised to start up
\AIPS\ itself.  If {\tt INSTEP1} did its work, you should just be able
to type {\tt aips} and have it start up for you.  If you have not yet
set up the network services required by \AIPS, you can expect lots of
error messages to be sprayed out on your window or terminal, but the
basic system will still work (minus TV, tek, and message servers, and
without remote tape capability).

Earlier releases recommended a file or symlink in {\tt /usr/local}, but
in this release, that is no longer necessary.  As long as \ttaips\ users
% @@@ rephrase next time around
have the reference to the {\tt LOGIN.CSH} or {\tt LOGIN.SH} command in
their login/profile files (see ``{\it Login Procedures}'' above), no
additional work is necessary on their part (or hopefully yours) to
enable them to use \AIPS.

You may, however, want to copy the \AIPS\ ``man'' page to your local
``man'' area (your sysadmin will probably know where this is), \eg:
\medskip

\example{\# cp \$SYSUNIX/AIPS.L /usr/local/man/man1/aips.1}
\medskip

\noindent This will enable people to type {\tt man aips} and get some
useful information on the startup options, provided they have their {\tt
MANPATH} environment variable set up to include your local area,
whether it be as indicated above or elsewhere.

The {\tt START\_AIPS} procedure goes through many gyrations, calling
some of the other files in the {\tt\$AIPS\_ROOT} and {\tt\$SYSUNIX}
areas, before it finally execs to the {\tt\$SYSUNIX/AIPSEXEC}
procedure.  This in turn is a stripped-down version of the old
(pre-{\tt 15APR92}) {\tt AIPS} shell script that used to start 
\AIPS\ all by itself.

To initiate a {\tt BATER} (\AIPS\ batch job submission program), there
is a procedure called {\tt BATER} (and {\tt bater}).  This takes a
subset of the command line arguments that {\tt START\_AIPS} takes,
\ie, a version name, {\tt REMOTE}, {\tt DEBUG}, or {\tt LOCAL}; the
{\tt REMOTE} option has already been mentioned (graphics terminal).

% One problem with {\tt BATER} is that it does not support the {\tt da=}
% option; is this important? @@@

When you invoke these procedures, after some setup the respective
startup program is executed, {\tt ZSTRTA} for {\tt AIPS} or {\tt ZSTRTB}
for {\tt BATER}.  The major purpose of the {\tt ZSTRT*} programs is to
assign the lowest available POPS number to the current job that is not
already in use (and not reserved for another terminal if reserved
terminals are in use) and to invoke the respective executable module as
a process with a name such as {\tt AIPSx}, where {\tt x} is the assigned
POPS number.  Tasks initiated from an {\tt AIPSx} session inherit this
POPS number and have similar process names (\eg, {\tt MX3}).  To startup
\AIPS\ in the simplest case, simply type: \medskip

\example{\% aips}\medskip

\noindent or for an example that shows some of the features introduced
in {\tt 15APR92}, \medskip

\example{\% aips pr=2 da=sparky,zippy tp=astro2 tv=foo:bar} 

\medskip\noindent 
The options in the latter case mean the following:  Use printer number
2 from the menu (leave out the {\tt pr=x} to get the menu), include
\AIPS\ data areas from remote hosts sparky and zippy, make sure the
{\tt TPMON} daemons are running on remote host astro2, and override the
default TV settings, using (X11) display on host foo while running the
{\tt XAS} TV server itself on host bar.  As you can see, the system is
quite flexible.  The only caveat is that most of the above hosts need to
be \AIPS\ hosts, except for machine foo, which just has to have
permission to display X11 images from machine bar.  For additional
details on these options, see the \AIPS\ man page in {\tt \$SYSAIPS} (or
wherever you installed it).

The first thing you will see in the former case (if you have more than
one printer configured) is something like this:\medskip

\fortran
orangutan_pmurphy<504> aips
 
You have a choice of 9 printers.  These are:
 
     1.  Library High speed Postscript printer -- Duplex
     2.  Library High speed postscript printer -- single sided
     3.  Postscript printer downstairs
     4.  Postscript printer in room 215
     5.  Color Postscript printer, AIPS Cage
     6.  SOLITAIRE ONLY -- Postscript 35 mm slides
     7.  GNU Ghostscript X-windows previewer
     8.  Sun OpenWindows PAGEVIEW previewer
     9.  QMS1725 Postscript printer in Green Bank
 
Enter your choice: 
\endfortran

\medskip\noindent This is of course specific to NRAO's Charlottesville
setup but your output should be similar and reflect your {\tt PRDEVS.SH}
setup.  At this point, you enter a number for the printer you want, and
continue:\medskip

\fortran
The output print queue is ps0, type PS

Data disk assignments:
   Disk 1 is /DATA/POLARIS_1
   Disk 2 is /DATA/BABOON_1
   Disk 3 is /DATA/BABOON_2
 
Tape assignments: 
   Tape 1 is Exabyte 8200 on BABOON
   Tape 2 is REMOTE
   Tape 3 is REMOTE

You do not seem to be at a workstation (TERM=emacs)

============================  AIPS NEWS  =============================

No news is good gnus

======================================================================

Starting up 15JUL93 AIPS with normal priority
Begin the one true AIPS number 1 (release of 15JUL93) at priority =   0
AIPS 1: YOU ARE NOT ASSIGNED A TV DEVICE
AIPS 1: YOU ARE NOT ASSIGNED A GRAPHICS DEVICE
AIPS 1: Enter user ID number
?
\endfortran
\medskip
\noindent You will probably see (asynchrously) the message:\medskip

\example{STARTPMON: Starting TPMON1 on BABOON...}\medskip

\noindent and also (later):\medskip

\example{TPMON1: begins}\medskip

\noindent The above example was done without a TV; there are
additional messages that may come out asynchrously to do with starting
the XAS TV server and the {\tt TEKSRV} and {\tt MSGSRV} servers; unlike
older releases, this version of \AIPS\ tries to identify the username
and process id of already running servers.  Unfortunately, these may
come out just as the poor user is trying to enter the user number and it
can be a bit confusing.

If you tried this command from a workstation running X11 (including
OpenWindows, Motif, VUE, \etc), three extra windows should have popped
up (two iconified).  One will be the TV server; the XAS icon has a
picture of a gorilla on it with ``new XAS'' in tiny letters below.
Another (also iconified) will be an {\tt xterm} that runs the {\tt
TEKSRV} program and displays graphics.  The final one will be the {\tt
MSGSRV} message server and will probably {\it not\/} appear as an icon,
but as an open {\tt xterm} instead.  You can, of course, customize
the startup location and characteristics of all these as indicated above
via the {\tt .Xdefaults} file.

If your windowing system is already displaying a lot of colors (\eg, a
background color image on the root window), XAS may start up with a
virtual colormap.  When you open the XAS window and move the cursor into
it (or click on it if you use click-to-type), the colors on your display
will probably change suddenly as the virtual colormap becomes the
default.  When you move the focus (move the mouse or click on a
different window), the default colormap will be restored.  This is
normal behaviour.  It can be avoided by putting as few colors as
possible into your windowing system before {\tt XAS} is started, or
lowering the number of colors available for {\tt XAS} via the X
resources; again, see the example earlier in this document.

Note also the ``AIPS NEWS'' message; this is from the file {\tt
AIPS.MSG} which is in the {\tt\$AIPS\_ROOT} area.  It is a good place
to put messages concerning the \AIPS\ system for all your users to
see. 

You should see the {\tt >} prompt at the end of the session after
entering your AIPS (VLA) user number (improvise if you don't have one
but leave 1 for the \AIPS\ manager).  If this is not the first time
starting, you will see the ``Recovered POPS environment'' message.
\medskip

\newsubsubsection{Task Initiation}

Assuming \AIPS\ in fact starts up, you're ready to start exercising it a
bit.  To make sure tasks are activated properly, type the following
inside \AIPS: \medskip

\example{> GO DISKU}\medskip

\noindent This should result in a fairly uninteresting report on disk
space usage (unless there is some real data on the disks in which case
it may be enlightening, or even embarassing).  You may want to check
the inputs\footnote*{\eightpoint just type INPUTS DISKU to see
                                 them}
before running it.  You may also try the {\tt NOBAT} task; this is
simply designed to sleep for the specified time, preventing batch jobs
from running.

If your message server is running, you will see the task output come out
in its window, whereas output from the main \ttaips\ program comes out
in whichever terminal emulation window where you started \ttaips.  
\medskip

\newsubsubsection{Tape Interface}

Once you are satisfied that task initiation works, you're ready to move
on to more substantive tasks, like reading in data from tape.  The tasks
involved here are {\tt UVLOD} (reads UV data tapes), {\tt IMLOD} (reads
map data tapes), and the more general {\tt FITLD} (reads FITS data
whether UV or image; not compiled in {\tt INSTEP3}).  Their success or
failure depends critically on the integrity of the tape interface
routine {\tt ZTAP2} which will require local development in the case of
ports to new systems.  Versions of {\tt ZTAP2} already exist in the
various subdirectories of {\tt\$APLUNIX} (Alliant, Convex, Sun, HP, IBM
(RS6000), Cray, DecStation) which should work without modification on
standard tape drives as follows:\medskip

% @@@ get from TPDEVS.LIST
\item{$\bullet$} Sun-supplied Exabyte 8200 and 8500 drives on a SCSI bus
                 (SunOS 4.1.1, 4.1.2, 5.1, 5.2) 
\item{$\bullet$} HP DAT drive on a Sun, SCSI bus (SunOS with patches for
                 backspace) 
\item{$\bullet$} IBM-supplied Exabyte 8200 and 8500 drives, SCSI bus
                 (AIX 3.1, 3.2) 
\item{$\bullet$} IBM-supplied 9-track drive (9348-012), SCSI bus (AIX 3.1, 3.2)
\item{$\bullet$} HP 9-track 88780B drive, SCSI bus (AIX, SunOS too?)
\item{$\bullet$} HP DAT drive on IBM, SCSI bus (AIX 3.2 or later)
\item{$\bullet$} ZZYZX 1.3Gb 4mm DAT drive on IBM, SCSI, 150Mb personality
\item{$\bullet$} ZZYZX Exabyte 8500 on IBM, SCSI bus (AIX 3.2 or later)
\item{$\bullet$} ZZYZX Exabyte 8200 on SunOS
\item{$\bullet$} Exabyte DAT from ZZYZX
\item{$\bullet$} Convex 9-track drives (ConvexOS 8.0 or later)
\item{$\bullet$} StorageTek 9-track drives on a convex (ConvexOS 8.0 or later)
\item{$\bullet$} TK50 on SCSI bus on DecStation/System (Ultrix 4.0/4.3);
                 Exabyte also?
\medskip

\noindent For anything else, you should do considerable testing with
both reading, writing and tape motion (verb {\tt AVFILE}) to verify that
the system works correctly.  If not, you will have to modify the {\tt
ZTAP2} routine.  The selection of tape drives above reflects those NRAO
had in routine operation with \ttaips\ at the time this document was
last updated; it does not endorse or recommend any particular vendor or
model.

The {\tt\$APLUNIX} directory itself contains a stubbed version of {\tt
ZTAP2}.  If this is the version that actually gets processed by the {\tt
INSTEP2} phase and added to your Z-routine object library, programs
linked with it will tell you that {\tt ZTAP2} ``requires local
development'' whenever any tape manipulation is attempted.

Remember to have the network services implemented if you are
attempting to use remote tape access. \medskip

\newsubsubsection{``Dirty Dozen'' Tasks (DDT) testing}

The other executable modules generated by {\tt INSTEP3} will allow you
to do quite a range of typical \AIPS\ processing.  After you're
satisfied that the system is functioning properly, you can generate the
remaining executable modules of the \AIPS\ system via {\tt INSTEP4} (see
below).  For details on the DDT suite of programs, see \AIPS\ memo 73
({\it AIPS DDT History}).  You may want to request a DDT tape from the
\AIPS\ group in Charlottesville, or get them over the internet network.

To obtain the small and medium datasets for the DDT via internet
anonymous ftp, connect to {\tt baboon.cv.nrao.edu} (192.33.115.103).
The files are in directory {\tt pub/aips/DDT} as files {\tt
ddt.small.tar} and {\tt ddt.medium.tar}.  These are tar files, each
containing eleven fits disk files that will enable you to run the small
or medium DDT.  In both cases, you need to figure out which are the UV
data files and which are the images (maps) and use {\tt UVLOD} (no UV
compressed data!) or {\tt FITLD} as appropriate, unless you compile {\tt
\$APGNOT/FITLD}.  {\bf IMPORTANT}: See the file {\tt README.DDT} in that
same area for more detailed instructions on unpacking, and on getting
the new (under construction at time of writing) DDT suite; things will
likely have changed by the time you read this.

Memos are also available at this anonymous ftp address in the directory
{\tt pub/aips/TEXT/PUBL}.  This is not the master area for memos, but we
attempt to keep it reasonably up to date with copies of relevant
documents.  It is a mirror for the {\tt \$AIPSPUBL} area you will find
on your \AIPS\ installation, with the difference that the baboon area is
constantly being updated.  Most \TeX\ memos will have a PostScript
version as well. 

At the time of writing, NRAO is experimenting with a {\tt www} server
that can be used by World-Wide-Web programs such as {\tt xmosaic};
current plans are for people to be able to connect to the following URL:
\medskip

\example{http://aips.cv.nrao.edu/aips.html}
\medskip

\noindent However, as the details are not yet finalized, you may want to
inquire (email to {\tt aipsmail@nrao.edu} perhaps) as to the exact
syntax before trying.  This area will have access to the complete
anonymous ftp area, and perhaps more.

\medskip

\newsubsubsection{Running under a Debugger}

If {\tt DEBUG} is one of the command line options used to start up the
{\tt AIPS} task, the relevant routine ({\tt ZACTV9}) in the {\tt ZSTRTA}
program will start up the {\tt AIPS.EXE} binary under control of the
specified debugger ({\tt dbx}, {\tt adb}, {\tt dbxtool}, {\tt debugger},
{\tt csd}, {\tt xde}, or some other); you get prompted for its name.

The \AIPS\ group have found that the environment variable {\tt
LM\_LICENSE\_FILE} may have to be explicitly defined as pointing to the
correct license file and available in the environment before running
\ttaips\ in debug mode with the newer Sun debuggers.  If your site runs
a license manager on Suns, you may or may not have to define this
variable as we do.  The symptom of needing it defined is that the
debugger starts up but refuses to do anything as it can't get a license
to run.

You will also get asked if you want to run {\tt AIPS} itself under the
control of the specified debugger.  If not, then only the other tasks
that {\tt AIPS} sheds will start up in debug
mode\footnote\dag{\eightpoint only if {\tt SETDEBUG(n)} is issued in
\AIPS\ with ${\tt n} > 10$}.  Running a process like {\tt AIPS} under
the control of a debugger as well as its tasks (subprocesses) can be
very confusing, if not simply undesirable; hence this choice.

When a task, or \ttaips\ itself, is run in debug mode, the program name
--- including the {\aipsfont POPS}\ digit --- will be embedded in the
debugger prompt on most systems.  In addition, for tasks, the 
\ttaips\ parent process will be put into a wait state (regardless of the
value assigned to the \AIPS\ adverb {\tt DOWAIT}). 
\medskip

\newsubsubsection{The VERSION Adverb}

In porting to a new system, or even when trying to debug certain parts
of \AIPS\ or new tasks, it is often useful to have private versions of
certain tasks.  The adverb {\tt VERSION} in \AIPS\ is used to point to
task executables in different directories.  The intention is that, in
addition to the normal selection ({\tt OLD}, {\tt NEW}, and {\tt TST}),
the user should be able to point to a private version of a task via the
use of an UPPERCASE environment variable that specifies the full name of
the directory containing the desired binary (executable).

A version of the task help file (\eg, {\tt UVLOD.HLP}) must reside in
the same directory as the private executable module.  As all string
adverbs in \AIPS\ are automatically converted to uppercase, your
environment variable name shouls also be entirely uppercase.  Of course,
the area it points to need not be uppercased.  The names of the files
must also be entirely upper case.  When you start up \AIPS, you can then
specify this variable as the value of {\tt VERSION}.  For example, if we
want to run a private version of the task {\tt FOO}, and {\tt FOO.EXE}
and {\tt FOO.HLP} reside in the area {\tt /u2/pmurphy/aips/test/}, then:
\medskip

\example{\%\ setenv MYSTUFF /u2/pmurphy/aips/test}\medskip

\noindent or

\example{\$\ MYSTUFF=/u2/pmurphy/aips/test; export MYSTUFF}

\medskip\noindent
Then in \AIPS, after setting {\tt VERSION='MYSTUFF'}, the system will
look at the private version of {\tt FOO} whenever the inputs, help,
explain, or go verbs are called for task {\tt FOO}. \medskip

\newsubsection{Installation Step 4}

The final stage in the installation process is the one that builds all
tasks in \AIPS.  It will remake those already made in {\tt INSTEP3}
but this causes very little overhead.  For the most part it is
completely automatic, and if you have tested \AIPS\ out with the
procedures outlined in the previous section, it should go smoothly.
\medskip

\newsubsubsection{Running INSTEP4}

The {\tt INSTEP4} procedure can take as long or longer than {\tt
INSTEP2}.  To initiate {\tt INSTEP4}, simply type:\medskip

\example{\%\ INSTEP4}

\medskip\noindent
It will cycle through all the major program source code areas in the
following order:
\medskip
{\settabs \+XXXXXXXXXX & AIPGUNIX\quad\quad & \cr
\+&AIPPGM       & \AIPS\ Program itself and related beasts \cr
\+&AIPGUNIX     & Unix-related \AIPS\ tasks \cr
\+&APLPGM       & Main area for application tasks \cr
\+&APGNOT       & Non standard application tasks \cr
\+&APGOOP       & Tasks that use object-oriented fortran routines \cr
\+&AIPNOT       & Non standard \AIPS\ tasks \cr
\+&QPGM         & AP-specific tasks \cr
\+&QPGNOT       & Non standard AP specific tasks \cr
\+&QYPGM        & AP- and TV-specific tasks \cr
\+&QYPGNOT      & as above but not standard \cr
\+&QPGOOP       & as APGOOP but AP-specific \cr
\+&YPGM         & TV-specific tasks \cr
\+&YPGNOT       & as above but not standard\cr
}
\medskip\noindent
and build ``at'' files for all the programs found, then use the ``at''
files to drive the execution of {\tt COMLNK}, as in the case of {\tt
INSTEP3} but on a much larger scale (approximately 300 programs in all).
Like {\tt INSTEP2}, there may be failures especially on a new port.
Also, some may fail to link if some of the {\tt INSTEP2} subroutines
failed to compile (see the {\it Known Problems} chapter).

%%% Following doesn't work anymore because of PREP...
% @@@ did you fix it?
% Note that {\tt COMLNK} will (via {\tt SEARCH}) replace whatever the
% argument it gets is with what it thinks is the most recent product of
% that.  For example, if the user types:\medskip
%
% \example{\% COMLNK \$AIPPGM/AIPS.FOR}\medskip
% 
% \noindent but {\tt \$AIPPGM/AIPS.o} exists and is
% up-to-date, {\tt SEARCH} will substitute {\tt\$AIPPGM/AIPS.o} and
% simply invoke the procedure {\tt LINK} to re-link it.  This is true
% even when include files change that are included in the program source
% code.  In other words, it knows to check the dependencies of the
% source file by checking what files it includes (just like {\tt make}
% with a well thought out makefile).
\vfill\eject % want it to start on a new page; may not be needed? @@@

\newsection{Z-Routines and Z-Programs}

The following is a collection of notes regarding Z-routines for the Unix
version of \AIPS.  Some of the information may be quite dated.\medskip

\newsubsection{Introduction}

The original implementation of \AIPS\ under Unix occurred as a result
of the pioneering efforts of David Garrett in the Astronomy Department
at the University of Texas, Austin.  At NRAO, the Unix implementation
has evolved under a number of systems beginning with Amdahl's UTS
implementation of Version 7 UNIX.  A Masscomp MC 500 at NRAO Greenbank
running Bell's System III UNIX had also served as a test bed from time
to time although never as a production machine.

% @@@ Update next paragraph!

All that is ancient history.  We now have eight IBM RS/6000 model 560
workstations running AIX 3.2 as our main \AIPS\ workhorses.  These have
essentially completely replaced the functionality of our older Convex
C1's (we only have one left at the AOC and it is targeted for
mothballing this year).  Also, there are lots of Suns: mostly
SparcStation IPC and IPX, (SunOS 4.1.1 and 4.1.2 with a few brave souls
at SunOS 5.1 and 5.2), one Sparc--10 (SunOS 5.2), a few additional IBM
RS/6000s (AIX 3.1/3.2), one DecStation (Ultrix 4.3/DEC Fortran) and the
most recent arrival, a Dec Alpha 3000 model 300 workstation (OSF/1, port
in progress).  VAXen have totally disappeared from our computer rooms
insofar as \AIPS\ use is concerned. The ports of \AIPS\ to all the Unix
machines mentioned above are relatively mature.  In addition, through
the courtesy of the people at NASA's Jet Propulsion Laboratory in
Pasadena, California, we have been able to make a full port to the HP
9000 series 700 systems running HP--UX 8 and 9.  Expect the Alpha port
to be made accessible via the ``patch'' mechanism sometime in the Fall
of 1993, and definitely available in the {\tt 15JAN94} release.

In addition, \AIPS\ has been ported to the Alliant FX architecture and a
port of \AIPS\ to Cray's UNICOS has also been performed.  The latter has
been somewhat updated since the last release.  Non-NRAO sites have also
ported \AIPS\ to a variety of UNIX environments.  The result has been
the evolution of a rather robust, portable implementation.  However,
NRAO must continue to rely on sites that are running flavors of UNIX or
that have hardware different from ours to contribute the special code
that these systems may require.  This has already produced a subset of
routines that is quite generic for Unix/AIPS, but we need to know about
variations, improvements and most important, cases where what we think
is generic is not in fact the case at all.  So {\it please\/} let us
know! \medskip

\newsubsection{Standards}

The \AIPS\ group continues to make the Unix Z-routines as generic as
possible.  What we are up against is the vendor extensions that, while
useful in the short term, are non-portable and/or 
non-standard\footnote*{\eightpoint For example,
% placeholder
        many systems will allow you to {\tt EQUIVALENCE} data items of
        type {\tt CHARACTER} with data items of other types; this is an
        ANSI (f77) standard violation.}.
% placeholder
Wherever routines can be written in ANSI standard Fortran 77, they
should be, so that they can be used by any system that has a compliant
compiler.  The real authority for this is the American National Standard
document {\it Programming Language FORTRAN\/} (ANSI publication
X3.9--1978).  DEC provides {\it VMS Fortran\/} users with very nice
manuals that highlight non-standard constructs in blue ink, and it is
these blue sections that should be avoided if the goal is portable code.

The situation for Z-routines that must be written in C was less clear
but things have improved.  The ANSI standard for C has been available
for some time now, and most systems have or offer such a compiler.
There are still some compilers that only support the older (so-called
``K\&R'' C, after Kernighan and Ritchie, the authors of {\it The C
Programming Language\/}, considered by many to be the original standard
work).  

During the recent port to SunOS 5 (Solaris 2), most of the existing Z
routines were overhauled and converted so that they will work either
with ANSI C or K\&R C.  On Suns with the ANSI C Compiler (called {\tt
acc} in SunOS 4), you should use this rather than the older compiler.
The differences amount to function prototypes and possibly some
different include files.
\medskip

\newsubsection{Defining your System: the ZDCHI2 Routine}

The system parameters defined in the routine {\tt ZDCHI2} are critical
to the successful exchange of data between systems, primarily via tape
or FITS disk.  These include the values assigned to the {\tt /DCHCOM/}
common variables {\tt BYTFLP}, {\tt SPFRMT} and {\tt DPFRMT}.  The
values assigned to several other, less critical system parameters in
this routine also warrant attention.  These include the values assigned
to {\tt NSHORT}, {\tt TTYCAR}, {\tt SYSTYP} and {\tt SYSVER}.\medskip

\newsubsubsection{BYTFLP --- Byte order: big or little Endian?}

The value assigned to {\tt BYTFLP} is used to indicate whether the host
uses byte or word flip, or both, or neither (most common) for its
internal representation of data.  Byte/word flipped data is where the
order of the bytes in data items is {\it flipped\/} (``little endian''
ordering) compared to the more common order (``big endian'').  
\AIPS\ has been designed such that it converts its input from the
outside world (\ie, tape and FITS disk data) into the byte order of the
host, and on output converts it back to big-endian order.  So on most
machines, the conversion routines are no-ops.  Here a byte is considered
to be 8 bits, and a word is 16 bits.

For the ``big-endian'' case, {\tt BYTFLP} should be left as {\tt 0}.
This covers Suns, IBM RS/6000's, HP 9000 series 700, and Convex.  For
``little-endian'' systems such as VAXen, DECstations (MIPS/Risc) and
Intel (\eg, 80486) based processors, the value for {\tt BYTFLP} should
be set to {\tt 3} to indicate both byte and word flipping.  Not all
MIPS-based processor use little endian ordering; like the Motorola 88000
and AMD 29000 RISC processors, MIPS-based processors actually support
both ordering schemes, selectable only at power-up.  However, the
highest profile MIPS-based processor is easily the DECstation which uses
little-endian ordering.  The systems you get direct from MIPS itself
however do not.

The following Z-routines are sensitive to byte/word flip:
\medskip
{\settabs 6 \columns \tt
\+& ZBYTFL & ZBYTF2 & ZI16IL & ZI32IL & ZILI16 \cr
\+& ZILI32 & ZIPACK & ZR32RL & ZR64RL & ZRLR32 \cr
\+& ZRLR64 \cr
}
\medskip

\newsubsubsection{Floating Point Formats: SPFRMT and DPFRMT}

{\tt SPFRMT} and {\tt DPFRMT} are floating-point format indicator codes
used to indicate the host single and double precision floating-point
formats.  \AIPS\ uses these to determine how to convert the host
floating-point data format to IEEE format before writing it to tape or
FITS disk and, conversely, how to convert IEEE floating-point data read
from tape to the host format.

Most processors brought to market in recent years use IEEE float-point
format (Sun, IBM RS6000, HP/Apollo, Convex, Dec (non-VAX)$\dots$).
Versions of the IEEE/host floating-point format conversion Z-routines
exist already for hosts that use IEEE (trivial, of course) and VAX
F-floating-point.  The routines that perform such conversions ({\tt
ZR32RL}, {\tt ZRLR32}, {\tt ZR64RL} and {\tt ZRLR64}) are designed to
stop dead in their tracks if they see an unsupported floating-point
indicator code.
\medskip

\newsubsubsection{Other Miscellaneous Parameters}

There are four parameters that may need to be set or changed for a
new system.  These are:\medskip

\item{$\bullet$} {\tt NSHORT} should be the number of iterations that
characterizes a loop as ``short''.  Some loop terminating values
cannot be known at compile time.  {\tt NSHORT} provides a means by
which we might be able to code alternate, scalar code to which
execution would branch upon detecting that the loop is "short".  This
is of course for {\tt \$QPSAP} routines mainly.

\item{$\bullet$} {\tt TTYCAR} (0 or 1) is simply used to toggle
whether or not carriage control is required for terminal I/O.  If you
aren't sure, try a few simple experiments to see if formatted terminal
I/O requires a leading blank (see {\tt \$APLGEN/ZTTYIO.FOR}).

\item{$\bullet$} {\tt SYSTYP} and {\tt SYSVER} are {\tt CHARACTER}
variables used to indicate the operating system (\eg, {\tt 'UNIX'}
versus {\tt 'VMS'}) and {\tt SYSVER} is used to indicate the version
(\eg, {\tt 'SunOS 4.1.2'}, {\tt '5.4'}).  For DEC/Ultrix systems, do not
alter the {\tt SYSTYP} variable as it is checked in other Z routines
when opening disk files for direct access (\eg, {\tt ZTPOPD}); the
record length convention on VMS and Ultrix systems is that the units of
record length are longwords (4 bytes each), whereas on most other
systems the units are bytes.
\medskip

\newsubsection{Routines that Require Local Development}

For new ports, some Z routines may require local development.  These are
in the {\tt\$APLGEN} and/or {\tt\$APLUNIX} areas and may be ``stubbed''.
The stubbed versions will print an error message and either return with
an error code or stop the program.  In many cases, working versions of
routines exist that are suited to a particular vendor's environment
(\eg, {\tt\$APLIBM}, {\tt\$APLHP} and {\tt\$APLSUN}).  These are
environments with which we have either had first hand experience or for
which non-NRAO sites have submitted code.

The routines that potentially require local development include:
\medskip

\item{$\bullet$} tape manipulation ({\tt ZTAP2} and {\tt ZMOUN2}); look
                 at Sun and IBM versions for examples;
\item{$\bullet$} line printer output spooling ({\tt ZLPCL2.C}
\item{$\bullet$} IEEE to local floating-point conversion ({\tt ZR32RL}, 
                 {\tt ZR64RL}, {\tt ZRLR32} and {\tt ZRLR64})
\item{$\bullet$} VLA archive tape data handling ({\tt ZDM2DL},
                 {\tt ZMCACL}, {\tt ZRDMF} and {\tt ZRM2RL})
\item{$\bullet$} Other data conversion routines (\eg, {\tt ZI16IL}, 
                 {\tt ZILI16}, \etc) if you are installing \AIPS\ on a
                 64-bit machine
\item{$\bullet$} Getting accumulated CPU time ({\tt ZCPU}; make sure
                 the units are right)
\item{$\bullet$} Getting free space ({\tt ZFRE2}; use the Sun version
                 as a template)
\item{$\bullet$} TV oriented Z-routines (\eg, {\tt ZM70*}) if your 
                 system has such a device.

\medskip\noindent
In the early stages of a new port, the most important Z-routines to work
on are {\tt ZDCHI2} and {\tt ZTAP2}.  In {\tt ZDCHI2}, you want to make
sure that the values for {\tt BYTFLP}, {\tt SPFRMT}, {\tt DPFRMT} and
{\tt TTYCAR} are correct for the target system.  {\tt ZTAP2} may take a
bit of work to determine how to detect such things as file marks and
beginning or end of tape.  The other Z routines are not so critical and
can be worked on as the need arises.

A list of most (maybe even all) of the Z routines relevant for Unix is
presented in Appendix 1 of this document.  This is unfortunately quite
out of date; refer to the source code itself if in doubt.  A brief
explanation of its function is also given for each routine.  If you need
more than this, consult the two-volume {\it Going \AIPS\/} document set.
The list in the appendix here may not include updated information on the
latest versions ({\it caveat emptor\/}!).
\medskip

\newsubsection{Unix Z programs}

The only Z programs developed for Unix/\AIPS\ at NRAO are {\tt ZSTRTA}
(interactive \AIPS\ startup) and {\tt ZSTRTB} (batch \AIPS\ startup).
Generic versions of these two can be found in {\tt \$AIPGUNIX}.  {\tt
ZSTRTA} is executed as part of the \AIPS\ startup procedure
{\tt\$SYSUNIX/AIPSEXEC}.  The purpose of {\tt ZSTRTA} is to determine
the lowest available/appropriate POPS number.  This is determined from
the existence of processes with names of the form {\tt AIPSn} where
{\tt n} ranges from 1 to the maximum number of interactive \AIPS~
allowed as specified via {\tt SETPAR} in the system parameter file
({\tt \$DA00/SP*}).  This value is also limited by the number of
memory files generated via {\tt FILAIP} (or {\tt FILINI}) and
initialized by {\tt POPSGN}.  Like {\tt ZSTRTA}, {\tt ZSTRTB} is
executed as part of the {\tt BATER} startup script {\tt
\$SYSUNIX/BATER}.  {\tt BATER} is an \AIPS-like program for preparing
and submitting \AIPS\ batch jobs.

There may be problems with the process determination part of these
routines, particularly when different accounts are used to run \AIPS.
There also may be file locking problems associated with this, especially
on NFS-mounted file systems.  
% @@@ update as needed
In the {\tt 15JUL93} version of \AIPS, an effort has been made to steer
clear of the older {\tt flock()} system call and use the locking
mechanisms available in {\tt fcntl()} instead.  The problem with using
{\tt flock()} is that it seems to work fine if the locked file is on a
NFS file system, \ie, it reports success, but the file is not in fact
locked.  Conversely, {\tt fcntl()} does support locking on remote NFS
file systems, but it has problems, notably at very large installations
such as NRAO's AOC network.  \AIPS\ makes extensive use of file locking,
and as one of the filesystems was used by \AIPS\ users on over 40
workstations rather heavily, the limit in the lock d\ae mon of 256 locks
did on occasion get exceeded.  Other sites are not as likely to run into
this problem, however, as the AOC is probably the largest 
\AIPS\ installation at this time.  

\vfill\eject
\newsection{Release Notes}

\newsubsection{Introduction}

The purpose of this chapter is to give installers some notion of the
system dependent changes in \AIPS\ that may affect local development.
The same change information can usually be extracted from the
\AIPS letter, but its impact may not be obvious.  If this is your first
installation of AIPS, these notes are probably of little interest, but
they may give you some idea what kind of future changes might trip you
up when you update your system.

The sections for the {\tt 15JUL89} and earlier versions may be found
in the {\tt 15APR91} version of this document.  \medskip

\newsubsection{Notes for the 15OCT89 Release}

The {\tt 15OCT89} release is the first publicly available release of
the overhauled system.

No more {\tt INTEGER*2} (and hardly any hollerith data anymore).  Lots
of other changes too numerous to mention (see memo titled {\it
Conversion of Old \AIPS\ Software to Run Under {\tt 15OCT89} and Later
Releases\/} which should accompany installation kits for the next few
releases).  There is {\it only\/} one way to convert data on disk
generated from previous releases to the new data format required by
the {\tt 15OCT89} release.  This is by writing the old data to tape
using {\tt FITTP} under the old system, then read the data from tape
into the new system using {\tt IMLOD} or {\tt UVLOD}.  The overhauled
code runs about as fast as the pre-overhauled code. The \AIPS\ group
has been reorganized. \medskip

%%% 15JAN91 release notes!  Nah.

\newsubsection{Notes for the 15APR91 Release}

No major system-level changes to report.  {\tt ZFRE2.C} in the
{\tt\$APLSUN} area has been written so that it should run on Convex
and IBM RS/6000 systems unmodified; a test version ran with no errors
on these two systems as well as Sun3 and Sun4.  The only version
tested within a full-blown \AIPS\ environment, however, was for Suns.
If you have a Convex or an IBM RS/6000 system, please try it out and
let us know if the {\tt\$APLSUN} version works.  Do NOT try it on a
DecStation!  There is a version in the works for that as the system
call in question ({\tt statfs()}) is significantly different on
Dec/Mips systems. \medskip

\newsubsection{Notes for the 15APR92 Release}

Many of the changes described in \AIPS\ memo 74 ({\it \AIPS\ at the
ATNF\/}) have been implemented in the general release of the system
(mostly thanks to Mark Calabretta).  The shell scripts that set up the
\AIPS\ environment and start the \AIPS\ program have been overhauled
so that networks are more of an integral part of the system instead of
an afterthought.  The way TV servers are handled has been radically
changed, a tektronix window server has been added, and (most important
to the overworked and underpaid \AIPS\ installer) {\tt INSTEP1} has
been introduced.  On top of this, the command-line options for
starting \AIPS\ have changed so that disk selection (on a per-host
basis, \ie~ all disks on a given hosts or none), printer selection,
and tv selection (to override the default) is possible.  A Unix
``man'' page for {\tt aips} is included.

The remote tape mechanism has been completely redone.  There is a new
tape daemon {\tt TPMON} that handles requests from remote hosts for
local tape drives --- and uses \AIPS\ Z routines.  These Z routines
have also been overhauled and work well with all the tape drives we
could get our hands on (Sun/Exabyte, Convex/9trk, IBM/Exabyte/9trk,
DecStation/TK50/Exabyte?).

XAS is now the preferred (and best-supported) TV server.  It has all
the features of the others (SSS and XVSS) but only relies on the basic
Xlib routines (it doesn't need any extra toolkits or libraries).

There's more, but you will have to read the {\tt 15APR92} \AIPS~
newsletter for the gory details. \medskip

\medskip

\newsubsection{Notes for the 15OCT92} release.

Most of this is summarized from the {\tt 15OCT92} AIPSLETTER; refer to
it for details.\medskip

\newsubsubsection{The XAS Screen Server}

The TV server {\tt XAS} was overhauled and improved considerably for
this release.  It is now considerably faster, and will try to use the
shared memory extension if the X server running supports it.  This, and
the ability to store up a given number of commands before updating the
screen, can be controlled via the {\tt .Xdefaults} file.  Finally, unix
sockets ({\tt DISPLAY} set to {\tt :0} instead of {\tt <hostname>:0})
are used for {\tt XAS} and {\tt TEKSERVER} windows where possible.  See
\AIPS~ memo 82 for details.\medskip

\newsubsubsection{Tape Access}

Various buffer sizes were increased and considerable extra work went
into making remote tape access faster.  The gory details are to be found
in \AIPS\ memo 80.  Now, accessing a remote tape should be just as fast
as a local tape.\medskip

\newsubsubsection{Fortran Compilation}

The manner in which the {\tt FC} and associated scripts ({\tt COMLNK},
{\tt COMRPL}) determine the optimization and debug level for a given
compilation has been radically changed.  Now, the default compilation
options for all architectures are stored in {\tt\$SYSUNIX/FDEFAULT.SH}
and the optimization/debug level determination is performed by {\tt
FCLEVEL.SH} using the text file {\tt OPTIMIZE.LIS}.  This last file is
essentially a database of what \AIPS\ modules need what level of
optimization and/or debugging.  It allows you to select a single
routine, an area, or all files; also you can select any of these on a
single architecture.  Look at the file (in {\tt\$SYSUNIX}, or
{\tt\$SYSLOCAL} on Suns) for details; it's largely self-explanatory.
The details of what the various \AIPS\ optimize levels {\tt OPT0}
through {\tt OPT9} are is set in the {\tt FDEFAULT.SH} file.\medskip

\newsubsubsection{ZABOR2 and ZACTV9}

These C language routines control exception handling and task
activation, respectively.  The latter now uses POSIX standards and
creates tasks as grandchildren; this cuts down on the occurence of
``zombie'' processes.  The former now allows tasks being run in the
presence of a debugger to trap exceptions normally, unless they are
actually being debugged.\medskip

%%% there's probably more but I can't remember it :-(.  Besides, it's
%%% late at night and I'm tired, coughing and I've had enough of
%%% editing this darn document.

\newsubsection{Notes for the 15JUL93 release}

Two new ports make their debut with this release, one for ``Solaris 2''
on Sparc systems, the other for HP--UX on Hewlett-Packard 9000 series
700 systems.  As both fall into the {\tt BELL} side of the tree, the
support within \AIPS\ for the System V flavor of Unix has improved
significantly.  In addition, several corrections and contributed modules
were received for the Cray (UniCos) and Silicon Graphics (Irix) systems.
On the Berkeley side of the universe, support was improved for the
DEC/Ultrix port, with the upgrade of NRAO's DecStation to Ultrix 4.3 and
DEC Fortran.  A port is in progress at the time of writing to DEC's
Alpha architecture running the OSF/1 (Unix-like) operating system.

The behaviour of \AIPS\ and specifically {\tt FITTP} has been changed.
Prior to this release, two end of file (EOF) marks were always written
at the end of data.  This is correct for 9 track tapes but not for
Exabyte or DAT drives.  All tapes written with \AIPS\ prior to March 30,
1993 in {\tt 15JUL93} or written with earlier releases will need special
treatment with this released version.  See the \thisver\ \AIPS letter
for details on how to work around or fix the problem.

Several speedup improvements and bug fixes found their way into the {\tt
XAS} TV server.  Notable among the bug fixes was the elimination of a
large memory leak when the MIT Shared Memory extension was used.  Again,
see the \AIPS letter for the details.

The Introduction of the Message Server allows task messages to be shown
in a separate window on a Workstation screen.  It can accept messages
from many different \AIPS\ sessions as long as they all use the same
\AIPS\ TV number (\ie, like the {\tt TEKSRV} graphics server, {\tt
MSGSRV} is tied to the TV server).

The tape routines were overhauled (again), and now when the users {\tt
mount} a tape, \AIPS\ will report back what it thinks was really
mounted.  This will in most cases require that the tape be physically in
the drive before the {\tt mount} command is issued.  The tape density
selection now really sets the density on most systems, including Exabyte
8500's on Suns and IBMs.

There is a good section in the \AIPS letter on the Object Oriented
Fortran code.  If you are considering writing a new \AIPS\ task, it will
probably save you a lot of grief if you read this section and the 
\AIPS\ memo (\#78) that describe the interface.  Most of the new tasks
in this release are written using this OOP interface.

The \AIPS\ preprocessor now allows nesting of include files up to three
levels deep.  It announces this each time it is run.

The ability to have two sets of libraries --- debug and
non-debug/optimized --- on Sun systems (SunOS 4 and 5) is introduced in
this release.  Also, the ability to use shared libraries was extended to
HP systems and SunOS 5.

Most, if not all, of the \AIPS\ C code is now capable of being
compiled by an ANSI C compiler.  In addition, as much of the code as
possible was made to comply with the POSIX--1 standard.  Most Berkeley
flavored code has been eliminated in the generic area, although the use
of the socket library is an exception; the Z routines that operate on
these now resides in {\tt\$APLUNIX} as we have found them to be
available on even the least Berkeley-like Unix systems.

Many of the shell scripts that used the {\tt ps} command to check for
processes had to be changed, as its syntax is different for System V
Unix.  Also, the printing scripts had to accomodate both the {\tt
lpr}/{\tt lpq} Berkeley printing commands and the {\tt lp}/{\tt lpstat}
System V commands.  

\newsection{Known Problems} %%% nah.

This chapter contains at least a partial list of the things that are
known to be problems with Unix/\AIPS\ or \AIPS\ in general and that we
should ultimately address as time allows.  You are encouraged to add
to this and other lists via the \AIPS\ {\tt gripe} or {\tt GREMAIL}
facility.

This section has not yet been completely updated.  We'll get it done
yet.  Hopefully before the final release of old \AIPS.  
\medskip 

\newsection{Updating User Data Formats}

If you have no previous installation of \AIPS\ in production, you can
totally ignore this chapter.  However, if you have existing data on disk
that was created with a version of \AIPS\ older than {\tt 15OCT90}, the
formats of some of the data files may be incompatible with the newly
installed version of AIPS.  Before that release, changes of \AIPS\ data
formats were done with a program called {\tt UPDAT}.  However, the
changes involved in the conversion to the {\tt 15OCT89} and later
releases are so great that no special purpose translation task was
prepared.  Older files must be written to and read from FITS files to be
used in {\tt 15OCT90} and later versions.

% After a format version change remove the comment delimiters, and
% finish converting runoff to TeX...
% \medskip
% 
% \newsubsection{Running UPDAT}
%
% The data conversion program UPDAT will convert files from an old
% format to the current format and rename it to the proper name
% containing the appropriate format code letter.  UPDAT knows which
% file names have which format by the letter code embedded in the
% file name, so it is impossible to corrupt data by running UPDAT twice
% for the same data.  UPDAT currently performs no useful function.
% The program UPDAT can be run with the following command:
%
% .skip 1
% \medskip
% RUN UPDAT
% \medskip\noindent
% .skip 1
% The program responds with the following prompt.
% .skip 1
% \medskip
% ENTER : 1=RANGE OF USERS, 2=USER NUMS IN TEXT FILE :
% \medskip\noindent
% .skip 1
% You can choose the user numbers for which you want to run UPDAT by two
% methods: (1) give it a range of users, or (2) set up a file,
% {\tt\$AIPS\_VERSION/HELP/USERLIST.HLP, containing a list of user numbers,
% one to a line.  If you choose (1) (a range of user numbers) you will
% get the following prompt:
% .skip 1
% \medskip
% ENTER USER NUMBER RANGE. (DEFAULT=    1 4095)  :
% \medskip\noindent
% .skip 1
% Other default values may appear for your system.  To select the
% default just press carriage return.  If you want to run it for a
% different range enter two numbers on the same line separated by at
% least one blank.  Entry is free format.  You will get two more
% prompts:
% .skip 1
% \medskip
% ENTER AIPS DISK NUM RANGE (DEFAULT=  1  1)  :
%
% ENTER OLDEST VERSION DATE AS 15MMMYY  (DEFAULT= 15OCT89 ) :
% \medskip\noindent
% .skip 1
%
% The program will then display a summary of the data you have entered
% and give you a chance to re-enter.
% .skip 1
% \medskip
% USER NUMBER RANGE :     1  100
% DISK RANGE        :     1    1
% OLDEST DATA       : 15OCT89
% ENTER : 1=I MADE A MISTAKE, REENTER, 2=CONTINUE :
% \medskip\noindent
% .skip 1
% At this point UPDAT will go through all user numbers that you
% specified and update their data.  UPDAT may be silent for a long time
% as it searches though the range of user numbers without finding any
% data.
%
\medskip

\newsection{Vendor Specific Notes}

\newsubsection{Introduction}

No two Unix systems are identical.  In fact, on the same Unix system, no
two Operating System (OS) levels are identical when it comes to \AIPS.
NRAO supports some better than others, largely because we can't afford
one of everything (even though we'd like to, especially the faster
ones$\dots$).  Many of the notes below are somewhat dated and some of
the problems will have been resolved as a result of the source code
overhaul ({\tt 15OCT89}), the network retrofit ({\tt 15APR92}) and later
releases.  However, you may still be able to glean some solutions to
problems you encounter from the notes below.\medskip

\newsubsection{Alliant Systems}

The last port to the Alliant FX/series was in September 1988 using
\AIPS\ release {\tt 15APR88} with Fortran 3.1.33, libmath\_v4.0,
striped disk, ACEs and System Configuration for FX80 supermkt (serial
\# 109 ):

\medskip \fortran
   Memory Size   = 96 Mb
   CE-Cache Size = 512 Kb
   User Memory   = 90.6 Mb
   Paging File   = 134.1 Mb
   Swapping File = 109.7 Mb
   Number of IPs = 6
   M012/M020/VME = 0/0/6
   Number of CEs = 8
   Detach/Attach = 0/8
\endfortran

\medskip\noindent Obviously this is somewhat dated, so installers of
\thisver\ should proceed with caution (We would welcome additional
notes from \AIPS\ managers with Alliant systems; please e-mail to {\tt
aipsmail@nrao.edu} if you can help).

\item{1)} For single CE configurations, Q-routines and those modules listed
in the obsolete file {\tt \$SYS\-CVEX/\-OPT2.LIS} (yes, {\tt \$SYSCVEX})
should probably be compiled with optimization level {\tt -Ogv -DAS}.
All other Fortran code should probably be compiled {\tt -Og -DAS}.

\item{2)} For multi-CE configurations, Q-routines and those modules listed in
{\tt\$SYSCVEX/OPT2.LIS} (yes, {\tt\$SYSCVEX}) should probably be
compiled with optimization level {\tt -O -DAS -alt}.  All other
Fortran code should probably be compiled {\tt -Ogv -DAS}.  Compiling
all code {\tt -O -DAS -alt} does not seem to improve performance
significantly and results in execution errors in a few routines (\ie,
{\tt\$APLSUB/PASENC}, {\tt ZR32RL}, {\tt ZRLR32}, {\tt ZR64RL} {\tt
ZRLR64} and probably others that were not exercised by our ``Dirty
Dozen Test'').

\item{3)} In multi-CE configurations with detached singleton CEs, those
programs NOT involving concurrent or vector/concurrent code (\eg, no
Q-routines or {\tt\$SYSCVEX/OPT2.LIS} modules) should probably be
linked using the {\tt -nc} option which prevents them from executing
on the CE cluster.  It may be easiest to make {\tt OPT0="-nc"} with
{\tt LINK="-v \$OPT0 \$DEBUG''} in {\tt LDOPTS.SH} and relink the
smaller number of programs you DO want to execute on the CE cluster
via {\tt LINK NOOPT0 <module>.o}.

\item{4)} The {\tt WHNALT.o} file found in {\tt\$QALN} was derived
from proprietary Alliant source code that we cannot distribute.  {\tt
WHNALT.o} should always be incorporated into your pseudo AP object
library.  {\tt WHNALT} is only called by {\tt\$QALN/QCLNSU.FOR}.

\item{5)} The {\tt WHNALT} routine has been known to fail in a
data-dependent fashion (\eg, the DDT large case {\tt APCLN} problem)
on Alliant systems configured with ACEs.  {\tt WHNALT} has worked for
years without problems on CE configured Alliants.  The modified
version of {\tt QCLNSU} below can be used as a workaround (\ie, in
place of {\tt\$QALN/QCLNSU.FOR}) until the problem can be resolved.
The problem is that sometimes one of the values in the array of
indices returned by {\tt WHNALT} is zero.  The workaround simply
checks for this condition and if so, recalls {\tt WHNALT} (see kludge
immediately following statement label 110).

\medskip
\fortran

      SUBROUTINE QCLNSU (COMP, LMAP, L1MAP, L2MAP, IBX, IBY, JNDEX,
     *   INDEX)
C-----------------------------------------------------------------------
C   QCLNSU does a CLEAN on a list of residuals using a given beam
C   patch
C    Inputs:
C      COMP(4)  R*4  Component vector:
C                 0 => intensity
C                 1 => x in cells
C                 2 => Y in cells
C                 3 => CLEAN loop gain (fractional)
C      LMAP     I*4  number of residuals
C      L1MAP    I*4  First residual in Y window
C      L2MAP    I*4  Last residual in Y window
C      IBX,IBY  I*4  Beam patch half width in X and Y
C                    Residuals with delta X or Y from the component
C                    position in COMP .GE. IBX,IBY are to be ignored.
C      JNDEX    I*4  0 - rel Index in FLUX, IX, IY of next residual
C                    to sub.
C   Input From Vector Work common:
C      IWVEC3   I*4  = IX, X pixel location of residuals
C      IWVEC4   I*4  = IY, Y pixel location of residuals
C      WKVEC5   R*4  = FLUX, Residual flux density
C      WKVEC6,7 R*4  = BEAM, BEAM patch.
C   Output:
C      INDEX    I*4  Index in FLUX of next residual.
C   Useage notes:
C     The following common work vectors are used:
C      IWVEC8   = IDXRAY  => array of x pixel offsets
C      IWVEC9   = IB      => indirect address array
C
C   Alliant version (same as Convex version).
C-----------------------------------------------------------------------
      INTEGER*4 ISAMAX, KMAX, INCX, IDXRAY(1), IB(1), IX(1), IY(1)
      INTEGER*4 L21MAP, NIB, JNDEX
      INTEGER*4 LMAP, IBX, IBY, L1MAP, L2MAP, INDEX, BOFF, BEMADR,
     *   LROW, ADDR, LOOP, XCOMP, YCOMP, N1
      LOGICAL   RECALL
      REAL*4    SUBT, COMP(4), BEAM(1), FLUX(1)
      INCLUDE 'INCS:DAPC.INC'
      INCLUDE 'INCS:CAPC.INC'
      INCLUDE 'INCS:EAPC.INC'
      EQUIVALENCE (IX, IWVEC3), (IY, IWVEC4), (FLUX, WKVEC5),
     *   (BEAM, WKVEC6)
      EQUIVALENCE (IDXRAY, IWVEC8), (IB, IWVEC9)
      DATA N1 /1/
C-----------------------------------------------------------------------
      LROW = 2 * IBY - 1
      BOFF = (IBX-1) * LROW + IBY
      IF (LMAP.LE.0) GO TO 999
C                                        Get component to be CLEANed
      XCOMP = COMP(2) + 0.5
      YCOMP = COMP(3) + 0.5
      SUBT = COMP(1) * COMP(4)
C                                       Get residual offsets
      INCLUDE 'INCS:ZVND.INC'
      DO 100 LOOP = L1MAP,L2MAP
         IDXRAY(LOOP) = IX(LOOP+JNDEX) - XCOMP
 100     CONTINUE
C                                        Compress x window
      L21MAP = L2MAP - L1MAP + 1
 110  CALL WHNALT (L21MAP, IDXRAY(L1MAP), N1, IBX, IB, NIB)
C                                       Kludge to get around Alliant
C                                       ACE "bug" where WHNALT may
C                                       return a zero value in the array
C                                       of indices (\ie, IB).  If so,
C                                       recall WHNALT.
      RECALL = .FALSE.
      DO 120 LOOP = 1,NIB
         IF (IB(LOOP).EQ.0) RECALL = .TRUE.
 120     CONTINUE
      IF (RECALL) GO TO 110
C                                        Subtraction loop
      INCLUDE 'INCS:ZVND.INC'
      DO 200 LOOP = 1,NIB
         ADDR = IB(LOOP) + L1MAP - 1
C                                        Get beam address
         BEMADR = BOFF + (IDXRAY(ADDR) * LROW)
     *      + (IY(ADDR+JNDEX) - YCOMP)
         FLUX(ADDR+JNDEX) = FLUX(ADDR+JNDEX) - SUBT * BEAM(BEMADR)
 200     CONTINUE
C                                        Find largest mag. residual
      INCX = 1
C                                       Call Alliant provided Linpack
C                                       routine = ISAMAX.
      KMAX = ISAMAX (LMAP, FLUX(1+JNDEX), INCX)
      COMP(1) = FLUX (KMAX+JNDEX)
      COMP(2) = IX(KMAX+JNDEX)
      COMP(3) = IY(KMAX+JNDEX)
C                                        Save index of next max.
      INDEX = KMAX
C
 999  RETURN
      END

\endfortran
\medskip\noindent

\item{6)} The call of {\tt\$QALN/SCFFT.o} by {\tt\$QALN/QCFFT.FOR}
has been replaced by a call to {\tt CFFT1D} from Alliant's {\tt
libmath.a}.  Both {\tt QCLNSU.FOR} and {\tt QMULCL.FOR} in {\tt\$QALN}
still call {\tt ISAMAX}, but Alliant's {\tt libmath.a} should now
contain this BLAS level 1 LINPACK routine.  The line {\tt -lmath: ...}
should appear in the link lists (as defined in
{\tt\$SYSLOCAL/LIBR.DAT}) for all programs linked with the Q-routine
object library (see {\tt \$SYSALLN/LIBR.DAT}).  The former {\tt
ISAMAX.o} and {\tt SCFFT.o} as well as the versions of {\tt QCFFT.FOR}
that call {\tt CFFT} and {\tt SCFFT} have been saved in {\tt\$QALN} as
{\tt ISAMAX.O}, {\tt fSCFFT.O}, {\tt QCFFT.CFFT} and {\tt
QCFFT.SCFFT}, respectively, just in case your Alliant's {\tt
libmath.a} does not contain {\tt ISAMAX} or {\tt CFFT1D} yet. Let us
know, otherwise we will eventually delete {\tt ISAMAX.O}, {\tt
SCFFT.O}, {\tt QCFFT.CFFT} and {\tt QCFFT.SCFFT}.\medskip

\newsubsection{Convex Systems}

In the heyday of the Convex era at NRAO, we had 3 Convex C1s that served
as \AIPS\ work horses, one in Charlottesville configured with both an
IIS model 70E and IVAS image display device and two in Socorro, each
configured with an IIS model 70F and one with an IVAS.  All three had
several Gigabytes of striped disk.

However, at the time of writing, two of these Convex systems have been
unplugged, and the third is scheduled for permanent shutdown near the
end of 1993.  Thus, our support for Convex systems in the future will
not be at the level found in older releases.

As of the {\tt 15JUL93} release, we are running \AIPS\ compiled under OS
9.0 with IEEE floating-point selected via the {\tt -fi} compiler switch.
\AIPS\ is also in production use elsewhere on other Convex models,
including the C2 and C3 series.

\item{1)} The {\tt\$SYSCVEX} directory contains a number of files used
in \AIPS\ programming that are setup for Convexes.  These files will
be copied to your {\tt\$SYSLOCAL} directory by the {\tt INSTEP1}
procedure and override the versions found in {\tt\$SYSUNIX}. The {\tt
\$SYSNRAO1} and {\tt \$SYSVLAC1} directories are the {\tt\$SYSLOCAL}
directories for the now-retired NRAO-CV, and NRAO-AOC Convex C1s,
respectively.  These directories may also contain files of interest to
other Convex sites.  The files may also be dated and possibly obsolete,
some having survived from the pre-{\tt 15APR92} epoch.  We have tried to
rely as much as possible on the generic {\tt\$SYSCVEX} files where
possible.

\item{2)} The {\tt\$APLGEN} versions of {\tt ZR32RL}, {\tt ZR64RL}, {\tt
ZRLR32} and {\tt ZRLR64} should suffice for either ``native''
(quasi-VAX F) or IEEE floating point.  Just make sure {\tt SPFMRT} and
{\tt DPFRMT} are set properly in {\tt ZDCHI2.FOR}.  The Generic
{\tt\$APLCVEX} version of this last file is set up for ``native''
floating point, whereas the {\tt\$APLNRAO1} and {\tt\$APLVLAC1}
versions (identical) both use IEEE format.  

\item{3)} The routine {\tt QRECT.S} in the directory {\tt \$QVEX} will now
work for either ``native'' or IEEE floating-point.

\item{4)} You should use {\tt /dev/rmtxx} for any tape definitions in
the {\tt TPDEVS.LIST} file if tape allocation is available on your
system (\ie, {\tt tpmount} and {\tt tpunmount}).  These were referred to
as {\tt tpalloc}/{\tt tpdealloc} in earlier ConvexOS releases.  If not,
the {\tt \$APLCVEX} version of {\tt ZMOUN2.C} should be copied to the
local Z routine directory and modified to eliminate the use of {\tt
tpmount}/{\tt tpdismount} and the definition of the {\tt AMT0n}
environment variables via {\tt ZCRLOG}.\medskip

\item{5)} The Convex Fortran compiler {\tt fc} contained a bug in version
5.0 which involves a feature called {\it global register allocation\/}.
This bug is also found in version 5.1, but was (we think) fixed in
version 5.2 and subsequent versions.  If you have the older version of
the compiler (check with {\tt vers /usr/convex/fc}), you should use the
undocumented compiler flag {\tt -ngr} when compiling code with the
optimization flags {\tt -O1} or {\tt -O2} level, for example,
Q-routines.  Otherwise, incorrect results are possible.\medskip

\item{6)} Version 9.0 and later of ConvexOS broke the old version of
{\tt ZDELA2.C}.  The symptoms were that tasks refuse to go away
when they complete.  The file {\tt\$APLCVEX/ZDELA2.C} will work fine
for this version, but pre-9.0 systems should use the more general
{\tt\$APLBERK} version (otherwise tasks won't even get started!).

\item{7)} {\tt\$APLBERK/ZCREA2.C} failed to compile on ConvexOS 9.0
because of problems in the included file {\tt <sys/mount.h>}.  The
version in {\tt\$APLCVEX} has this include removed.  \medskip

\item{8)} Some larger Convex systems have equally large disk
partitions.  If any of your partitions is more than about 2 Gigabytes,
the algorithm used in {\tt \$APLBERK/ZFRE2.C} to calculate disk space
will fail because of the limitations of a 32-bit integer.  A more
robust calculation method is needed; the current one converts Unix
blocks to bytes and thence to \AIPS\ blocks, hence the potential for
overflow.  One user had a 10Gb partition and {\tt FREE} reported -2
Gbytes free (yes, minus two)!\medskip

\item{9)} The method used in {\tt INSTEP1} to convert the shell scripts
to the Korn shell is not perfect.  It seemed to work on the test
installation, despite stopping silently.  A restart of the procedure
appeared to work without other intervention.  Also, the {\tt LIBR} step
seemed not to work in {\tt INSTEP2} on some libraries, but it worked
fine when done manually.  \medskip

Finally, a reminder: Check the settings of the compiler options in {\tt
CCOPTS.SH}, {\tt LDOPTS.SH}, {\tt AS\-OPTS.SH}, and {\tt FDEFAULT.SH},
adding {\tt -fi} if you have the IEEE hardware, and removing it if not.
Also, remember to edit the default Convex version of {\tt LIBR.DAT}; it
is set up for NRAO's old Convex at Charlottesville and unlikely to be
correct for other sites.

\medskip

\newsubsection{Sun Systems}

NRAO has many Sparc systems dedicated to \AIPS\ use and/or programming.
We no longer have Sun-3's in our \AIPS\ cluster, only IPC, IPX and
Sparc2 systems.  At the time of writing, we have just added a Sparc10
but this is a server and not a production \AIPS\ machine.  The following
notes are based on our own experiences as well as that of others, under
a variety of OS versions, from SunOS 3.5 up through 5.2.

\item{1)}  There are some SunOS 4.x releases that have
caused some problems, in particular 4.1 with version 1.2 of the
Sun Fortran compiler (try to get Fortran version 1.3.1 at least).  We
have not been able to get a working \AIPS\ system with this
combination.  

\item{2)} Most Sun Fortran versions up to 1.4 have a bug that causes random
numbers to be stored in variables initialized with DATA statements, when
the {\tt TMPFS} option is used in the kernel (\ie, when the {\tt /tmp}
partition is mounted on swap; a {\tt df /tmp} will reveal this).  {\it
We have not observed this behaviour in SunOS 5.1 or 5.2}.  If you have
{\tt /tmp} mounted on the swap partition for older OS versions, 
\AIPS\ will not build correctly.  You must either (a) Apply the Sun
patches 100174--01 (and 100175?); (b) remake your kernel without the
{\tt TMPFS} option and mount {\tt /tmp} on its own partition; (c) if you
can, just mount {\tt /tmp} elsewhere anyway; or (d) use the {\tt -temp=}
option of the fortran compiler to force it to use some directory other
than {\tt /tmp} for storage of temporary files during compilation.

\item{3)} There is a problem with {\tt \$APLUNIX/ZACTV9.C} for SunOS
versions {\it earlier than 4.1\/}; it calls {\tt waitpid()} which was
introduced at 4.1.  If you have an earlier version of the OS, use the
generic Unix version ({\tt \$APLUNIX/ZACTV9.C}) {\it from an older
release of \AIPS, \eg {\tt 15OCT92}} instead by moving it to
your {\tt\$ZLOCAL} area.

\item{4)} If you have a really old OS version, 3.5 to be specific, {\tt
f77 -O} compilations can get into infinite loops. 
Compilations that apparently succeed can nevertheless yield execution
errors (\eg, infinite loops, bus errors).  What little performance
improvement you get from {\tt -O} optimization (about 10--20\%) is
probably not worth either the installation or execution problems it
can cause.  Compiling {\tt f77 -P} also fails on a handful of modules
and is probably even less worthwhile to pursue.  A very important
exception to the above is the Q-routine library which should always be
compiled at the highest optimization level possible.  Modules written
in C are also an exception and can be safely compiled using {\tt cc
-O}.

{\item {5)} {On Sun 3 systems, special care should be taken to properly
define the default floating point compiler option for {\tt f77} (Sparc
systems in general don't need any special command-line option for
this).  This may be done in two ways: \medskip
\item{$\bullet$} by defining the environment variables {\tt COMP} and
	{\tt LINK} in your local versions of {\tt FCOPTS.SH} and {\tt
	LDOPTS.SH}, respectively, to include the the desired floating
	point option, or:
\item{$\bullet$} by defining the environment variable {\tt
	FLOAT\_OPTION} as part of your login procedure.
\medskip
The documentation for {\tt f77} describes the various floating point
options.  On Sun 3's you will want to use {\tt -f68881} and \AIPS~ has
ported fairly well under this option in the past.  The default option is
{\tt -fsoft} which has problems.  This is not the preferred option
anyway.  Most Sun--3's are configured with at least the Motorola MC68881
floating-point coprocessor.  No serious problems have been reported with
the {\tt ffpa} option.  This option is, of course, highly desirable for
\AIPS\ code, in particular for the Q-routines, but is only meaningful
for systems configured with a floating point accelerator.  Such sites
have reported performance enhancements of 4-5x on compute intensive
tasks such as {\tt MX}.  Our experience with the {\tt -fswitch} option
indicates that it is probably safe, but generates slow code (about 2x
slower).  

It should be emphasized that NRAO no longer has any Sun-3 systems in its
\AIPS\ environment and thus cannot support these systems at the level it
has in the past.  Sites with such equipment are strongly urged to
investigate upgrade/trade-in possibilities, if at all possible.
}

\item {6)} {Under OS 4.0, program {\tt LINK}s may fail with {\it
\_units undefined\/}.  This does not seem to be a problem with later
OS versions; if you can, try to upgrade to at least 4.1.  The following
will probably suffice as a work around.  Create {\tt\$SYSLOCAL/SYSTEM.C}
containing:\medskip
\fortran
          system_(s,n)
          char *s;
          int n;
          {
              system(s);
              return;
          }
\endfortran
\medskip
Then {\tt CC \$SYSLOCAL/SYSTEM.C} and modify {\tt\$SYSLOCAL/LDOPTS.SH}
so that the link options line looks like: {\tt LINK="\$DEBUG
\$SYSLOCAL/SYSTEM.o /usr/lib/libc.a"}.  

% no longer relevant?
\item{7)} There is a change in the fpa floating-point exception
handling as of OS 4.0.  In {\tt \$APLSUN/ZABORS.C}, the call to {\tt
sigfpe\_handler} should be changed to a call to {\tt fpa\_handler} for
systems with floating-point accellerators.  {\it No modifications are
necessary for Sparc systems.}

% \item{8)} Under OS 4.0, in {\tt \$APLUNIX/ZTPCL2.C}, errno 1 (not owner)
% occurs while closing the 2nd {\it dup'ed\/} (see {\tt
% \$APLUNIX/ZTPOP2.C}) file descriptor for the tape drive.  This does
% not seem to occur in later OS releases so action is {\it only\/}
% needed for SunOS 4.0 sites.  The work around is to copy {\tt
% \$APLUNIX/ZTPCL2.C} to your local Z-routine directory and simply
% comment out the second close statement.

\item{8)} {On some systems (perhaps only those with Xylogics 472 tape
controllers), the routine {\tt ZTPMI2} had been known to fail on partial
record reads (\eg, {\tt TPHEAD}).  The workaround was to always read 32K
bytes into a temporary buffer (\ie, despite the actual number of bytes
requested), then copy the actual number of bytes requested to the output
buffer.  It also seems to require compilation using the {\tt -g} option
(\eg, {\tt COMRPL DEBUG ...}).  

We have no evidence or indication that this is still the case, and the Z
routines for tapes have undergone so many changes, that the ``hack''
listed in previous versions of this document is no longer being
included.  However, it is not difficult to retrofit the technique above
into the modern version of the routine.}
\medskip

\item{9)} If you will be rebuilding the {\tt AIPS.EXE} program while
people are using your \AIPS\ installation, or any other commonly used
program that may be active for long periods of time (days perhaps), be
warned.  When {\tt COMLNK} replaces the binary file, the process running
the old version will inevitably get a {\tt bus error}.  Although Suns
trap {\tt SIGBUS} by default, apparently the error handler code never
gets called because the disk file changed ``underneath'' it.
Fortunately, Suns handle this fairly well and the task just aborts.
You will make fewer enemies if you are aware of this and warn people
before rebuilding anything.

\item{10)} Also if you use shared libraries, you may see some
``unresolved references'' errors from the link phase of {\tt INSTEP3}
and {\tt INSTEP4}; these are non-issues as the so-called references
will never be called by those programs being linked.  As long as the
{\tt COMLNK} termination message is ``ends successfully'', you can
ignore the warnings.

\item{11)} One more thing about shared libraries: their use may force
you to increase swap space on your systems.  At NRAO, most of our Suns
have anywhere from 75 to 105 Megabytes of swap.  80 is a good value to
shoot for.  In large installations, the savings in disk space from the
smaller \AIPS\ binaries in {\tt\$LOAD} is more than offset by the
additional space one has to reserve for swap on many workstations.
\medskip

\item{12)} If you have a very recent version of the Fortran 
compiler, you may want to use {\tt -libmil} in the Fortran {\tt
FDEFAULT.SH} settings (and an appropriate {\tt -cg} setting in {\tt
LDOPTS.SH}) for a slight speed advantage.  Otherwise, the use of {\tt
-libmieee} may be advantageous.  Check your {\tt f77} manual page for
details.\medskip

\newsubsection{Solaris (Sparc) Notes}

Well, we had to implement the change from SunOS 4 to 5 as a different
port, so it deserves its own section here.  As the port is brand-new,
there's not a lot to say --- yet.

\item{1)}  {\tt INSTEP1} will probably warn you that the tape devices
you specify, \eg\ {\tt /dev/rmt/0ln} is not a character-special device.
Ignore these warnings.

\item{2)} {\tt PATH}!!!  Make sure your path variable is set to include
all the wonderful new places where compilers and other tools have
hidden.  You will want {\tt /usr/ccs/bin} and {\tt /opt/SUNWspro/bin} in
there at a minimum.

\item{3)} There may be file locking problems in {\tt /tmp} when using
the {\tt fcntl()} type locks that \AIPS\ now uses.  As part of the
installation testing, a data disk (\#1) was made in {\tt /tmp} on our
Solaris 2.1 machine, and this was in turn mounted on swap space.  With
this configuration, an unexpected lock on a tape lock file got stuck for
no apparent reason.  We do not recommend using {\tt /tmp} on swap to
hold the first \AIPS\ data area.  It {\it might\/} be ok for a scratch
disk, but you may be safer avoiding it altogether.

\item{4)} The Solaris version of the {\tt ZLPCL2} shell script uses
something called {\tt postprint} which we found on our machine in the
{\tt /usr/lib/lp/postscript/} directory.  If you do not have this
command, you should look for another text-to-postscript filter such as
{\tt lwf}.

\item{5)} See item 12 above in the Sun4 section.

%%% More vendor-specific notes on Sun?
\medskip

\newsubsection{IBM RS/6000 Notes}

There are three flavors of C compiler available with AIX (version 3 and
above).  These are {\tt xlc}, {\tt c89}, and {\tt cc}.  The first is the
recommended compiler for AIPS, while the last is usually used for
compatibility with IBM RT and PS/2 applications.

One of the big problems in mixing C and Fortran code on AIX systems is
that, unlike SunOS, ConvexOS, Ultrix, VMS, \etc, the linker does {\it
not\/} append an underscore to the C routine names when they are
called from a fortran main program.  The IBM version of the {\tt PP}
preprocessor shell script will take care of this problem, and the {\tt
INSTEP1} procedure will handle it while building the Fortran
preprocessor (it calls a C routine).  
% @@@
{\bf NOTE}: The {\tt -qextname} option will be used for the next {\tt
15JAN94} release of \AIPS\ so that this problem will go away.

In addition, there exists a fortran {\it and\/} C version of some
well-known system calls such as {\tt getenv()} with conflicting
parameters.  The workaround for this so far has been to use the
IBM-specific {\tt LINK} shell script which explicitly includes the
{\tt libc} and {\tt libbsd} runtime libraries.  No action is needed;
{\tt INSTEP1} sets things up so this is the default {\tt LINK} on all
IBM RS/6000 systems.  

In the early days of AIX \AIPS, some users reported that they
had to add {\tt -D\_POSIX\_SOURCE} and {\tt -D\_ALL\_SOURCE} to {\tt
CCOPTS.SH} to properly get the include files.  We have not found this to
be needed with AIX 3.2 on any of our many IBM systems.  If you find this
to be necessary, please let us know the details.

%%% Need more ibm rs6000 vendor notes or at least make them smoother.
\medskip

\newsubsection{DEC/MIPS (DecStation 3100 \etc) Notes}

\item {1.} The AIPS port to the DEC/Mips architecture (DecStations and
DecSystems) was initially for Ultrix version 4.0 and the Mips-supplied
Fortran compiler (version 2.1).  With the {\tt 15JUL93} release,
% @@@
Ultrix 4.3 and DEC Fortran is finally supported.  After we took into
account the various bug fixes kindly reported to us by several concerned
\AIPS\ Ultrix users outside NRAO, the installation test went remarkably
well on this system (apart from pilot error).

\item{2.} When using the DEC version of the {\tt dbx} debugger, be
careful in believing what it says when printing Fortran {\tt LOGICAL}
variables.  It led the author on a merry wild goose chase because it
almost always prints ``false'' when the logical value is in fact true.
It says ``false'' when it really is false too.  Look at the value in hex
if you really want to know what it is. \medskip

\item{3.} As some DEC-specific file routines like {\tt ZTPOPD.FOR} rely
on the value of {\tt SYSVER} which is in turn set in {\tt ZDCHI2}, do
not mess with this variable.  Also note that {\tt SYSTYP} cannot be used
as another Z routine sets it to {\tt UNIX}. \medskip

\newsubsection{HP 9000/700 Series}

The initial port to these systems was performed on HP--UX 08.09 on
two systems kindly made available to us via internet and guest accounts
by the people at JPL.  Later, the OS there was upgraded to 09.01 with
apparently no ill effects.  The installation testing was done on this
newer system.

It may be that the shared library support does not work as well in the
newer OS version than in the older one.  At least one beta tester
reported this.  Caution is recommended, and if you run into problems
with the shared libraries (or any other part of the HP port), let us
know.  Conversely, if you find shared libraries work well for you, {\it
please\/} let us know the details!

\vfill\eject
\input UGUIDE_APDX_1.TEX
\end
