%%% UGUIDE.TEX -- AIPS Installation Porting Reference for Unix Systems
%%%              Soon to be renamed the Installation Reference Manual.
%-----------------------------------------------------------------------
%;  Copyright (C) 1995
%;  Associated Universities, Inc. Washington DC, USA.
%;
%;  This program is free software; you can redistribute it and/or
%;  modify it under the terms of the GNU General Public License as
%;  published by the Free Software Foundation; either version 2 of
%;  the License, or (at your option) any later version.
%;
%;  This program is distributed in the hope that it will be useful,
%;  but WITHOUT ANY WARRANTY; without even the implied warranty of
%;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%;  GNU General Public License for more details.
%;
%;  You should have received a copy of the GNU General Public
%;  License along with this program; if not, write to the Free
%;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
%;  MA 02139, USA.
%;
%;  Correspondence concerning AIPS should be addressed as follows:
%;          Internet email: aipsmail@nrao.edu.
%;          Postal address: AIPS Project Office
%;                          National Radio Astronomy Observatory
%;                          520 Edgemont Road
%;                          Charlottesville, VA 22903-2475 USA
%-----------------------------------------------------------------------

%%% 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]
%%% Modified for 15JAN94 94.02.15 (late again)       [PPM]
%%% Modified for 15JUL94 94.08.04 (I take the fifth) [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
\def\POPS{{\aipsfont POPS}}     %%% POPS in aips font
\def\dol{{\$}}                  %%% dollar sign; here's another (for emacs):$
\def\bul{{$\bullet$}}           %%% Bullet

\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{15JUL94}
%%% ********************* @@@
\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}
\medskip
\centerline{\sl World Wide Web accessible at}
\centerline{\tt http://info.cv.nrao.edu/aips/}
\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 document is intended as a reference for \AIPS\ managers installing a
new version of \AIPS\ on a Unix\footnote*{\eightpoint UNIX is a registered
                                          trademark in the United States
                                          and other countries, licensed
                                          exclusively through X/Open
                                          Company, Ltd.}
%%% placeholder, leave me be!
machine.  It describes the 4 phases of \AIPS\ installation and much of
what goes on behind the scenes.  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, Alpha, SGI, Linux); if you are installing \AIPS\ on one of
these systems, please use that document as your primary guide.  You should
use this ``porting reference'' when installing \AIPS\ on new, untried
systems, and/or if you want a more detailed explanation of the various
steps of installation for all systems, new or otherwise.

\AIPS\ has had a long association with the proprietary VMS system from
Digital Equipment Corporation, and the installation process described here
has many of its roots in the AIPS VMS install process.  Hence there is no
``{\it make aips\/}'' command or overall ``Makefile''.  Furthermore,
because there are many variants of unix, it is not always possible to have
an installation procedure that will run on all of them with no problems
whatsoever; the shell scripts that comprise the bulk of the Unix
installation process for AIPS come close, or so the author hopes.

%%% @@@ change for 15JAN95...

With the {\tt 15JUL94} release, there are once again two types of
installation available: a ``source-only'' tape, which will require
re-compilation and rebuilding of the programs, and a ``binary'' tape which
has pre-built programs as well as the source code.  The source-only tape
is available (as usual) via ftp on the internet, but due to their large
size, the binary tapes are only available as actual tapes (DAT and
Exabyte).  Also, binary tapes are only available for a limited set of
systems (see below).

Regardless of whether you are performing a new port, a source-only
installation on a well-known system or a binary installation, the initial
procedures are essentially the same.  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.  Each
step has an associated shell script (Unix equivalent to a VMS command
procedure or a DOS batch file), and these have names like {\tt INSTEP1},
{\tt INSTEP2}, \etc.  In reading these following sections, don't worry too
much about the details; just try to get an overall view of what needs to
be done.

{\tt INSTEP1} is common to both source-only and binary installations,
whereas the remaining INSTEPs (2, 3, and 4) are only necessary for
source-only installations.  However, there is some advice in the sections
on some of these subsequent steps that is relevant to binary
installations; where this is the case, it will be indicated at the
beginning of the section or sections.

\medskip\newsubsubsection{INSTEP1: Setup and Unpacking}

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

%%% @@@ edit as appropriate
Unlike the previous versions of this script, the {\tt 15JUL94} version
can actually offer to start the editor for you on the relevant files that
need modified and/or customized.  It also tries to detect as much about
your system as it needs to know, even checking printcap files for printer
names if necessary.

\medskip\newsubsubsection{INSTEP2: Massive Compilation of Libraries}

The {\tt INSTEP2} shell script will recompile all the necessary
subroutines into the right libraries.  It is not necessary to run it for
binary installations.  This script, and the {\tt INSTEP3} and {\tt
INSTEP4} scripts will have been copied to an architecture-specific area;
this allows different architectures to be installed at the same time.
There is unfortunately no {\it Makefile\/} for this or the following
steps, although the scripts comes fairly close to doing most of the same
things.

For new ports, it will be necessary to create some new directories, define
names for them in {\tt AREAS.DAT}, edit the {\tt LIBR.DAT} file, modify
the compiler and linker settings, and more, before starting {\tt INSTEP2}.
For ``known'' systems, most of this is unnecessary (though running {\tt
INSTEP2} is necessary).  The script 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 1400
routines in all, depending on the target system.
%%% @@@ check this - wc -l *.LIS on ARCH/INSTALL/
One nice feature about {\tt INSTEP2} (and the following steps too) is that
they checkpoint themselves.  This means that if the script stops for any
reasons (\eg, you run out of disk space, the computer crashes, someone
accidentally kills the process, or a routine fails to compile), you can
continue where you left off without having to redo the previous good
compilations.

If you are porting \aips\ to a new system, there are some
machine-specific or "Z" routines that require local development.  Unless
the new system is very different from most Unix systems, there will
probably only be a handful of these.  The generic versions should
suffice well into the installation process, or you may find acceptable
versions in one of the other systems or ``architectures''.

The number-crunching heart of \AIPS\ is the set of ``Q'' routines.
Originally intended for Array Processors, the ``pseudo array-processor''
or PSAP routines is general enough that it does not need modified for most
new ports.  You may want to look at creating optimized versions of some of
these to increase performance, however.

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.  {\it
For systems that \aips\ is already ported to, 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 appropriately named architecture-specific
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! \medskip

As about 400 routines precede the Z-routines, the first part of {\tt
INSTEP2} is a good time to look at the few Z-routines that require local
development {\it for new ports only\/} (see the appendix on this topic).
If your system is fast at compiling, you might want to address the Z
routine changes before starting {\tt INSTEP2}.  On processors where
``little endian'' byte ordering is used, the value of {\tt BYTFLP} as set
in the routine {\tt ZDCHI2} must be correct (see the Dec, Alpha, or Linux
versions; most other systems are big endian).  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.

\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

\item\bul The programs essential to create/maintain \aips\ system files
\item\bul The \AIPS\ task itself, and
\item\bul About a dozen of the most used tasks.

\medskip \noindent
The programs, and ``canned'' versions of the \AIPS\ system files are
provided on binary tapes, but they both must be created for source-only
installations.  Additionally, even for binary tapes, the parameters in the
``canned'' system files may not suit the needs of the site or system on
which you are installing \AIPS; if so, it will be necessary to re-generate
the system files.  {\tt INSTEP1} will offer to do this for you.

The system files include a system parameter file, an accounting file,
batch queue and batch work files (the batch feature is optional), a
password file, image catalog files, a task communications file, a
``gripes'' file, and {\aipsfont POPS}\footnote\dag{\eightpoint People
                                        Oriented Parsing System, \ie, the
                                        \AIPS\ command language}
%%% placeholder
memory files.  These are created via the program {\tt FILAIP} which
prompts for its inputs.  After creation, the memory files must be
initialized by the {\tt POPSGN} program.  Finally, the program {\tt
SETPAR} should be run to set the system parameters not set by {\tt
FILAIP}; usually this just means setting the system name.

For those systems with \AIPS\ TV displays other than X11 or Sunview screen
servers, the program {\tt SETTVP} should also be run to change the default
TV parameters.  It is not necessary to run it otherwise, unless you
changed the parameters in the header files of the screen server(s).

After these programs have been run, you are ready to run a basic
stripped-down \AIPS\ system (or a full-blown one if installing from a
binary tape).  Other details, such as network services, need to be
addressed before the network and graphical features 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 the shell script {\tt SYSETUP} and a {\tt SETSP}
program (the latter is compiled in {\tt INSTEP4}).

Most of the task binaries 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 85.  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 316 separate programs,
%%% @@@ check number, correct for 15JAN94
this can easily take as long as, or longer than {\tt INSTEP2}.\medskip

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

Throughout this document, \AIPS\ directories will sometimes 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.

The notation used to refer to these environment variables here is the same
that you would use to actually expand them on the Unix command line.  This
means that, for a variable called ARCH, if you type:\medskip

\line{\hskip 2cm \tt \dol\ echo \dol ARCH \hfill}\medskip

\noindent the computer will ``echo'' or print the value contained in that
variable.  In the remainder of this document, such variables (or rather
their contents) will be referred to by, \eg, {\tt\dol ARCH} in typewriter
font with the dollar sign preceding the name.

A few of the most common ``logicals'' or environment variables, used very
frequently in this document and in \AIPS, are:\medskip
%%% @@@ may not need this page eject:
\vfill\eject
\item\bul {\tt\dol ARCH}, the architecture of the computer
        (a combination of the Operating System and Hardware)
\item\bul {\tt\dol HOST}, the host or computer name
\item\bul {\tt\dol SITE}, the site name (may cover multiple hosts)
\item\bul {\tt\dol SYSUNIX}, a directory where many Unix shell scripts,
        setup files and programs are kept
\item\bul {\tt\dol SYSLOCAL}, a site- and architecture-specific
        directory where local setup information and \AIPS\ utility
        programs are kept
\item\bul {\tt\dol AIPS\char95 ROOT}, the top-level directory of your
        \AIPS\ installation.

\medskip\noindent
Some of the essential \AIPS\ environment variables will be defined for you
by the {\tt LOGIN.CSH} or {\tt LOGIN.SH} scripts; you will be instructed
to insert a call to one of these in your login file later in the
installation process.  However, the bulk of the variables are defined
after one of these files has been called, usually by typing {\tt\dol
CDTST} at the Unix command line.  This will define a variable for most of
the directories in the \AIPS\ directory tree; these are required by the
compilation and linking shell scripts, but not for routine running of
\AIPS itself.

While almost all Unix systems now have the {\tt printenv} command, some
may not have an environment big enough to fit all the \AIPS\ programming
environment variables.  This is especially true if your \AIPS\ root
directory is a long pathname.  If you get messages about ``environment
overflow'' or find that some variables are just not defined when they
plainly should be, it may be necessary to remove the symbolic link or
shell script {\tt PRINTENV} from your {\tt\dol SYSLOCAL} area, and build
the {\tt PRINTENV.C} program (found in {\tt\dol SYSUNIX}) there instead.

\medskip\newsubsection{Directory Structure}

The original directory structure of AIPS is described 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\dol DOCTXT/APPENDIXA.TEX}\footnote*{\eightpoint printed copies are
                                        available from the AIPS Group in
                                        Charlottesville}.
For the {\tt 15APR92} and subsequent versions of \AIPS, 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.
This version scheme is described in the section ``AIPS Versions'' later in
this document.  Thus, in the top-level directory where your
\AIPS\ installation will live, there will be the following
sub-directories:\medskip

\vbox{\settabs
\+\quad\quad X &TEXT XXX\quad &\cr
\+&\thisver     & Source and version-specific files (most of \AIPS)\cr
\+&BIN          & Contains some files used during a binary installation\cr
\+&DA00         & Holds areas for host-specific system files, also config
                  files \cr
\+&FITS         & Default location for import/export of FITS disk files\cr
\+&RUN          & User-created run files are stored here (optional) \cr
\+&TEXT         & Ionospheric data, color schemes (OFM's), and
                  documentation (PUBL)\cr
}\medskip

\noindent In addition to \thisver, there may be similar directories for
older versions of \AIPS.  Under each version-date directory are (at least)
the following:\medskip

\vbox{\settabs
\+\quad\quad X &SYSTEMXXX\quad &\cr
\+&AIPS         & AIPS main programs and subroutines\cr
\+&APL          & Applications programs and subroutines\cr
\+&DOC          & Documentation area (see also AIPSPUBL above)\cr
\+&HELP         & Help/Explain/Input files for tasks, verbs, \etc \cr
\+&HIST         & Code Management history files \cr
\+&INC          & Include files\cr
\+&Q            & Numeric-intensive (``Pseudo-Array-Processor'') tasks and
                  routines\cr
\+&QY           & Tasks, routines that depend on both Pseudo-AP and TV
                  routines\cr
\+&RUN          & Area for standard procedure or ``run'' files (DDT for
                  example) \cr
\+&SYSTEM       & System and Machine specific files \cr
\+&Y            & TV-specific tasks and routines \cr
}\medskip
%%% @@@ may not need this...
\eject
\noindent Finally, there are (since {\tt 15APR92}) the following
architecture-specific areas under each version-date directory:\medskip

\vbox{\settabs
\+\quad\quad X &IBM3090\quad &\cr
\+&ALPHA        & Digital Alpha AXP systems running OSF/1 \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\footnote\dag{\eightpoint The
                        IBM3090 port did not pass the DDT test for
                        accuracy due to the 370 class floating point
                        format}\cr
\+&LINUX        & Intel PC (386, 486, pentium) running Linux
                  ({\it NOT\/} DOS!)\cr
\+&SGI          & Silicon Graphics running Irix version 5\cr
\+&SOL          & Sun-4 series (Sparc) running SunOS 5 (Solaris 2)\cr
\+&SUN4         & Sun-4 series (Sparc) running SunOS 4 (Solaris 1)\cr
\+&SUN3         & Sun-3 series (Motorola 68020/68030) systems\cr
}\medskip

\noindent
%%% @@@ @@@ @@@ @@@ @@@ is this still true? @@@ @@@ @@@ @@@ @@@ @@@ @@@
Of all these, only ALPHA, DEC, IBM, LINUX, SOL, and SUN4 are actively
supported in-house by NRAO (\ie, we have these systems and they all run
\AIPS\ for us).  CVEX support is not what it used to be due to our lack of
a local system (since March 1994 when {\tt yucca} was de-commissioned).  HP
and SGI are supported via guest account at a couple of outside site (you
know who you are; we are grateful!) and they generally have better support
than other non-in-house systems.
%%% @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@ @@@
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; {\tt INSTEP2,3,4}, logs,
                  \etc\cr
\+&LIBR         & Object (random archive) Libraries (in subdirectories)
                  \cr
\+&LIBRDBG      & Object libraries compiled in debug mode (optional)\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; {\tt
                  SYSTEM/\dol SITE} is your {\tt \dol SYSLOCAL} area.\cr
\+&TEMPLATE     & Only for network installation; template system DA00
                  files.\cr
}\medskip

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

The information in this section is now at least 5 years old, but for the
sake of historic completeness, is included here.

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\dol DOCTXT/F77CONV.TXT}
for more details.\medskip

\newsubsection{AIPS Versions and Multiple Architectures}

\medskip\newsubsubsection{The Canonical Three Versions: OLD, NEW, TST}

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\ memos 73 and 85}.  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 the main users of {\tt TST} and often
find bugs and problems first.  Visitors to NRAO are recommended to use
{\tt NEW}, which was changed only to fix serious bugs.  In this way, the
code ultimately shipped to outside users has been rather thoroughly
exercised, at least on NRAO systems.

%%% @@@ @@@ @@@ @@@ @@@ Update as needed @@@ @@@ @@@ @@@ @@@ @@@ @@@
However, with the development of the \AIPS++ system proceeding (there has
already been one library release), the {\tt 15APR91} release of
``Classic'' \AIPS\ was the last one issued on a quarterly basis.  NRAO is
issuing {\tt 15JUL94} and will continue to issue versions most likely on a
bi-annual basis, the next one planned being {\tt 15JAN95}.  The decision
to make further releases or to change this bi-annual release policy will
be made as needed.  Contact the \aips\ group at {\tt aipsmail@nrao.edu}
for more details.
%%% @@@ @@@ @@@ @@@ @@@ Update as needed @@@ @@@ @@@ @@@ @@@ @@@ @@@
In addition, the released version of ``Classic'' \AIPS\ now corresponds
to the {\tt NEW} version in-house.

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
moth-balled on tape.  However, versions of \AIPS\ starting at {\tt 15APR92}
are incompatible with earlier versions and it is difficult if not
impossible to make a pre-{\tt 15APR92} version coexist with a later
version (it can be done but requires work/expertise).  Too many
system-level directories are in different places.  Also, as the {\tt
HOSTS.LIST} format was changed in {\tt 15JUL93}, it may be difficult to
have it and older versions {\tt 15OCT92} or {\tt 15APR92} coexist with it.
There are a few steps necessary to get such systems to co-operate; the
details are spelled out in the {\tt 15JUL94} release notes later in this
document.
%%% @@@ make sure they are and fix date above!!!

\medskip\newsubsubsection{Multiple Architectures}

As is alluded to elsewhere in this document, it is possible to support
more than a single type of computer/OS from the same \AIPS\ directory
tree.  This of course requires that you use the Network File System (NFS)
or its equivalent, to make the same directory accessible from multiple
systems.  It is critical that the top-level ``aips root'' directory appear
to have identical names on all systems on which you make it available,
otherwise you will defeat the network scheme that \AIPS\ uses.

Once you have installed \AIPS\ on one architecture, here are the steps
you must go through to add a second. \medskip

\item{\bul} If you have two binary tapes, unpack the second one in the
        same place as the first.  You may get complaints about it not
        overwriting existing files, but as these refer to the source files
        and these are identical on all tapes, there is not a problem.
        Ignore such messages.
\item{\bul} If you have a binary tape but want to extend your system to a
        second architecture, you do not need an extra tape or tar file.
        All the source needed for compiling \AIPS\ for an additional
        architecture is already on your tape.
\item{\bul} Log in to the ``second architecture'' system using the same
        account name you used while installing \AIPS\ on the first.  If
        necessary, create this account on the second system.
\item{\bul} Start {\tt INSTEP1}.  As it will find the {\tt INSTEP1.STARTED}
        file from your first installation, it will pick up such things as
        the site name and aips root area.  While it will ask some
        questions that are strictly speaking not necessary, it should
        detect most of the things set up by the first installation.
\item{\bul} If you are performing a source-only installation, proceed as
        you did for the first architecture with preparations for running
        {\tt INSTEP2}, {\tt INSTEP3} and {\tt INSTEP4}.  If the
        architecture you are building on is a well-known one to \AIPS,
        you can probably skip {\tt INSTEP3} as it is a subset of {\tt
        INSTEP4}.

\medskip\noindent If your two (or more) architectures are compatible at
the binary data level (identical byte order and floating point format),
you need {\it not\/} re-run the {\tt FILAIP} and {\tt POPSGN} programs on
the second architecture {\it if\/} you already have done so on the first.
If you simply copy the files in the template area for the first system to
a template area for the second (or make the template directory for the
second system a symbolic link to the first), then the {\tt SYSETUP} script
will finish the configuring of the system files for you.  You will still
need to run {\tt SETPAR} to set the system name.

\medskip\newsubsubsection{Checklist}

The list of items below is intended as a quick summary of what is required
to complete an installation.  For most installations, the majority of the
work will be done by {\tt INSTEP1}; where manual intervention is needed,
this is indicated by items {\it entirely in italics\/}.  Also, items not
relevant to binary installations are indicated by a {\bf o} instead of a
{$\bullet$}.\medskip

\item\bul {\it Create an\/ {\tt aips} account if wanted, and read
        the tape (or tar file) to disk}

\item\bul If you want to have {\tt INSTEP1} automatically start
        your favourite editor on files that need to be edited by hand,
        make sure you have defined the {\tt EDITOR} environment variable
        (\eg, set it to {\tt emacs} or {\tt vi} or whatever).

\item\bul If necessary, convert critical shell scripts, including {\tt
        INSTEP1}.  This is only necessary on some systems where the Bourne
        shell lacks certain features (\eg, shell functions).  Of the known
        systems, only Convex, Ultrix and to a lesser extent OSF/1 have had
        to use alternate shells for some scripts.  Generally the Korn
        shell is a good replacement.  All files in {\tt\dol INSUNIX}, and
        all {\tt *.SH} files in the architecture-specific system area are
        converted initially by {\tt INSTEP1}. Additional files copied to
        {\tt\dol SYSLOCAL} also get converted later.  The conversion
        simply involves editing the first line of each script.

\item\bul Define {\tt\dol HOST} (hostname), {\tt \dol ARCH}
        (architecture), and {\tt \dol SITE} (site name).  See item on {\tt
        HOSTS.LIST} below.  If an old {\tt INSTEP1.STARTED} file from a
        previous installation is found, {\tt\dol SITE} and {\tt\dol
        AIPS\-\char95 ROOT} may be extracted from it.  {\tt INSTEP1} will
        not automatically detect an old version in any other way.

\item\bul If Architecture is new, create {\tt \thisver/\dol ARCH}
        directory and make {\tt LIBR}, {\tt LOAD}, {\tt MEMORY}, {\tt
        PREP}, {\tt SYSTEM} and optionally {\tt TEMPLATE} subdirectories.
        Also make {\tt\dol SYSLOCAL} which is {\tt \thisver/\dol
        ARCH/\-SYS\-TEM/\-\dol SITE}.

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

%%% @@@ Modify next as needed (not yet done)
\item\bul Copy some {\tt\dol SYSUNIX} files to the {\tt\dol AIPS\char95 ROOT}
        area, being careful to save older versions already there.  If an older
        {\tt 15JUL93} or {\tt 15JAN94} version was found, skip some
        unchanged files.  Run {\tt AIPSROOT.DEFINE}.

\item\bul {\it Insert a \/{\tt source LOGIN.CSH} in the \/{\tt
        .login} file (or a \/{\tt .~./LOGIN.SH} in the \/{\tt .profile})}.

\item\bul Make a symbolic link in {\tt\dol SYSLOCAL} to the {\tt
        START\char95 AIPS} shell script.  For Convex/Ultrix, copy the file
        instead, and convert its shell.

\item\bul Define the \AIPS\ versions in {\tt AIPSPATH.CSH} and
        {\tt AIPSPATH.SH} (both of these in {\tt\dol AIPS\char95 ROOT}).

\item\bul Create {\tt\dol NET0} ({\tt\dol AIPS\char95 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\dol HOST}.
        Also create an area for FITS files (defaults to
        {\tt \dol AIPS\char95 ROOT/FITS}), or make it a symlink to somewhere
        else.

\item\bul If necessary, copy {\tt PRDEVS.LIST} from {\tt SYSUNIX}
        to {\tt \dol NET0}; add printer definitions from an old {\tt
        PR\-DEVS.SH} file or from {\tt /etc/printcap} if possible.

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

\item\bul Create the binaries {\tt NEWEST}, {\tt PRINTENV} (or make
        a symlink to {\tt printenv}) and {\tt PP.EXE} in {\tt\dol
        SYSLOCAL}.  Also create {\tt F2PS} and {\tt F2TEXT}.  (Binary
        installations: copy these from the {\tt BIN/\dol ARCH} area).

\item\bul Make an entry in {\tt\dol AIPS\char95 ROOT/HOSTS.LIST} for
        this host, and any of like architecture that will run \AIPS.

\item\bul {\it For new ports, make sure all necessary new source
        directories have been created (one for Z routines to parallel the
        {\tt \dol APLSUN}, {\tt \dol APLSGI}, \etc, areas; possibly for Q
        and -- if you can't use X11 -- Y routines too).

\item\bul {\it Check that the above local directories are defined
        as environment variables in both {\tt CDVER.CSH} and {\tt
        .SH} in {\tt\dol SYSLOCAL}.}

\item\bul {\it New ports only: Check \/{\tt LIBR.DAT} and
        \/{\tt INCS.SH} in \/{\tt\dol 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\bul {\it Edit the \/{\tt *OPT.SH} files in \/{\tt\dol
        SYSLOCAL} to reflect your choice of debug, optimization, \etc, for
        compiling and linking\/}.  Also edit {\tt \dol
        SYSUNIX/FDEFAULT.SH} to set fortran options if you changed them in
        {\tt INSTEP1}, and check {\tt \dol SYSUNIX/OPTIMIZE.LIS}\/}.

\item\bul Choose whether or not to use shared libraries on
        Sun/HP, and a separate set of debug libraries on all systems.

\item\bul Make {\tt XAS}, the X11 (X-windows) TV server if
        desired.

\item\bul Create {\tt\dol ARCH/INSTALL} and create symlinks to
        {\tt\dol INSUNIX/INSTEP[234]} there.  Move there and get ready to
        start {\tt INSTEP2}.

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

\medskip\newsubsection{Disk Space Requirements}

A full-blown \AIPS\ system with no files removed for disk space saving
will take anywhere from 200 to 300 Megabytes, depending on several
factors.  Most of this is tied up in the binaries (executable files, the
{\tt *.EXE} files in the {\tt\dol 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 24 Megabytes, or 17 Megabytes for the version compressed with the
GNU {\tt gzip} utility.  The uncompressed source code is about 75
megabytes, including the {\tt TEXT} area for documentation, \etc
%%% @@@ @@@ @@@ @@@ @@@ check it and fix! @@@ @@@ @@@ @@@ @@@ @@@
The {\it AIPS Unix Installation Summary} has a list, in section 5.1,
%%% @@@ keep current!
of the sizes of files on the binary tapes as noted in the preparations for
the release.

\medskip\newsubsubsection{Text Files}

The disk space required for all of the text files that come on the
installation tape is roughly 50 Mbytes.
%%% @@@ figure right for 15JUL94; change as appropriate.
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, including PostScript files}
{\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 (The 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
         \char123\char125\ \char92;}
\medskip

\noindent and similarly for the files {\tt *.C}, {\tt *.INC}, and any
{\tt *.o} or {\tt *.f} or {\tt *.c} files in {\tt \dol 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) will be much greater than
for the code.  The bulk of most \AIPS\ systems is taken up by the contents
of the {\tt \dol 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 \dol LOAD/*.EXE}; how much space
this saves will be system dependent.  It will probably be significant,
however.

The space used by the system files will vary depending on the size of your
installation.  With the binary distributions, the supplied system files
are designed for use with a moderate size setup with up to 10
\AIPS\ hosts, 4 interactive and 2 batch users; varying these numbers will
in turn change the sizes of the files.  For the \thisver\ release, the
size of the system files on the binary tapes is about 8 megabytes.

Space used by the program binaries will depend on architecture, and many
other details.  Factors that can influence the sizes of these files
include:\medskip

\item\bul Debug options options used when \AIPS\ is built, \eg,
        whether the {\tt -g} option to include symbolic debugging
        information is used;
\item\bul Whether or not you ``strip'' the {\tt *.EXE} files; this
        removes any debugging information (binary tapes are shipped with
        stripped {\tt .EXE} files);
\item\bul Type of system; RISC systems (Reduced Instruction Set
        Computers; \eg, Sparc, Alpha, HP, SGI) produce larger binaries
        than CISC (Complex Instruction Set, \eg, Intel, VAX)
\item\bul How much use is made of shared libraries.  The IBM AIX
        operating system, for example, makes extensive and efficient use
        of system shared libraries.  Also important is whether or not
        \AIPS\ shared libraries are used (their use is a trade-off; see
        below).

\medskip\noindent

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!

On Sun and HP systems, \AIPS\ allows for the use of \AIPS-specific shared
libraries.  This is achieved through special versions of {\tt \dol LIBR}
and {\tt\dol LINK} in the {\tt \thisver/\dol ARCH/SYSTEM} area (which will
be copied to your {\tt\dol SYSLOCAL} by the installation procedure).  The
file {\tt USESHARED} must exist in {\tt\dol 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, if you are
performing a source-only installation.  Another file, {\tt NOSHARE.LIS},
must also exist.  It specifies any programs that should {\it not} be built
with shared libraries.  There are many files in the {\tt SUN4} version of
this file, many of these probably need not even be there.  There are no
Solaris or HP versions of the file.  All binary tapes are shipped from
NRAO with static \AIPS\ libraries.

For shared libraries, the resultant size of the binaries is on the order
of 100 Megabytes for {\tt SUN4}.
%%% @@@ checked (98.39) for 15JUL94; use this to find out (dl in my .profile):
%%% du -s *.EXE | awk '{x += $1} ; END {print "total kilobytes: " x}'
%%% (extra dollar for emacs TeX mode: $)
If the system is built without using shared libraries and in debug mode,
the size will be closer to 300 Megabytes.  As indicated above, stripping
the {\tt *.EXE} files, and/or building without debug flags, will reduce
the size somewhat.  There is a trade-off, however; if you use shared
libraries, you will most likely need to {\it increase the swap space on
your systems\/}.  At NRAO, we typically have between 70 and 105 megabytes
of swap.  In a site with more than two or three \AIPS\ hosts, the savings
from smaller binaries in {\tt\dol LOAD} are more than offset by the amount
of disk space that has to be reserved for swap on each system.

There have been some problems with shared libraries on newer OS versions
of HP--UX.  Caution is advised for HP installers; if disk space is not a
major issue, you may want to stick with non-shared libraries.
%%% @@@ still?

\medskip\newsubsection{System Directories}

The directory {\tt \thisver/SYSTEM/UNIX} contain shell scripts and
configuration files used by \AIPS (the older VMS command files are in the
{\tt\thisver/SYS\-TEM/VMS} area).  In addition, there are directories
under {\tt\thisver/\dol ARCH/SYSTEM} for different flavors (architectures)
of Unix.  A list of these may be found earlier in this document under the
{\it Directory Structure\/} section.

The installation procedure will create a subdirectory for site specific
procedures and definitions.  This will be {\tt \thisver/\dol
ARCH/SYSTEM/\dol SITE} and is usually referenced by its environment
variable name, {\tt\dol SYSLOCAL}.  There is also a directory called {\tt
\thisver/SYSTEM/UNIX/INSTALL} where the Unix version of the \AIPS\ install
scripts are stored.  As part of {\tt INSTEP1}, a site- and
architecture-specific area {\tt\thisver/\dol ARCH/INSTALL} is created, and
is populated with symbolic links pointing at the master versions of {\tt
INSTEP2}, {\tt INSTEP3}, and {\tt INSTEP4}.  The compiling and linking for
each architecture will then be done from the architecture-specific area,
enabling simultaneous installations to be performed in a single {\tt
AIPS\char95 ROOT} directory tree.  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 former Convex sites, and are provided as examples of working Convex
installations.  However, all of NRAO's  Convex systems have now been
de-commissioned and there may be problems with newer versions of
Convex OS.

\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 also the \AIPS\ TV
servers.  Since the {\tt 15APR92} release, all TV servers use the same
set of Y routines ({\tt\dol 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, Dec 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 (with one exception).
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 (obsolete)
\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
basis for the model behind 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 widespread availability of fast,
inexpensive RISC and other fast 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 here that
can be safely removed.  Strictly speaking, 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 \dol 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 \dol CDOLD}, {\tt \dol CDNEW} or {\tt
\dol CDTST} commands, whichever is appropriate; these are described later
in this document and redefine on the fly the many environment variables
that point to the different directories (and that depend on the version
date).  For most installations, this will only be done once, typically in
the {\tt .login} or {\tt .profile} file.

There are several other architecture-specific system directories {\tt
\thisver/\dol 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\dol
SYSLOCAL} area in a rational way, using {\tt\thisver/\dol
ARCH/SYS\-TEM/\dol SITE} as the directory for {\tt\dol SYSLOCAL}.  If none
is appropriate (\ie, you are doing a new port), choose the closest or if
necessary the generic {\tt \dol SYSUNIX} files.  The few C programs and
the preprocessor (in the {\tt \dol SYSUNIX} area, currently {\tt
NEWEST.C}, {\tt PRINTENV.C}, {\tt PP.FOR}, {\tt F2PS.C}, and {\tt
F2TEXT.C}) will need to be compiled and linked as part of the
installation.  Again, this will be attempted by {\tt INSTEP1} but you may
have to do it by hand if it fails.  If there is a {\tt printenv} command
in your path during {\tt INSTEP1}, then a {\tt PRINTENV} symbolic link is
simply made to it in {\tt\dol SYSLOCAL}.  Again, it may be necessary to
build {\tt PRINTENV} by hand if the system {\tt printenv} cannot handle a
large number of rather long environment variables.

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\dol AIPS\char95 ROOT} area:\medskip

{\parindent=3.7cm
\item{\tt AIPS.BOOT\quad} (optional) commands to run at boot time:
                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\char95 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 \dol AIPS\char95 ROOT/HOSTS.LIST}).
\item{\tt INSTEP1\quad} Will be a copy of the {\tt\dol INSUNIX/INSTEP1}
                procedure.
\item{\tt INSTEP1.STARTED\quad} holds definitions of {\tt SITE} and {\tt
                AIPS\char95 ROOT} from one run of {\tt INSTEP1} to the next.
                Also stores the \AIPS\ version, e.g. \thisver.  Keep it
                around for a possible {\tt 15JAN95} installation. % @@@
\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).  Insert a call to the relevant
                one from the {\tt .login} or {\tt .profile} of any account
                that will run \AIPS.
\item{\tt PRDEVS.SH\quad} Symbolic link to the generic {\tt\dol SYSUNIX}
                version; inserted here for backwards compatibility with
                older versions of \AIPS.  See below.
\item{\tt START\char95 AIPS\quad}  Starts up the \AIPS\ program (via {\tt
                AIPSEXEC}); called via {\tt aips} or {\tt AIPS} symlinks
                in {\tt\dol SYSLOCAL}.
\item{\tt START\char95 TPSERVERS\quad}  Starts up {\tt TPMON} daemons for
                remote tapes (may be called via {\tt rsh}).  If called
                with {\tt -d} as argument, gives verbose messages.
\item{\tt START\char95 TVSERVERS\quad}  Starts up XAS and the other window
                servers {\tt MSGSRV} and {\tt TEKSRV} (may be called via
                remote shell command).
\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 (if none of either, needs no
                change and can be a symlink to {\tt\dol SYSUNIX} version).
}

\medskip

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

{\parindent=3.7cm
\item{\tt CDVER.SH\quad} and {\tt .CSH}: Change \AIPS\ version and
                programming environment variables (called by
                {\tt\dol 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, \eg, on a convex).
\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\dol SYSUNIX} area:\medskip

{\parindent=3.7cm
\item{\tt AIPSCC\quad}   Runs local C compiler (uses {\tt
                         \dol SYSLOCAL/CCOPTS.SH}).
\item{\tt AIPSEXEC\quad} The script that actually starts \AIPS\ (called
                         by {\tt START\char95 AIPS}).
\item{\tt ALLRSH\quad}   Do a command on all \AIPS\ hosts via {\tt rsh} or
                         {\tt remsh}.
\item{\tt AREAS\quad}    (Re)Makes {\tt AREAS.SH} and {\tt .CSH} from
                         {\tt\dol SYSAIPS/AREAS.DAT}.
\item{\tt AS\quad}       Runs local Assembler (uses {\tt
                         \dol 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}).
\item{\tt COMRPL\quad}   Runs Compiler only, not for main programs (uses
                         {\tt SEARCH}, {\tt PP}, {\tt AS} or {\tt CC} or
                         {\tt FC}).
\item{\tt CREADIR\quad}  Creates empty \AIPS\ directory tree based on
                         {\tt\dol SYSAIPS/AREAS.DAT}.  Obsolete.
\item{\tt DADEVS.SH\quad} Defines data disks from files {\tt NETSP} and
                         {\tt DADEVS.LIST} in {\tt\dol NET0} (or {\tt
                         DADEVS.LIST} in {\tt\dol DA00}, or {\tt .dadevs}
                         in login area).
\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\dol SYSUNIX}).
\item{\tt FCLEVEL.SH\quad} Reads file {\tt OPTIMIZE.LIS} from {\tt
                         \dol SYSLOCAL} or {\tt\dol SYSUNIX} and determines
                         debug, optimize level for the program or
                         subroutine being compiled.  Called by {\tt FC}.
\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 GREP}\quad}   Finds files containing strings in subdirectories.
\item{{\tt LGREP}\quad}  Like GREP except this one is case sensitive.
\item{\tt LIBR\quad}     Builds/updates object libraries in {\tt
                         \dol LIBR/*/} (uses {\tt \dol SYSLOCAL/LIBR.DAT}).
\item{\tt LIBS\quad}     Generates library list needed for programs in a
                         given source code area; uses {\tt
                         \dol SYSLOCAL/LIBR.DAT} (versions also in Sun, Sol
                         and HP local areas).
\item{\tt LINK\quad}     Runs local Linker (loader); uses {\tt
                         \dol 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 \dol SYSLOCAL/LIBR.DAT}).
\item{\tt PP\quad}       Shell wrapper to preprocess source code (for
                         fortran, calls {\tt \dol SYSLOCAL/PP.EXE}).  Local
                         version for {\tt IBM} and {\tt CRI}.
\item{{\tt PROG}\quad}   ``What directory is program FOOBAR in?''
\item{\tt PWD\quad}      Show current working directory without
                         automounter (\eg, {\tt /tmp\char95 mnt}) directory;
                         may fail for some configurations.  Uses
                         {\tt\dol PWD} if it can.
\item{\tt RUN\quad}      Run programs other than {\tt AIPS} or {\tt
                         BATER}.  Calls {\tt DADEVS.SH}.
\item{\tt SEARCH\quad}   find appropriate version of a module (calls
                         {\tt NEWEST}, uses files
                         {\tt\dol SYSLOCAL/SEA\-RCH*.DAT}).
\item{{\tt SHOPH}\quad}  Used for checking the shopping lists used by
                         the new {\tt ABOUT} adverb.
\item{\tt SSSERVERS\quad} Start up Sunview version of \AIPS\ TV server.
                         (may not work; untested for years).
\item{\tt STARTPMON\quad} Start up {\tt TPMON} daemon(s).  Called by
                         {\tt START\char95 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} Defines tape names,
                         uses table {\tt \dol NET0/TPDEVS.LIST}
\item{\tt WHICH\quad}    \AIPS\ wrapper for ``find'' command.
\item{\tt WHOUSES\quad}  Shows which binaries ({\tt *.EXE}) use a given
                         routine.  Takes a {\it long\/} time.
\item{\tt XASERVERS\quad} Start up the XAS X11 \AIPS\ TV server.  Called
                         by {\tt START\char95 TVSERVERS}.
\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.
                         Local versions for {\tt SOL} and {\tt CRI}.
%%% @@@ may not be complete.  Check.
}\medskip

\noindent Finally, there are five programs in {\tt\dol SYSUNIX}:\medskip

{\parindent=3.7cm
\item{\tt F2PS.C\quad} (New for {\tt 15JUL94}) Convert Fortran output to
                PostScript (tm) in a few different layouts;
\item{\tt F2TEXT.C\quad} (New for {\tt 15JUL94}) Convert Fortran output to
                plain text (\ie, filter the carriage control in col. 1);
\item{\tt NEWEST.C\quad} Find newest file in argument list;
\item{\tt PP.FOR\quad} The Fortran Preprocessor for \aips; and
\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}\medskip
}
\medskip\noindent
At least two of these programs --- {\tt NEWEST} and {\tt PP} --- 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 attempt to
build binaries in the {\tt \dol SYSLOCAL} area.  The rest of the tools
will assume (a) that {\tt\dol SYSLOCAL} is in your path (the {\tt LOGIN.*}
scripts put it there) and (b) that the programs above are built and placed
in that area.\medskip

\vfill\eject
\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.  On the other hand, for a
single user installation, creating such an account is not necessary.  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 {\tt tcsh} during the installation
process.

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.  You may already have
an existing group that can be used for this purpose.  As the only
alternative to an \AIPS\ group 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 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.  Also, {\tt aipsmgr}, the {\tt aips} account (if any), and any other
accounts that will run \AIPS\ should belong to the {\tt aipsuser} group
mentioned in the previous paragraph.  Then the user data areas and {\it
some\/} system directories ({\tt\dol NET0/*}, {\tt \dol DATA\char95
ROOT/*}, {\tt\dol TSTMEM/*}) 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}.  {\tt INSTEP1} attempts to apply this option where
appropriate.

Do {\it not\/} set the ``t'' bit on these directories; it will cause
many problems.  If this bit is set on {\tt /tmp}, it can potentially
cause problems for \AIPS\ as well.

The {\tt\dol 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.
This script has {\it 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\dol 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\dol AIPS\char95 ROOT/\thisver/SOL} directory to be
on the Solaris machine itself; this can be easily accomplished via a
symbolic link:\medskip

\example{cd \dol AIPS\char95 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/\dol 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.

\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\bul Using the Internet and {\tt ftp}
\item\bul Reading from a Local Tape Drive
\item\bul Reading from a Remote Tape Drive
\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 {\tt aipsmgr}
account if you have one, or failing that the \ttaips\ account.  If you
choose not to create either of these accounts, use the account --- perhaps
your own --- that will be the primary user of \AIPS.  For whichever
account you use, make sure you are in its login area, or wherever the root
of the \ttaips\ directory tree will be.

The {\tt tar} operation (see below) will create several files in this
area: a directory containing the \AIPS\ code ({\tt\thisver}), a second
directory for some ancillary files ({\tt TEXT}), a third directory used in
the binary installations ({\tt BIN}), and a symbolic link to the {\tt
INSTEP1} procedure.  On binary tapes, there will also be a directory {\tt
DA00} which contains pre-built versions of the \AIPS\ system files.  The
actual program binaries are in their final resting places on the binary
tapes; there is no need to move them around after reading the tape.

The {\tt\thisver} 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}.  It also contains
architecture-specific directories for many systems.  You may want to
remove any old {\tt TEXT} area before unpacking the tape (or tar file),
unless you modified files in it (unlikely) in which case you should move
it prior to loading the tape or tar file.  If you leave an old {\tt TEXT}
area, the reading from tape will fail to load newer versions of any
changed files in that area.

\medskip\newsubsubsection{Internet and ftp}

NRAO now encourages sites to obtain the source-only version of \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}).  Unfortunately we cannot provide
\AIPS\ under ``anonymous'' ftp; therefore a special {\tt getaips} account
and (frequently changed) password is used; you will be provided with the
latter 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 If you do not have very much disk space, you may want to combine
them in the following manner (Bourne/Korn/bash shell):\medskip

\example{\dol\ mv \thisver.tar.Z.01 \thisver.tar.Z}
\example{\dol\ for i in \thisver.tar.Z.* ; do}
\example{> \ cat \dol i >>\thisver.tar.Z}
\example{> \ rm \dol i}
\example{> done}
\medskip

\noindent This will go through each piece, appending it to the first one
and removing the appended piece right away.  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.  If you wish to be careful, you can save them on
tape first.\medskip

\newsubsubsection{Local Tape Drive}

Insert the distribution tape into the drive and use {\tt tar} to unpack
it, \eg:\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\bul For SunOS 5.x, HP and SGI systems, use {\tt /dev/rmt/<n>ln}
                 where {\tt <n>} is as above.
\item\bul On the IBM RS/6000 series, use
                 {\tt /dev/rmt<n>} where {\tt <n>} is a number (0, 1,
                 2$\dots$).  Use {\tt smitty tapes} on IBM's to see which
                 tape drive is which.
\item\bul On DecStations and Alpha systems, use
                 {\tt /dev/rmt<n>h} or {\tt /dev/rmt<n>l} (for high
                 or low density).
\item\bul On a Convex, 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.
\medskip

\noindent If in doubt about tape names, check your system documentation,
starting with the manual pages for {\tt mt} if any, or ask your system
administrator.  ``{\it 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
simply causes each filename read from the archive to be printed out as it
is unpacked.

\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 (On HP systems, use {\tt remsh} instead of {\tt rsh})  You use
the appropriate network name of the remote system (the one with the 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.

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 input filename,
and specify blocking factor in that order.  The minus following that tells
it to use the standard input (\ie, output of the {\tt rsh} command via the
pipe) 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 or the {\tt
/etc/hosts.equiv} file.

\medskip\newsubsection{Installation Step 1}

This step involves some editing, moving, and general setup.  The {\tt
INSTEP1} 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 distribution, and you should
see the files {\tt\thisver}, {\tt TEXT}, {\tt BIN}, and {\tt INSTEP1}
(also {\tt DA00} for binary installations).  The directory you are in will
be defined by environment variable {\tt\dol AIPS\char95 ROOT}.

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

\example{\dol~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.

If you want {\tt INSTEP1} to offer you the choice of editing the various
configuration files during the course of the installation, you should make
sure to have the {\tt EDITOR} environment variable defined before
starting.

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, and to a lesser extent OSF/1 (Dec Alpha)..

The {\tt INSTEP1} procedure should be able to detect the ``inferior''
shells on the above-mentioned systems, and it will attempt to convert
certain critical shell scripts to an alternative shell.  For Ultrix, this
is {\tt /bin/sh5} (the System V shell), and on Convex and Alpha systems
{\tt /bin/ksh} (the Korn shell) is used.  INSTEP1 writes a shell script
called {\tt sh-cvt} in the aips root area which 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.  This has occurred in the past (on Convex OS) 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.

On OSF/1 systems (Dec Alpha), the Bourne shell is better but still not
quite good enough for {\tt INSTEP1} so it modifies itself to use the
Korn shell, asks to be restarted and stops.  Just do the obvious: type
{\tt INSTEP1} again.
\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? (NO)}\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.},
%%% placeholder
though a simple {\tt <return>} will give the default response indicated
(if a default response is indicated; some questions require a specific
answer).  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 \dol 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{Existing Installation}

%%% @@@ this changed in 15JAN95!
The way in which {\tt INSTEP1} finds a previous installation is via the
presence of the file {\tt INSTEP1.STARTED}.  If this file exists, it is
scanned at this point and the version defined therein is extracted.
Then it is moved to {\tt INSTEP1.STARTED.OLD} and you are given the
chance to have the previously defined {\tt SITE} and {\tt AIPS\char95 ROOT}
extracted from this older file.  Regardless of whether you choose to get
these older values, a new {\tt INSTEP1.STARTED} is created with the
current version date {\tt\thisver}.

%%% @@@ change as needed
If the older version is {\tt 15JUL93} or {\tt 15JAN94}, certain files in
{\tt AIPS\char95 ROOT} will be preserved as they have not changed in the
{\tt\thisver} release.

\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.  For Convex systems, it makes a symbolic link in the current
area to the dummy {\tt uname} command in {\tt\dol SYSCVEX}.  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 HOST}.  It will be
defined by the file {\tt LOGIN.CSH} or {\tt LOGIN.SH} after the
procedure finishes.

If your site uses fully qualified host names, 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).

In addition, {\tt uname} on systems such as SunOS 4.1 will return a
maximum of 9 characters.  SunOS 5 does not have this restriction.
Because of this, NRAO has found it necessary to create additional
aliases for systems like {\tt antarctica} and {\tt pantagruel} (dropping
the tenth and any subsequent characters to create aliases, e.g. {\tt
antarctic}).

\medskip\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}.

It is possible for multiple sites to share the same {\tt AIPS\char95 ROOT}
area.  This is quite useful if you want to support machines with different
byte order (big, little endian) using just one installation.  For example,
NRAO has two ``sites'' within the Charlottesville installation, {\tt
NRAOCV} for Sun and IBM RS/6000 systems, and {\tt VCOARN} (spell it
backwards) for Dec Alpha, Dec Ultrix, and Linux systems.  As the hosts and
tv information obtained by the various scripts from{\tt HOSTS.LIST} is
restricted to a single site name, it is possible to mix/match different
systems in this manner.

\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/\dol 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 Micro-systems (Motorola 680x0), SunOS 4.x
                        (Solaris 1.x)
\item{\tt SUN4\quad}    Sun Micro-systems (Sparc), SunOS 4 (Solaris 1.x)
\item{\tt SOL\quad}     Sun Micro-systems (Sparc), SunOS 5 (Solaris 2.x)
\item{\tt CVEX\quad}    Convex, Convex OS
\item{\tt DEC\quad}     Digital Equipment Corporation DecStation/system,
                        Ultrix 4.3/DEC Fortran
\item{\tt ALPHA\quad}   Digital Alpha AXP, OSF/1 1.2, 1.3, and 2.0?
\item{\tt LINUX\quad}   Intel 386/486/pentium PC's with Linux (not DOS) 0.99
                        through 1.1.47 (at least)
\item{\tt IBM\quad}     IBM RS--6000 series, AIX 3.1 and 3.2
\item{\tt HP\quad}      Hewlett-Packard 9000/700 systems, HP-UX 8 or 9
\item{\tt SGI\quad}     Silicon Graphics (SG--Irix version 5)
\item{\tt IBM3090\quad} IBM Mainframes, AIX (not fully supported)
\item{\tt ALLN\quad}    Alliant (Concentrix)
\item{\tt CRI\quad}     Cray Research, Inc. (UniCos)
}\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 this in turn is
not found, it looks for the {\tt uname} command, first in {\tt /bin}
and then in {\tt /usr/bin}.  If either {\tt uname} or {\tt arch} is
found after all this searching, they are used to get the architecture.

After all this, the {\tt ARCH} environment variable is examined and
possibly changed.  {\tt AIX} is changed to {\tt IBM}, {\tt ULTRIX} to
{\tt DEC}, {\tt OSF1} gets converted to {\tt ALPHA}, {\tt HP-UX} to {\tt
HP}, and {\tt I386} or {\tt I486} to {\tt LINUX}.  In addition, for {\tt
SUN4}, the OS revision (4.something or 5.something) determines whether
it is converted to {\tt SOL}.  Also, for Solaris, {\tt /usr/ccs/bin} is
added to the path if (a) it's not already in it, and (b) the directory
exists.  If you see a message, you might want to consider adding this
directory permanently to your path in your login or profile.

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 for confirmation.

The following is done for new ports and also for known systems, and the
directory creation and setgid steps are skipped if the directories
already exist:
\medskip

\item\bul Create {\tt\thisver/\dol ARCH} directory, makes it setgid;
\item\bul Create subdirectories {\tt ERRORS}, {\tt ERRORS/\dol 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;
\item\bul Make all these subdirectories ``setgid''.

\newsubsubsection{Create SYSLOCAL Area}

The {\tt\dol SYSLOCAL} directory is architecture-specific, and is found
under {\tt\thisver/\dol ARCH/}.  {\tt INSTEP1} will create it using your
site name, \ie~ {\tt\thisver/\dol ARCH/SYSTEM/\dol SITE/}.  Thus it is the
same for all hosts of the same type in a given installation.

Once the directory exists, any files in the {\tt\thisver/\dol ARCH/SYSTEM}
area are copied to it.  Then a set of standard files are copied to this
new {\tt \dol SYSLOCAL} area from the {\tt \dol SYSUNIX} area
{\tt\thisver/SYSTEM/UNIX}, only if they don't already exist in the {\tt
\dol SYSLOCAL} area.  In this way, all the necessary shell scripts and
setup files are copied, but any architecture-specific versions are used in
place of 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 the Korn or System V shells at this point (see above).  These
are: any {\tt *.SH} files, and copies of {\tt AIPSEXEC}, {\tt LIBR}, and
{\tt LINK} from {\tt \dol SYSUNIX}.

If you had modified any {\tt\dol SYSLOCAL} files in some older versions of
\AIPS\ (either {\tt 15OCT92} or {\tt 15APR92}), 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\dol SYSLOCAL} area from the old one.

\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\char95 ROOT} is not defined, you
will be given the name of the current directory (with {\tt /tmp\char95
mnt} removed from it in case you are using the automounter) and asked to
confirm if this is the {\tt AIPS\char95 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\char95 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\dol AIPS\char95 ROOT} pathname.  Such a name,
\eg, {\tt /u/j.doe/aips}, will cause serious problems to {\tt INSTEP2}, and
it is far simpler to either rename the directory or pick one without a dot
in its name.

\medskip\newsubsubsection{Printer Setup}

%%% @@@ New to 15JUL94, change for 15JAN95

The manner in which printers are configured has changed in {\tt 15JUL94}.
In older versions, the installer had to insert actual shell variable
assignments in the {\tt PRDEVS.SH} file which got copied to {\tt\dol
AIPS\char95 ROOT}.  Now, the definitions are placed in {\tt\dol
NET0/PRDEVS.LIST}, which is a file similar in appearance and concept to
the other list files ({\tt HOSTS.LIST}, {\tt TPDEVS.LIST}, {\tt
DADEVS.LIST}).

There is a sample {\tt PRDEVS.LIST} file in {\tt\dol SYSUNIX} which
contains some definitions that are used in the Charlottesville
\AIPS\ installation.  The actual in-use version is somewhat more
interesting and is shown here:\medskip

\fortran
#-----------------------------------------------------------------------
# PRDEVS.LIST -- List of AIPS Printers for your site
#-----------------------------------------------------------------------
# Place a one-line entry for each printer that you wish to make
# available to AIPS users.  The first column should have the printer
# name as known to /etc/printcap or equivalent.  The second is the AIPS
# printer type, one of PS, PS-CMYK, QMS, TEXT, or PREVIEW for PostScript
# (tm), Color PostScript, QUIC (QMS or Talaris), plain text, or screen
# previewers respectively.
#
# Column three specifies a comma-separated (NO SPACES!) list of options
# for each printer.  Right now there are four possible values: NONE,
# DUP to indicate a duplex printer, DEF to indicate a default printer,
# and BIG[=VALUE] to indicate that this is _the_ "big" printer and any
# print job with more lines than VALUE (default 1000) will be diverted
# there regardless of what printer the user chose.
#
# This version for NRAO-Charlottesville.
#-----------------------------------------------------------------------
# printer  type     AIPS options   Description

ps3dup     PS       BIG=1000,DUP,DEF Library FAST PostScript printer, Duplex
ps3        PS       None             Library Fast PostScript printer, normal
ps1        PS       NONE             Postscript printer downstairs
ps2        PS       NONE             Postscript printer in room 215
pscolor    PS-CMYK  NONE             Color Postscript printer, AIPS Cage
35mm2k     PS-CMYK  NONE             Postscript 35mm slides
ghostview  PREVIEW  NONE             GNU Ghostview X-windows previewer
pageview   PREVIEW  NONE             Sun OpenWindows previewer
lpgb       REMOTE   NONE             QMS1725 Postscript printer in GREEN BANK
$PRINTER   PS       NONE             Printer ${PRINTER-not.available}, type PS
\endfortran

\medskip\noindent There are four main fields in the file; the first three
must be delimited by a space or spaces, while the fourth (the description)
may contain spaces.  The third field (options) may contain multiple items
but these must be separated by commas only.  The comments in the file
describe the format and allowed values fairly well.  There are two
interesting features shown above that may be useful to other sites.  The
first is the ``remote'' printer {\tt lpgb}, and the second is the last
printer {\tt\dol PRINTER}.

For any printer you define as ``remote'', the file to be printed will be
passed to a shell script of the same name as the printer.  In the above
example, there is a shell script {\tt lpgb} that takes one argument (the
filename) and, via a {\tt rsh} command, copies it to a remote printer.  In
cases where you want to give access to remote systems without having your
system administrator configure extra remote printers for the local system,
this can be quite useful.  However, the scheme is only as good as the
shell script you supply.

If you define {\tt\dol PRINTER} as one of the printers exactly as
indicated in the last line of the example above, this definition will only
be useful if the user has defined this variable in their environment.  If
the user has set the variable to {\tt myprint} for example, they will see
the line:\medskip

\example{10.  Printer myprint, assume PostScript}\medskip

\noindent whereas a different user who has no printer defined will instead
see:\medskip

\example{10. Printer not.available, assume PostScript}\medskip

\noindent This is a useful way of configuring personal printers for
individuals without giving everyone easy access to them.

The {\tt INSTEP1} script will attempt to take the information from an old
{\tt PRDEVS.SH} file, if one is found, and convert it to the newer format
automatically.  If you have the {\tt EDITOR} environment variable defined,
you will be given the option of editing the resulting file at that point.

If an older {\tt PRDEVS.SH} file is not found, the script presents you
with a summary of the types of printers and the options.  Then it checks
if there is a file {\tt /etc/printcap}, and if so it will attempt to parse
its contents and extract the names of all printers defined therein.  The
{\tt printcap} file is not universally used, but it can be found on
most Berkeley-based systems such as Suns running SunOS 4.  For each
printer found, you will be asked if you want to include it, its type, any
options, and a description.  This information is added rather crudely to
%%% @@@ did you fix this, i.e. use awk to print the info neatly?
the {\tt\dol NET0/PRDEVS.LIST} file.

If the {\tt printcap} file cannot be found, you will be asked how many
printers you want to define, and will be asked for the printer name, plus
the same information as outlined in the previous paragraph.

\medskip\newsubsubsection{Copy system files to the aips root}

There are currently 16
%%% @@@ count'em and check!!!  See INSTEP1 script, stage 7 for the list.
files that will be copied to the {\tt AIPS\char95 ROOT} area from
{\tt\dol SYSUNIX}.  If you have a {\tt 15JUL93} or {\tt 15JAN94} installation
and the {\tt INSTEP1} script detects this, only 10 of these will be copied
and the remaining 6 will remain untouched.  Be warned, however: the script
says:\medskip

\example{INSTEP1: Will NOT clobber your AIPSASSN.*, AIPSROOT.DEFINE, HOSTS.*,}
\example{INSTEP1: or LOGIN.* files (15JAN94 INSTEP1 clobbered HOSTS.LIST,
                  Sorry}
\example{INSTEP1: The others in \dol AIPS\char95 ROOT will have to be
                  updated.}\medskip

\noindent (``clobber'' here means overwrite) Most of these are Bourne
shell scripts; three 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 \dol AIPS\char95 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\dol AIPS\char95 ROOT}
area, you will be asked for each one, \eg:\medskip

\example{Warning!  Old AIPSPATH.SH found in AIPS\char95 ROOT}
\example{Some older versions of AIPS\char95 ROOT files may be}
\example{incompatible with this version of AIPS, especially}
\example{if they predate the 15APR92 release}\medskip
\example{Do you want to MOVE the old AIPSPATH.SH file to AIPSPATH.SH.OLD? (NO)}

\noindent The files copied are:\medskip

{\settabs 3 \columns \tt
\+ AIPSASSN.CSH         & HOSTS.SH               & START\char95 TVSERVERS \cr
\+ AIPSASSN.SH          & HOSTS.LIST             & TVALT \cr
\+ AIPSPATH.CSH         & LOGIN.CSH              & TVDEVS.SH \cr
\+ AIPSPATH.SH          & LOGIN.SH               & AIPS.BOOT \cr
\+ AIPSROOT.DEFINE      & START\char95 AIPS      & \cr
\+ HOSTS.CSH            & START\char95 TPSERVERS &  \cr
}\medskip

\noindent The format of {\tt HOSTS.LIST} was changed in {\tt 15JUL93}, so
if you have an earlier version, you need to make sure it uses the newer {\tt
HOSTS.CSH}, {\tt HOSTS.SH}, and {\tt TVDEVS.SH} scripts.  In order to
maintain compatibility between a {\tt 15OCT92} release and a newer one,
you should do the following:\medskip

\item{1.} {Move the two directories and make symlinks to {\tt\thisver}:
\medskip
\example{cd \dol AIPS\char95 ROOT/15OCT92/\dol ARCH/SYSTEM}
\example{mv \dol SITE \dol{SITE}.OLD}
\example{ln -s \dol AIPS\char95 ROOT/\thisver/\dol ARCH/SYSTEM/\dol SITE \dol SITE}
\example{cd \dol AIPS\char95 ROOT/15OCT92/SYSTEM}
\example{mv UNIX UNIX.OLD}
\example{ln -s \dol AIPS\char95 ROOT/\thisver/SYSTEM/UNIX UNIX}}
\medskip
\item{2.} {Rename the {\tt TEKSERVER} binary to {\tt TEKSRV}:\medskip
\example{cd \dol AIPS\char95 ROOT/15OCT92/\dol ARCH/LOAD}
\example{mv TEKSERVER.EXE TEKSRV.EXE}}
\medskip

%%% @@@ Dates above... may be ok

\medskip\newsubsubsection{Run AIPSROOT.DEFINE}

This shell script will set the value of the {\tt AIPS\char95 ROOT}
environment variable automatically in all of the shell scripts that
need it.  If you do not specify the directory name for {\tt
AIPS\char95 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{Create the AIPS command}

In versions of \AIPS\ prior to {\tt 15JAN94} you were advised to create a
file in {\tt /usr/local/bin}.  That method has now been superseded.  Now
the {\tt INSTEP1} script will automatically make a symbolic link in the
{\tt\dol SYSLOCAL} area called ``{\tt aips}'' that points at the version
of {\tt START\char95 AIPS} in {\tt\dol AIPS\char95 ROOT}.  It also makes
an additional one called ``{\tt AIPS}'' for those users who like to work
in upper case.  Thus, for users to avail of this scheme, they will have to
``source'' or ``dot'' the relevant {\tt LOGIN.*} file in their {\tt
.login} or {\tt .profile}.

For DEC/Ultrix and Convex systems, the above symbolic links are removed,
and the {\tt\dol AIPS\char95 \-ROOT/\-START\char95 \-AIPS} script is copied to
{\tt\dol SYSLOCAL/AIPS}, and converted to the relevant shell.  A symbolic
link {\tt aips} is then made to it.  This allows non-Ultrix and non-Convex
architectures to co-exist with these systems.

\medskip\newsubsubsection{Set AIPS Version Names}

The system as shipped can accommodate 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\dol 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.  Also see the above note for compatibility
between {\tt 15OCT92} and later releases.

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\dol DA00} now points to a directory {\tt\dol AIPS\char95
ROOT/DA00/\dol 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\dol AIPS\char95 ROOT/DA00} and {\tt\dol 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\dol 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\char95 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 rhesus}, for
example, the first two disks would be {\tt /DATA/RHESUS\char95 1} and {\tt
/DATA/RHESUS\char95 2}.  This will enable the \AIPS\ user to select disks
from different host machines at startup.  The criterion for the {\tt
da=FOOBAR} command line option to the {\tt aips} command to select disks
is simply that the string {\tt FOOBAR} be somewhere in the name.

For most installations, it will be easiest to make the data root area
something like {\tt\dol AIPS\char95 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 going to be in any way large (more than about 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 gone further than just using basic
automounter technology, and 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\char95 1 -rw,grpid,hard,intr gorilla:/gorilla/aips/GORILLA\char95 1}
\example{GORILLA\char95 2 -rw,grpid,hard,intr gorilla:/gorilla/aips/GORILLA\char95 2}
\example{GORILLA\char95 3 -rw,grpid,hard,intr gorilla:/gorilla\char95 2/GORILLA\char95 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\char95 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.  Unfortunately not all NFS servers support the {\tt
grpid} option.

Systems that NRAO has used this automounter scheme successfully with
include: Sun3, Sun4, Solaris, IBM RS/6000 (AIX 3.2; it did {\it not\/}
work for version 3.1) Convex, DecStation (Mips/Ultrix 4.0, 4.3, and
Alpha/OSF--1).  With a little effort, our Linux guru was also able to get
it to work.  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\char95 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\char95 ROOT} 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 will be
required for that.

Certain tasks (such as the {\tt TPMON} remote tape d\ae mons) require the
{\tt FITS} area to exist.  This is the default staging area for import and
export of FITS-format disk files to and from \ttaips.  If there already
exists a directory or symbolic link {\tt\dol AIPS\char95 ROOT/FITS}, or if
environment variable {\tt\dol FITS} is defined, then nothing is done.
Otherwise you are given the option to create the directory in the standard
area, or make it a symbolic link to another area.  Some sites may want to
have a large scratch area on another file-system for this purpose.

If required, {\tt INSTEP1} copies the {\tt DADEVS.LIST} and {\tt
NETSP} files from {\tt\dol SYSUNIX} to the {\tt\dol NET0}) area
%%% @@@ where is NET0 first defined?
(actually {\tt\dol AIPS\char95 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} script to inspect the two files mentioned in the last
paragraph.  If your {\tt\dol EDITOR} environment variable is defined, the
script will ask if you wish to edit them now.

The {\tt NETSP} file overrides some system parameters previously set via
the {\tt RUN SETPAR} program, \ie, the {\tt\dol 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 older 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}.  Since the {\tt 15JUL93}
release, this method has been replaced with 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} and {\tt PRDEVS.LIST} in the {\tt\dol NET0} area.
If it exists, and the current host has a tape drive or drives defined in
it, the file will not be updated or modified.  If it exists and there are
no entries in it for the current host, then you are given the option of
adding one or more.

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 8500}
\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 8500 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 no-rewind 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.

The {\tt ZMOUN2.C} routine in the architecture-specific Z routine area will
modify the actual device name used where multiple densities are supported.
This usually means 9-track tape drives or Exabyte 8500 devices.  If you
have such a device, you {\it must\/} enter it so that the density
modification code in the Z routine produces the correct name for different
densities.

Here is a brief summary of the form of device names for known systems, and
how the {\tt ZMOUN2} routine modifies the name:
\medskip
{\parindent 2cm
\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 add 8 or 16 to the number if higher density is
            indicated by the {\tt DENSITY} adverb; it is imperative that
            you enter the base number, otherwise the density algorithm
            will get confused (though not half as confused as you).
            For Solaris 2 (SunOS 5), see SOL below.
\item{SUN3} See SUN4 above.
\item{SOL}  {\tt /dev/rmt/<x><d>n}, where {\tt <x>} is $0, 1, 2, \dots$,
            and {\tt <d>} is the density (l, m, h for low, medium, or
            high).  \AIPS\ will modify {\tt <d>} on the fly depending on
            the density desired, and the density letter {\it must\/}
            immediately follow the tape number {\tt <x>}.
\item{IBM}  {\tt /dev/rmt<x>} where {\tt <x>} is $0, 1, 2, \dots$ for
            the tape drive number.  Do {\it not\/} use a full name, \eg, {\tt
            /dev/rmt0.1} as \AIPS\ will add the correct qualifier.  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.  Be sure to set {\tt <d>}
            to {\tt l} initially.
\item{ALPHA} Identical to DEC.
\item{HP}   {\tt /dev/rmt/<x><d>n} where {\tt <x>} is $0, 1, 2, \dots$,
            and {\tt <d>} is the density (l, m, h as for DEC).  The n is
            for no-rewind.  \AIPS\ will modify the {\tt <d>} according to
            the density desired on the fly.  As with SOL, the density
            indicator must immediately follow the tape number.
\item{LINUX} {\tt /dev/nrst<x>}, similar to Sun, for SCSI tape drives, or
            {\tt /dev/nrmt<x>} for non-SCSI drives.  There is some local
            tape drive support in {\tt\thisver}\ on Linux; %%% @@@ still?
            however, most PC tapes are quarter-inch cartridges which
            cannot backspace over files/records and are thus unusable from
            within \AIPS.
\item{SGI} Identical to HP.
}
\medskip

\noindent The relevant code containing the logic for handling tape drives
is found in {\tt ZMOUN2.C} and {\tt ZTAP2.C} in the Z-routine areas for
the different architectures.  If you modify this code for your system,
please let us have a copy of the modified (working!) code along with a
thorough description of your system (hardware, operating system, any
relevant patches), tape controllers, tape drivers and the tape drive
itself.  Also remember that the rules for tape names and behavior (\eg,
reporting status of drive, error codes) are probably the least
standardized thing in the Unix environment, and what works for your drive
may not work for someone else's.  There isn't even anything useful in the
Posix standards about mag tapes (please contact the author if you know this
is not so!).

\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.  This information is requested by {\tt INSTEP1} even if you
are doing a binary installation.  Its first guess is obtained from the
{\tt \dol SYSLOCAL} file {\tt CCOPTS.SH} and the output of the {\tt\dol
SYSUNIX} file {\tt FDEFAULT.SH}, which come pre-configured for several
well-known \AIPS\ architectures.  You will be asked to confirm if this
guess is correct or not.  For Sun3 and Sun4 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.  This
is not the same as the (Kernighan and Ritchie style) default C compiler
available in SunOS 4.1.

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
probably in {\tt /opt/SUNWspro/bin}.

If you change what the default Fortran or C compiler is, the script
attempts to update this information in the relevant files.  For Fortran,
the only one it can update is {\tt \dol SYSLOCAL/LDOPTS.SH}, but you will
need to modify {\tt \dol SYSUNIX/FDEFAULT.SH} by hand (if {\tt\dol EDITOR}
is defined, it offers to start the edit for you now).  For C, the file
{\tt\dol SYSLOCAL/CCOPTS.SH} is automatically modified.

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 five
%%% @@@ make sure it still is true, NEWEST, PRINTENV, PP.EXE, F2PS, F2TEXT
utility programs that need to be compiled for the source-only
installations, 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;
\item{3)} {\tt PP.EXE}, the Fortran pre-processor;
\item{4)} {\tt F2PS}, the Fortran-to-PostScript filter; and
\item{5)} {\tt F2TEXT}, the Fortran-to-text filter.
\medskip

\noindent For binary installations, pre-built versions of these are copied
from the {\tt \dol AIPS\char95 ROOT/BIN/\dol ARCH} area, and no
re-compilation should be necessary.  For source-only installations, the
{\tt INSTEP1} script will attempt to build the programs for you.

The first of these is only needed on systems that do not have {\tt
printenv}, or where the system-supplied {\tt printenv} cannot handle the
large environment needed to rebuild \AIPS.  If the script finds {\tt
printenv} in the path anywhere, it will simply make a symbolic link {\tt
PRINTENV} in the {\tt\dol SYSLOCAL} area to it.  Otherwise, it will make a
symbolic link to {\tt\dol SYSUNIX/PRINTENV.C} in {\tt\dol
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\dol SYSUNIX/NEWEST.C} which again is copied (for
all architectures this time) to {\tt\dol SYSLOCAL} as {\tt newest.c} and
compiled with the {\tt -o} qualifier to make {\tt NEWEST}.

A symbolic link is made to the preprocessor source {\tt\dol SYSUNIX/PP.FOR}
via {\tt\dol SYSLOCAL/pp.f} and a Z-routine to translate environment
variables {\tt\thisver/APL/DEV/UNIX/ZTRLOG.C} is also symlink-ed as
{\tt\dol SYSLOCAL/ztrlog.c}.  The latter is compiled with the {\tt -c}
qualifier and a {\tt -I} reference to the \AIPS\ include area 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.  For Linux, a three-step
process is used: (1) run {\tt f2c} on the Fortran source, (2) change the
references to {\tt CALL EXIT} in the resultant C code, and (3) compile
the edited C code with {\tt gcc}.  Also, on HP systems, the {\tt CALL
EXIT} is replaced with {\tt STOP}.

Finally, the {\tt F2PS} and {\tt F2TEXT} filters (new to the {\tt 15JUL94}
%%% @@@ update as needed.  Is this the right place for it???
release), are compiled.  These are relatively simple programs that take
the Fortran-formatted output of {\tt AIPS} and other tasks, and format it
for either PostScript or plain text printers.  {\tt F2PS} will use the
value of ``number of lines per printed page'', item 34 in the {\tt SETPAR}
menu, to decide what format and orientation is used.  The table below
summarizes the command line arguments and their effects on {\tt F2PS}:
\medskip

{\settabs 7 \columns \hrule \vskip 2pt \hrule
\+& Argument & Lines & Argument & Lines & Orientation & Font size \cr
\hrule \vskip 3pt
\+& -S &  97  &   -S/-A4  & 95   &    Portrait   &  6.8  \cr
\+& -R &  61  &   -R/-A4  & 58   &    Landscape  &  8.0  \cr
\+& -M &  54  &   -M/-A4  & 52   &    Landscape  &  9.0  \cr
\+& -L &  52  &   -L/-A4  & 47   &    Landscape  &  9.25 \cr
\vskip 2pt \hrule
}\medskip

The arguments are passed to the program via the {\tt ZLPCL2} shell script
in {\tt\dol SYSUNIX}.  As shipped, this script causes the program to
assume ``A'' size paper ($ 8.5 \times 11 $ inches); if you wish to use A4
size instead, edit the shell script and add the {\tt -A4} argument in the
appropriate place.

Both {\tt F2PS} and {\tt F2TEXT} will accept Fortran formatted output,
\ie, column 1 of the files they process is assumed to be the special
formatting column as specified in the Fortran 77 standard.  The programs
will interpret this column, and act accordingly (new page for form feed,
skip 1 or 2 lines as appropriate).  {\tt F2TEXT} will take an extra
optional argument, {\tt -e}, if the last page of a print job is to end
with a form feed; this may not be necessary with most printers, and the
default is no ending form feed.  Again, change this as needed in {\tt
ZLPCL2}.

If any of the above task builds fail, you will have to investigate the
problem, correct it if possible and compile the program by hand.

\medskip\newsubsubsection{Shared and Debug Libraries}

You are given the option to choose whether you want to build ``shared''
or dynamic \AIPS\ libraries on some systems.  In addition, on all
systems you are also asked 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 they are
not totally debugged on HP.

The binary tapes are shipped with non-debug, non-shared \AIPS\ libraries,
and the rest of this section is not relevant for such installations.

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 decrease by
about 50 megabytes.  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 fewer than about 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 is recommended and you
may want to stick with the non-shared libraries if you have a HP system.
As the NRAO \AIPS\ group still does not have access to an in-house HP--UX
system, our progress in debugging this problem has been slow.

Even if you ask for the shared libraries, the regular non-shared versions
have to be built anyway.  Thus, if you chose share-able libraries, all it
really takes to convert a given task to use the static libraries is a
relink.  The mechanism for deciding whether or not to link against shared
libraries is the presence or absence of the file {\tt \dol
SYSLOCAL/USESHARED} (the contents or size don't matter).  Also, there is a
list {\tt\dol SYSLOCAL/NOSHARE.LIS} containing simple (basenamed)
filenames of programs that must {\it not\/} be linked against the shared
libraries.  This file exists for {\tt SUN4} installations (most of the
entries in it probably don't need to be there) but not for other
architectures.  You can always add to this list if you find a task that
does not behave well with shared libraries.

Previously, linking against shared libraries had sometimes produced
warnings about unresolved references.  On Solaris 2.x, this is a fatal
error and the resulting task simply will not run.  The \AIPS\ group has
tried to remove all such occurrences of these references, so you should
not see this message anymore.  If you do, it means something is not
right.

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
\dol SYSLOCAL/DOTWOLIB}, which was called {\tt DOTWOBIN} in older versions.
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 pre-processed source code around in the {\tt\dol 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 occurring.
\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
Versions of \AIPS\ {\tt 15JUL93} or earlier had a different format for
this file, but the newer format {\it should\/} be backwards compatible, as
long as your older versions of \AIPS\ use the newer shell scripts in the
{\tt\dol AIPS\char95 ROOT} area.  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}, {\tt 15JAN94},
or {\tt\thisver}.

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.

The comments for fields 3 and 4 are old.  You can in fact mix different
architectures in the same {\tt\dol AIPS\char95 ROOT} area, but you have to
assign different site names.  As already mentioned, at
NRAO/Char\-lottes\-ville the {\tt HOSTS.LIST} file has two sites: {\tt
NRAOCV} for the Suns and IBM RS/6000 systems, and {\tt VCOARN} (NRAOCV
spelt backwards) for systems with reversed byte order: Dec/Ultrix,
Dec/Alpha, and Intel/Linux.

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.  There is a limit of one instance of a TV server ({\tt XAS}) per
\AIPS\ host or TV host.  Conversely, given enough hosts, there is no such
limit on the number of TV servers you can display on a single X11 screen;
you just need to have each server come from a different host.

Using the {\tt tv=} command line option of the \ttaips\ command, you can
in fact redirect (via X11) 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.

You can also choose, using the {\tt tv=} command line option, a separate
TV host other than the system on which you are running \ttaips.  In
other words, the \ttaips\ host, TV host, and TV display can be three
separate systems.  However, the TV host and \ttaips\ host have to be
regular \AIPS\ systems listed in {\tt HOSTS.LIST}.

\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, Dec-Windows, Motif, fvwm and twm/tvtwm).

If you answer {\tt YES}, the script will unpack the archive in the
directory {\tt\thisver/Y/SER\-VERS/XAS}.  For Linux, the unpacking is
performed via the {\tt UNSHR} program provided in the {\tt YSERV} area, as
the bash shell gets very confused with the characters in the {\tt
Makefile} in the {\tt XAS.SHR} archive.  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.  Also it uses some predefined values for some systems.
Here is a summary of the ``logic'' behind this:\medskip

{\ndot For Linux, use {\tt /usr/X386/lib} and {\tt /usr/include/X11}.}
{\ndot If {\tt\dol OPENWINHOME} is defined, use its include and lib areas.}
{\ndot For Alpha systems, use {\tt /usr/include/X11} and {\tt
        /usr/include/lib}.}
{\ndot If {\tt /usr/openwin} exists, treat it as for {\tt\dol OPENWINHOME}
        above.}
{\ndot Check {\tt /opt/local/lib} and {\tt /opt/local/include}}
{\ndot Check {\tt /usr/local/lib} and {\tt /usr/local/include}}
{\ndot Check {\tt /usr/lib} and {\tt /usr/include}}
{\ndot Check {\tt /usr/lib/X11R5} and {\tt /usr/include/X11R5} (valid
        for some HP systems)}
{\ndot Check {\tt /local/X11R5} (NRAO-specific area)\medskip}

\medskip\noindent 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 in the Makefile by hand later.

If the script 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 figure out if this is
possible by running the standard X11 program {\tt xdpyinfo} and searching
for the string {\tt MIT-SHM} in its output.  It also searches for the file
{\tt X11/extensions/XShm.h} in the include area previously specified.  If
and only if: (a) it finds this and (b) the {\tt xdpyinfo} check worked, it
will assume that XAS should be made with the shared memory code enabled.
You will be asked for confirmation before the ``make'' starts.  If the
wrong choice is made, and shared memory is enabled during the make, most
likely the compile or link will fail.  To change the option permanently in
{\tt XAS}, edit the {\tt Makefile} in the {\tt\dol YSERV/XAS/} directory
to change {\tt SHMOPT} to blank for no shared memory, or {\tt -DUSE\char95
SHM} otherwise, and then type {\tt make} to remake it (Warning: {\tt\dol
LOAD} must be defined before you do this, and any {\tt *.o} files should
be removed first; there is no ``clean'' target in the Makefile).

If you have a shared-memory-enabled version of {\tt XAS}, it will
automatically detect if the server and display hosts are different; in
this case it will not even attempt to use shared memory.  However, if
you want to inhibit its use, see the section below on X resources; the
{\tt AIPStv*useSharedMemory} resource can be turned on or off prior to
starting the TV server.

On Suns, you will need to have the System V IPC options configured in
your kernel.  Check Sun's System and Network Administration Manual,
chapter 9, for the details.  In particular, you will want to have this
in the configuration file:\medskip

\example{options IPCSHMEM\ \ \ \ \ \ \ \#\ \ System V IPC shared-memory
        facility}\medskip

\noindent If it is not (or is commented out), then you have to rebuild
the kernel --- or have your sysadmin do it for you --- to make use of
the X11 shared memory extension.

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.
For Solaris, it adds {\tt -lsocket} to the {\tt STDLIBS} variable.
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/\dol ARCH/INSTALL} and makes symbolic links to the files {\tt
INSTEP2}, {\tt INSTEP3}, and {\tt INSTEP3} in {\tt\dol INSUNIX}.
Obviously this is only done for source-only installations; there is
normally no need to run {\tt INSTEP2} or subsequent steps for binary
installations.

You will be presented with a set of instructions for editing and checking
various files at the end of {\tt INSTEP1}.  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}

Historically, there was often a need for each installation of \AIPS\ to
perform some local code development; Unix was not very widespread and
there were many different architectures and systems to choose from.
Since these ``bleeding edge'' days, there has been somewhat of a
shakedown in the Unix software market, and standards bodies have rushed
in trying to make things easier (except for mag-tapes; see author's
complaint above!).  Also, NRAO now has a moderately diverse selection of
Unix based systems in-house that are accessible to the \AIPS\ group.

If you are porting \AIPS\ to a previously untried architecture, you
will most likely have to create several new areas.  The best way is to
edit {\tt\dol SYSAIPS/AREAS.DAT} and insert new area definitions.
Typically, you will want one for Z routines somewhere under {\tt
APL/DEV}, and a system area analogous to {\tt \dol SYSSUN}.  This is the bare
minimum, as you may also need a Q-routine area and an include area.
Once you have modified this file, you should run {\tt \dol SYSUNIX/AREAS}
to regenerate {\tt AREAS.CSH} and {\tt AREAS.SH} in the same directory.

You will want to define a new architecture in the various shell scripts
that need it: {\tt START\char95 AIPS}, {\tt FDEFAULT.SH}, {\tt TVALT}, and
others.  Just look to see where the {\tt ARCH} variable is used/checked.
Then you need to create a new {\tt LIBR.DAT} file.  The easiest way to do
this is to take the closest architecture, e.g. for a hypothetical port to
a Berkeley-like system, take the {\tt SUN4} one and change things like
{\tt\dol APLSUN} to whatever you called the new architecture-specific
area.  For additional information about {\tt LIBR.DAT}, see section 2.4.5.
%%% @@@ CHECK that this section number is right!

The Z-routines are stored under {\tt\thisver/APL/DEV} (\ie, {\tt
\dol 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 \dol 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}, Intel/PC
({\tt LINUX}), Masscomp ({\tt MASC}), Silicon Graphics ({\tt SGI}), and
SunOS 5/Solaris 2 ({\tt SOL}).  Under the {\tt APL/DEV/UNIX/BERK} area,
there are directories for Alliant ({\tt ALLN}), Convex ({\tt CVEX}), Dec
Alpha/OSF--1 ({\tt DEC}, IBM RS/6000 ({\tt IBM}), Sun ({\tt SUN}), and Vax
({\tt VAX} for BSD Unix).  There are subdirectories for {\tt NRAO1} and
{\tt VLAC1} in the {\tt CVEX} area (for specifying that we had IEEE
hardware).  However, the IBM 3090 area is a subdirectory of the IBM
RS/6000 area.  Similarly, in the Dec-Alpha (OSF/1) area, there is an {\tt
ULTRIX} subdirectory for the few routines that are different on Ultrix
(4.3).
%%% @@@ make sure above is still right.

To maintain the hierarchical structure, you should position any new
Z-routine directory such that it accurately reflects your system.  for
example, {\tt \thisver/APL/DEV/UNIX/BELL/SCO} might be the choice for a
hypothetical port to the Santa Cruz Operation's version of Unix for
PC's.  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 obsolete Sunview only) and XVSS
(Sun's OpenWindows only).  The latter two are rarely used anymore.
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

In the exceedingly unlikely case that you have no TV (this now means
that you have no access to X11, and don't have any older style hardware
image display device like the $I^2S$), modify the {\tt LIBR.DAT} to use
{\tt\thisver/Y/DEV/STUB} for no TV support.  In the even more unlikely
case that you have an image display device that does not support X
windows and for which there is no existing support in \AIPS, you will
need to create a new Y-routine directory under {\tt Y/DEV} somewhere.
You can safely 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\/}, and try not to use operating system specific code.  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
minimize 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 has not had any active FPS array
processors used for \AIPS\ in quite some time.  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} (empty)}
{\ndot {\tt HP} (empty)}
{\ndot {\tt IBM} RS/6000 (AIX) optimized PSAP routines; there is also
        a subdirectory for mainframe-specific routines ({\tt IBM/3090/}).}
{\ndot {\tt SGI} (empty)}
{\ndot {\tt SOL} (empty)}
{\ndot {\tt SUN} Sun 3/4 optimized PSAP routines}
{\ndot {\tt VMS} VAX/VMS specific PSAP routines\medskip}\medskip

\noindent
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 new directory in the above scheme.
\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\dol SYSAIPS/AREAS.DAT} file by
the shell script {\tt\dol SYSUNIX/AREAS}.   Note that in the generic {\tt
\dol 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.  If you have already put them in {\tt AREAS.DAT} and
regenerated the shell scripts, there is no need for this and you can
un-comment this from the {\tt\dol SYSLOCAL} versions of the {\tt CDVER}
files.

Some UNIX systems may not be able to handle the size of an environment
resulting from so many definitions, as mentioned earlier.  The limiting
factor is the value of {\tt NCARGS} as defined in the file {\tt
/usr/include/\-sys/\-param.h} on most systems.  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\char95
directory\char95 path\char95 name/*}.  {\tt NCARGS} varies somewhat but on
most modern systems it is usually in excess of 24000.  Convex-OS (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 may be able to rebuild or reconfigure your
system kernel with a sufficiently large value for {\tt NCARGS} (or have
your sysadmin do this).  However, removing ``logicals'' for areas you may
have deleted or don't need, and/or making sure the {\tt\dol AIPS\char95
ROOT} is a short name, are probably simpler solutions.
\medskip

\newsubsubsection{Login Procedures}

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{.~\dol 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\dol SYSUNIX} version of the file (and telling you that {\tt
AIPS\char95 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.  This is a known
problem on IBM RS/6000 AIX systems and there is no quick solution.

In addition, watch for the protection mask on the {\tt /tmp} area; on
some systems the ``t'' bit 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\dol SYSLOCAL} and {\tt\dol 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\dol SYSLOCAL} and {\tt\dol SYSUNIX}.  These are
inserted at the beginning of the variable, and all the other elements in
{\tt PATH} that don't match these are then appended.  \AIPS\ definitions
(environment variables) can be reset to whichever version you want
through typing {\tt\dol CDOLD}, {\tt\dol CDNEW} and {\tt\dol CDTST} if you have
multiple versions.  These strange creatures are the lowest common
denominator solutions for all flavors of UNIX and shells.  They are
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\dol CD...} in the {\tt .login} or
{\tt .profile} of any accounts that will be doing significant
programming in \AIPS.  However, this is only really needed for
installation, programming and moving quickly around the directory tree.
You will need to at least call {\tt\dol CDOLD} or {\tt\dol CDNEW} or
{\tt\dol CDTST} interactively before starting {\tt INSTEP2} as it will fail
otherwise.
\medskip

\newsubsubsection{Object Libraries and Source Code Search Paths}

The \aips\ system has 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\dol 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
will have been copied by {\tt INSTEP1} to the {\tt\dol SYSLOCAL} area.

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\dol 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\dol 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
(actually Unix ``archive'' libraries, \ie, {\tt \dol 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{\dol LIBR/APLSUN/SUBLIB:0:\dol APLSUN \hfill\rm (Sun specific)}
\example{\dol LIBR/APLSUN/SUBLIB:0:\dol APLBERK \hfill\rm (Berkeley (BSD) Unix)}
\example{\dol LIBR/APLSUN/SUBLIB:0:\dol APLUNIX \hfill\rm (Generic Unix)}
\example{\dol LIBR/APLSUN/SUBLIB:0:\dol 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
(quite rare now, with workstations taking over from the IIS, IVAS,
DeAnza and other devices) and/or multiple sets of Q routines (almost
unheard of anymore, probably last used on a VMS 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, \eg, {\tt
\dol LIBR/APLSUB/SUBLIB} to {\tt \dol LIBR/APLSUB.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
\dol APLGEN/ZDATE} will call the {\tt SEARCH} shell script which will, on
a Sun4 system, check in:\medskip

\example{APL/DEV/UNIX/BERK/SUN/ZDATE.*}
\example{APL/DEV/UNIX/BERK/ZDATE.*}
\example{APL/DEV/UNIX/ZDATE.*}
\example{APL/DEV/ZDATE.*}
\medskip

\noindent This list is derived from the {\tt SEARCH<n>.DAT} files in
{\tt\dol SYSLOCAL} ({\tt <n>} here corresponds to {\tt <loadnumber>} and is
usually zero).  The net effect 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 \dol LIBR} area itself contains only subdirectories (\eg, {\tt
\dol 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
are in, \eg, {\tt \dol 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\char95 LIBRARY\char95 PATH} variable.

For most installations, the {\tt <loadnumber>} will be zero in all
cases.  In the unlikely event that 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{\dol LIBR/YSUB/SUBLIB:0:\dol YSUB}
\example{ }
\example{Non-standard routines}
\example{ }
\example{\dol LIBR/YNOT/SUBLIB:0:\dol YNOT}
\example{ }
\example{Standard Screen Server TV Y-routines}
\example{ }
\example{\dol LIBR/YSS/SUBLIB:0:\dol YSS}
\example{\dol LIBR/YSS/SUBLIB:0:\dol YGEN}
\example{ }
\example{IIS Model 70 Y-routines}
\example{ }
\example{\dol LIBR/YM70/SUBLIB:2:\dol YM70}
\example{\dol LIBR/YM70/SUBLIB:2:\dol YIIS}
\example{\dol LIBR/YM70/SUBLIB:2:\dol YGEN}
\example{ }
\example{IIS Model IVAS Y-routines}
\example{ }
\example{\dol LIBR/YIVAS/SUBLIB:4:\dol YIVAS}
\example{\dol LIBR/YIVAS/SUBLIB:4:\dol 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\dol LIBR/YM70/SUBLIB} and
{\tt\dol 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\dol LOAD}, that for the IIS Model 70 will
go in {\tt\dol LOAD2} (same as {\tt\dol LOAD/ALT2/}), and those for the IVAS
will go in {\tt\dol LOAD4} (same as {\tt\dol LOAD/ALT4/}).  This obviously has
disk space consequences.

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\dol 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\dol 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&\dol LIBR/APLCVEX/SUBLIB\quad&\dol APLNRAO1,\dol APLCVEX,\dol APLBERK,\dol APLUNIX,\dol APLGEN\cr

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

\noindent There is nothing special about the {\tt\dol 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.  If it does, it may mean that {\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

\line{\ \ {\eightpoint \tt
        AIPS stand alone program source code search paths and link
        libraries:}\hfill}
\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\dol 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 \dol 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
\+& \dol AIPGUNIX  & \dol AIPNOT      & \dol AIPPGM      & \dol APGNOT\cr
\+& \dol APGOOP    & \dol APGUNIX     & \dol APLPGM      & \dol QPGM\cr
\+& \dol QPGNOT    & \dol QPGOOP      & \dol QYPGM       & \dol QYPGNOT\cr
\+& \dol YPGM      & \dol YPGNOT      & \dol 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\dol LOAD}.

If you have hardwired TV's and/or a real AP, you will 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 the Y and/or Q
routines for each alternative TV and/or AP.  The binaries for these
programs are stored in {\tt\dol LOAD<n>} where {\tt <n>} is the {\tt
<loadnumber>}.  This environment variable will translate to {\tt
\dol LOAD/ALT<n>}.  {\it Only \/{\tt\dol LOAD1} through \/{\tt\dol LOAD3} are
defined by default on most configurations so you may have to add extra
definitions to \/{\tt \dol AIPS\char95 ROOT/AIPSASSN.*} or \/{\tt
\dol SYSLOCAL/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\dol APLPGM} and {\tt\dol 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\dol QPGM},{\tt\dol QPGNOT}, and
{\tt\dol QPGOOP}, {\tt\dol YPGM} and {\tt\dol YPGNOT}, and {\tt\dol QYPGM} and
{\tt\dol 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\dol LOAD})}
{\ndot {\it pseudo\/} AP with TV server ({\tt \dol LOAD1})}
{\ndot {\it real} AP with IVAS TV ({\tt\dol LOAD2}), and}
{\ndot {\it pseudo\/} AP with IVAS TV ({\tt\dol LOAD3})\medskip}
\medskip

\noindent The programs that depend on Q-routines will 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 types
with the TV {\it device 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\dol 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\dol LOAD},
{\tt\dol LOAD2} and {\tt\dol 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 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\dol 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=\dol 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 PAPC.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.  If your
system has more than 128 megabytes of main memory, you should consider
editing this file and increasing the {\tt PKPWD2} parameter so that the
total AP size is 17 megabytes; this would enable a complete 2k square
image to fit in the AP at one time with a little breathing room.

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

{\tt\dol 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
found this to be unnecessary, as both the {\tt\dol INCSOL} and {\tt
\dol INCHP} areas are empty, and we never created areas for Dec/Alpha or
Linux).  System specific include files are mostly those used in the
pseudo array processor library.  Check for a subdirectory in the
{\tt\dol 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
PAPC.INC}; this will automatically set the default number you see for
the second AP memory in the {\tt RUN SETPAR} menu (item 29).  Older
versions of \AIPS\ had this set in {\tt DAPC.INC}.  This is truly an
upper limit to the size of AP that the programs will use, though if you
use {\tt SETPAR} to set a value less than what is set in {\tt DAPC.INC},
the programs will honor the smaller value.

The total number of kilowords in the regular AP is always 64 and is set
by {\tt PKPWRD}.  The ``second'' AP array size is set by {\tt PKPWD2},
but in the {\tt PAPC.INC} file you simply set the variable {\tt APSIZE}.
As shipped the default is 1310720 words, corresponding to 5 megabytes.
You will see that this causes the 2nd AP size in {\tt SETPAR} to come up
as 1216.
\medskip

\newsubsubsection{Compiler and Loader Options}

Each Unix system and compiler combination 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 to {\tt\dol 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\dol SYSUNIX}.  The comments in these files make it relatively easy to
edit and change them as appropriate.  If you change the {\tt FDEFAULT.SH}
or {\tt OPTIMIZE.LIS} files in {\tt\dol SYSUNIX}, please keep backup
copies of the originals, \eg, {\tt FDEFAULT.SH.NRAO}.

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
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\dol 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.  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 should be compiled with what
levels of optimization and debug settings.  There are default values in
here too.

It is desirable to throw whatever optimization your system allows at the
Q routines.  The most significant gains in performance will result from
optimizing the contents of {\tt \dol 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.  Some compilers, \eg, IBM's, come with
highly optimizing preprocessors that are enabled with a command line
switch.  In the case of IBM, the {\tt FDEFAULT.SH} already has this
information coded in the optimization definitions. \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 functionally equivalent
to the Berkeley {\tt printenv} for systems that either don't have it or
where the environment is too small.  {\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: \medskip

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

\noindent If your system's version of {\tt printenv} is either
inadequate or just not there, then do this:\medskip

\example{\% ln -s \dol 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) you can delete the links {\tt printenv.*} and {\tt
newest.*}.

There are two additional programs --- {\tt F2PS} and {\tt F2TEXT} --- that
need to be built here, but {\tt INSTEP1} should have been able to build
these.  They are not needed for the compile or link stages of the
installation; only for use by \AIPS\ itself.  They have already been
described in the previous sections.

\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\bul locating {\tt INCLUDE} statements, then searching for
        and inserting the text from the specified external file;
\item\bul 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\bul substituting {\tt REAL} for {\tt HOLLERITH} type
        declarations, which are used for storing 4 (always) hollerith
        characters per element (regardless of host word size).
\item\bul 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 \dol SYSLOCAL}
\example{\% ln -s \dol SYSUNIX/PP.FOR pp.f}
\example{\% ln -s \dol 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 -e 's/ztrlog\char95 /ztrlog/g' >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\dol SYSLOCAL}.

Additionally, on HP systems, you need to substitute a {\tt STOP}
statement in place of the {\tt CALL EXIT} in {\tt pp.f}:\medskip

\example{\% mv pp.f pp.tmp}
\example{\% cat pp.tmp | sed -e 's/CALL EXIT.*\dol/STOP/g' >pp.f}
\example{\% rm pp.tmp}

Next, if your system is {\it not\/} Linux, 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.

For Linux, a more complex workaround is needed.  {\tt INSTEP1} should
have done this for you, but in case it failed, here are the steps
needed.  First, compile {\tt ztrlog.c} as above (use {\tt gcc}).  Then:
\medskip

\example{\% f2c pp.f}
\example{\% mv pp.c pp.tmp}
\example{\% cat pp.tmp | sed -e 's/exit\char95 (/exit(/g' -e '/int exit/d'
         >pp.c}
\example{\% rm -f pp.tmp}
\example{\% f77 -O -o PP.EXE pp.c ztrlog.o}\medskip

\noindent This little dance separates the Fortran-to-C conversion from
the C compilation of the result, and replaces the external reference to
{\tt exit\char95 } with the normal C {\tt exit} call.

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 is usually a simple
copy to files with lowercase file ``type'', e.g. {\tt FOO.c}.  In the
case of Fortran modules, {\tt PP} sets {\tt\dol INCS} to whatever is in the
variable {\tt\dol 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.

\medskip

\newsubsection{Installation Step 2}

\newsubsubsection{Running INSTEP2}

For binary installations, you do {|it not\/} need to run the {\tt INSTEP2}
shells script.  For source installations, change directory to
{\tt\thisver/\dol 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\dol 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\dol
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{\% \dol 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\dol CDNEW} or
{\tt\dol CDOLD} here.

As this step can take a long time, you may want to shed it as a
background task:\medskip

\example{\dol\ (INSTEP2 >/dev/null 2>INSTEP2.ERRS \&)}\medskip

\noindent (the above assumes a bourne, korn, or bash shell, not a c or
tcsh shell).  This will run the process as a grandchild, throw away the
output (which is sent via ``tee'' to {\tt INSTEP2.LOG} anyway) and
captures any output to {\tt stderr} in another file.  You may see some
messages in the error file, \eg, {\tt tsort: cycle in data} or messages
about remaking {\tt SEARCH0.DAT}.  These are harmless.  You can monitor
progress of this process by:\medskip

\example{\$ tail -f INSTEP2.LOG}\medskip

\noindent {\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.
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/580 or a HP 9000/735, it
will only be about two hours.

One thing to watch for is that if all of the {\tt\dol 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\dol 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}).

For new ports, 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).  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 \dol APLNRAO1} or {\tt \dol APLVLAC1} version of
{\tt ZDCHI2} instead of the generic {\tt\dol APLCVEX} version (did you
remember to change {\tt LIBR.DAT}?).

%%% @@@ 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\dol 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 \dol APLGEN} will
ultimately produce the file {\tt APLGEN.LIS} containing a list of all
the subroutine source code found in the directory {\tt\dol APLGEN} and
below that is relevant to the host implementation.  The path names
selected are determined by the directory search paths defined in
{\tt\dol SYSLOCAL/LIBR.DAT}.

The ``at'' files are then used by the procedure {\tt\dol SYSUNIX/COMRPL}
to drive the mass compilation phase.  As each subroutine is compiled,
the resulting object module is staged to one or more {\tt\dol LIBR}
subdirectories, again based on {\tt LIBR.DAT}.  For example, object
modules generated from {\tt\dol APLGEN/}$\dots$\ subroutine source code
is staged to the proper {\tt\dol LIBR} subdirectory defined for such
modules.  After all subroutines are complied for, say {\tt\dol AIPSUB},
the procedure {\tt\dol 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\dol LIBR/AIPSUB}.  On Suns where you
have chosen to use shared libraries (\ie, created an empty file
{\tt\dol SYSLOCAL/USESHARED}), the {\tt\dol 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\dol AIPS\char95 VERSION/\dol ARCH/LIBR\-DBG} that contains a parallel set of
directories to the {\tt\dol 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\dol 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 DOTWOLIB} in the {\tt\dol SYSLOCAL}
area, and that it is only currently supported on Suns (including Solaris).
Currently, {\tt INSTEP2} will {\it not\/} make the debug versions of the
libraries; it just leaves the object modules in the staging areas.

{\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.
However, it waits until it has finished processing the particular ``at''
file before quitting, and then complains.  This behaviour is different
than in versions of \AIPS\ before {\tt 15JAN94}.

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\dol LIBR/AIPSUB/SUBLIB}).
For Suns and HPs, the shared libraries are located directly in the
{\tt\dol 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\dol 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 \dol LIBR} (and
possibly {\tt \dol LIBRDBG}) areas.  Object library updating is only done
either manually or by the procedure {\tt LIBR}news/ (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\dol SYSLOCAL/LIBR.DAT}.  One of the 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.

The remainder of this subsection will cover certain aspects of the
\AIPS\ installation that you may have to deal with.  These can usually
be done in parallel with {\tt INSTEP2} and {\tt INSTEP3}.\medskip

\newsubsubsection{Device Names (Logicals)}

The files {\tt AIPSASSN.CSH} and {\tt AIPSASSN.SH} are used to define
some \AIPS\ system values 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.  Since the {\tt 15JUL93} release, the tape drives are
defined in the {\tt TPDEVS.LIST} file and there will probably be no need
to edit 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.  But in a vanilla installation, you probably won't even have to
look at them.

If for any reason you need to modify these files, look at the section
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

\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.  Also be sure that you make equivalent changes in
both files, not just one.

\medskip\newsubsubsection{Data Areas}

There must be at least one \AIPS\ user data area, or \AIPS\ and its
support tasks simply will not work.  Since the {\tt 15APR92} release,
these areas are defined at \AIPS\ startup on the fly, depending on the
contents of {\tt \dol 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.  Also the file {\tt\dol NET0/NETSP} sets {\tt TIMDEST}
(expiry time) limits and user reservation numbers for the same disks.

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\dol AIPS\char95 ROOT/DA00/\dol HOST} for each host.

The {\tt DADEVS.SH} shell script is called by both {\tt START\char95 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 \dol AIPS\char95 ROOT/DATA/FOOBAR\char95 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\dol 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, such as speed of startup where the {\tt \dol NET0/DADEVS.LIST} has
many disks and the {\tt .dadevs} file may only have a few.

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 \dol AIPS\char95 ROOT/DA00/\dol 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\dol AIPS\char95 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?  yep (for 15jul94)

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
\dol DATA\char95 ROOT/\dol HOST\char95 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\dol DATA\char95 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.  Be warned, however: on some automounter versions, the
auto dismounting can in fact cause long-running AIPS jobs to crash.  The
reason is that the \AIPS\ process may not have an open file on a given
data disk, and also will not have any of the data disks in the {\tt
PATH}.  Hence the automounter will dismount it.  In principle, when an
open is attempted on a file, the automounter should intervene and mount
the directory, but at least one site has reported that (for Solaris)
this does not always happen and a ``file not found'' message is issued.
Running the task again invariably gets things working again.

The {\tt da=} option to the {\tt START\char95 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\char95 1}
\example{\ \ \ Disk 2 is /DATA/BABOON\char95 1}
\example{\ \ \ Disk 3 is /DATA/BABOON\char95 2}
\example{\ \ \ Disk 4 is /DATA/LEMUR\char95 1}
\example{\ \ \ Disk 5 is /DATA/LEMUR\char95 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\char95 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\char95 1} disk.

When running \AIPS, users can set the adverb {\tt BADDISK} to prevent
scratch file creation on {\tt\dol DA01} or any other disk.  Also, 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 \dol 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 named, and referenced by the
\ttaips\ program via an integer parameter in an adverb such as {\tt
INTAPE} or {\tt OUTTAPE}.  The definition of all tape drives is
centralized in one single file, {\tt\dol NET0/TPDEVS.LIST}.  A shell
script ({\tt TPDEVS.SH}) is called by various other scripts such as {\tt
START\char95 AIPS} and {\tt START\char95 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 a
particularly convoluted 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 likely to be encountered.
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}.
Refer to the previous sections describing {\tt INSTEP1} for additional
information about restrictions on the form of the device name, and the
related density switching performed by {\tt ZMOUN2.C}.

The sample {\tt TPDEVS.LIST} file in {\tt\dol SYSUNIX} (not the one copied
to your {\tt\dol NET0} area) shows common device names for the
architectures NRAO uses in-house.  The \AIPS routines {\tt ZTAP2} and
{\tt ZMOUN2} in the various architecture-specific Z routine areas in
general will know how to change device names on the fly to get the
correct density requested (see the {\tt DENSITY} adverb and its help
file in \ttaips).  It is vital that you enter the basic device name in
the {\tt TPDEVS.LIST} file.  For example, with an Exabyte 8500 on a Sun,
use {\tt /dev/nrst0} instead of {\tt /dev/nrst8}; and on an IBM RS/6000,
you should use {\tt /dev/rmt0} instead of {\tt /dev/rmt0.1}.  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,
Solaris, IBM, HP, Convex, and Dec (Ultrix and Alpha) 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 by default, \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 d\ae mon or d\ae mons 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\char95 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 named {\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\dol 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 ({\tt TPMON1}) will handle remote
requests for access to {\it FITS\/} disk files.  The second one {\tt
TPMON2} 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.  Even more work was performed with {\tt
15JUL93}, improving robustness, eliminating bugs, doing as much testing
as we possibly could on the equipment at our disposal, and more.  For
{\tt 15JAN94} we smoothed out the wrinkles and made sure the Dec Alpha,
Solaris and HP systems worked as we expected.  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 {\it 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 is somewhat obsolete 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 died with our last remaining convex (yucca) at
the AOC site.

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} files.  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}.

However, 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
TEKSRV} for this purpose, but there has been little interest expressed
in this possibility and it will probably never happen. \medskip

\newsubsubsection{Message Terminals}

As in the case of reserved terminals, the use of dedicated 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.  They are the hardware
equivalent of the {\tt MSGSRV} task running in a window on an X11
display (see below).

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.  At NRAO we used recycled and otherwise obsolete
terminals as \AIPS\ message terminals on our Convex systems while we had
them.  Like reserved terminals, message terminals can be added later by
simply defining them in your {\tt AIPSASSN.SH} and {\tt .CSH} files,
and they have to be fixed device names.

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

\medskip\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\dag{\eightpoint
                          Originally called TEKSERVER and MSGSERVER},
%%% 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.

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.
{\tt TEKSRV} by default 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, 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}).  There can
only be one instance of each server running on each \AIPS\ host at a
time.

The servers 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\char95 TEK\char95 EMULATOR}, default {\tt xterm}}
{\ndot {\tt AIPS\char95 MSG\char95 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.  If you decide on
site-wide defaults other than the above for these variables, you should
edit the {\tt AIPSASSN.*} files and make the definitions there.

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).  There is therefore no need to do anything (other
than what {\tt INSTEP1} has already done in the {\tt HOSTS.LIST} file)
to configure these at this stage.  There is 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 TEKSRV}, {\tt
MSGSRV}, and {\tt XAS} in {\tt\dol HLPFIL}, or just type, \eg, {\tt HELP
MSGSRV} 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{Old-style 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 and terminal emulators, such as
retrographics, visual 102G, Selanar, vterm--4010, \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 is 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, need to be
defined in your {\tt HOSTS.LIST} file.  As {\tt INSTEP1} will 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
(Versions of \AIPS\ older than {\tt 15JUL93} had this information in a
far less convenient form embedded in the {\tt TVDEVS.SH} file.)
%%% @@@ edit as needed above
The only exception to this is for ``hardware'' TV devices such as the
IIS, IVAS, and DeAnza image displays.  If you don't have any of these,
you can safely skip the information that follows.

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 the
gory details.
%%% @@@ is that a cop-out?  Need to show it here?  Nah.
For such hardware devices, you will have to define two environment
variables: \medskip

\item\bul {\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\bul {\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\char95 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 AIPSASSN.CSH} and defaults to {\tt /dev/console}.
\medskip

\newsubsubsection{Printers and Plotters}

The printer setup has changed with the {\tt 15JUL94} version.  Whereas the
information was previously specified in a {\tt PRDEVS.SH} file via direct
shell definitions, now there is a {\tt PRDEVS.LIST} file that will be
created in your {\tt\dol NET0} area by {\tt INSTEP1}.  See the section
``Printer Setup'' (2.3.9)
%%% @@@ check section
for an example of what one looks like.

The {\tt PRDEVS.SH} file is now generic and resides in the {\tt \dol
SYSUNIX} area; for backwards compatibility, a symbolic link to it is
placed in your {\tt\dol AIPS\char95 ROOT} directory.  Also, its behaviour
appears as before to the remainder of the shell scripts and so it can
safely be used --- with the new {\tt PRDEVS.LIST} file --- with older
versions of \AIPS\ (at least back to {\tt 15APR92}).

{\tt INSTEP1} will, if an older {\tt PRDEVS.SH} file is found in the
{\tt\dol AIPS\char95 ROOT} area (and the {\tt PRDEVS.LIST} file is not in
{\tt\dol NET0}), attempt to create the {\tt PRDEVS.LIST} file from the older
definitions.  If this is successful, no further questions will be asked.

If an older {\tt PRDEVS.SH} file is not found, but there is an {\tt
/etc/printcap} file on this system, an attempt will be made to parse that
file and extract the names of all printers defined therein.  If an older
{\tt PRDEVS.SH} file is not found, and neither is {\tt /etc/printcap},
then the script simply asks you how many printers you wish to define.

For each printer, you will be asked for its name (unless the {\tt
printcap} name was found), its type (one of {tt PS} for PostScript, {\tt
PS-CMYK} for color PostScript, {\tt QMS} for QUIC printers, {\tt TEXT} for
plain text, or {\tt PREVIEW} for screen previewers.  Finally, you will be
prompted for a description.  You may also use type {\tt REMOTE}; see the
description of the file and this option earlier in this document for
details.

The shell scripts {\tt ZLASCL} and {\tt ZLPCL2} have been made even more
generic than before, with the use of the {\tt F2PS} and {\tt F2TEXT}
filters.  There should be no need to edit these files, unless you wish to
change, \eg, to A4 format paper.  There are architecture-specific versions
of {\tt ZLPCL2} for IBM, Cray, and Solaris systems; the one for Solaris
should be moved or removed as it does not use the new filters.  These will
be in the {\tt\dol SYSLOCAL} area for these systems.

The printer selection is achieved in one of two ways.  If there is only
one printer specified in {\tt PRDEVS.LIST}, 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, show the 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.

The printing scripts have 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.

If you have a color PS printer, you should set its type to {\tt PS-CMYK}
in the {\tt PRDEVS.LIST} file instead of just plain {\tt PS}, and the
script will then be able to catch color output (such as from the task {\tt
TVCPS} and send it directly to the color printer regardless of the printer
specified by the user.  However, the ``feature'' of diverting monochrome
output from a color printer that was present in previous versions of
\AIPS\ has been discontinued.  If your users attempt to do this, they will
see a message:\medskip

\example{Warning!  Monochrome file on color PS printer!}\medskip

\noindent
Postscript 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*} C 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\dol 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}.  At the risk of
restating the obvious, it is unnecessary to run the procedure for binary
installations.  For source installations, 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 (\ie, do a {\tt
\dol CDTST} first).  The purpose of {\tt INSTEP3} is to compile a selected
subset (about 20) of all the possible programs in the \AIPS\ system
(over 300 and still growing).  The resulting executable modules are
moved to the appropriate {\tt\dol LOAD} (or {\tt\dol LOADn}) directory.  The
subset represents:\medskip

\item\bul the stand-alone program {\tt FILAIP} which creates
        the \AIPS\ system files and initializes all but the
        \POPS\ memory files;
\item\bul the stand-alone program {\tt POPSGN} which initializes
        the \POPS\ memory files that are created by {\tt FILAIP};
\item\bul 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\bul the system specific \AIPS\ startup program {\tt
        ZSTRTA}, and {\tt AIPS} itself;
\item\bul the tasks {\tt DISKU} and {\tt NOBAT};
\item\bul a subset of tasks originally known as the {\it
        Dirty Dozen\/} which includes FITLD, UVSRT, UVDIF, UVMAP,
        COMB, APCLN, SUBIM, CCMRG, CALIB, MX, VTESS, PRTAC
        and FITTP; and
\item\bul network tasks TPMON, TEKSRV, and MSGSRV.
\medskip

\noindent {\tt INSTEP3} begins by checking that the source code for 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\dol LIBR/*/SUBLIB} files as prescribed in
{\tt\dol 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 source-only
installations.  If you are performing a binary installation, you have the
option of using the ready-to-run system files on the tape, or to
regenerate them.  {\tt INSTEP1} will have presented a list of the
parameters used to generate the files on tape:\medskip

\example{INSTEP1: \#disks, \#catalog entries per disk: 15 -100}
\example{INSTEP1: \#interactive AIPS, \#batch queues: 4 2}
\example{INSTEP1: \#TV, \#TK devices: 10 255}
\example{INSTEP1: \#tape drives: 4}\medskip

\noindent These should be adequate for most installations.  If you wish to
increase any of the parameters other than number of disks and catalog
entries, you will have to regenerate the files.  {\tt INSTEP1} will run
the program if you indicate you wish to change the numbers.

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\dol SYSUNIX}, is simply an aid to running (via an {\tt exec} command)
the various standalone tasks outside of {\tt AIPS} and {\tt BATER}.
This procedure will call the {\tt HOSTS.SH}, {\tt AIPSPATH.SH}, and {\tt
AIPSASSN.SH} files in the {\tt \dol AIPS\char95 ROOT} area.  It also calls the
{\tt DADEVS.SH} file in {\tt \dol 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\char95 AIPS} script, if you should need this.

It uses the environment variable {\tt\dol AIPS\char95 VERSION} to find the file
(in the {\tt LOAD} subdirectory of same).  To change \AIPS\ versions,
use {\tt\dol CDOLD}, {\tt\dol CDNEW}, and {\tt\dol 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\dol DA00}, one (the message file for user 1) has to be
created in {\tt\dol DA01}.  If there is already a message file for user 1
there, {\tt FILAIP} will detect and 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\dol 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.  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
is stored in {\tt\dol AIPS\char95 VERSION/\dol 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\dol AIPS\char95 ROOT/DA00/\dol 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
It is again far easier to specify a larger number of TV's than you
currently have as it makes adding new TV servers a lot easier.
Otherwise you will have to go through a somewhat tortuous recipe in
order to create new image catalogs for each new system you add.
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!
\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\dol 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 \dol 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\dol 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}
(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 displayed 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.  User \#1 is permitted to set the password for any other user
number.  If the password is forgotten for user \#1, you will have to
delete or move the entire password file and recreate it via the program
{\tt FILINI}.  Make sure you know how big the password file needs to be
before deleting the old one.

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\dol 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}

\POPS\ is the command language of \AIPS.  The \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\char95 1}
\example{\ }
\example{Starting up POPSGN (RELEASE OF 15JAN94)}
\example{Enter Idebug, Mname, Version (1 I, 2 A's) (NO COMMAS)}
\example{\bf 0 POPSDAT TST}
\example{> \hskip 6cm \it (press RETURN when you see this)}
\example{POPSG1: Popsgen complete}
\example{POPSG1: UNKNOW \ 15JAN94 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\dol 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\dol 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 TST}.

After entering this information, {\tt POPSGN} will grind away for a
short 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\dol 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
item 19 in the {\tt SETPAR} list, \ie\ the local system identification
(name), is probably the only one that definitely should be set before
using \AIPS.  It 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 (more of it appears on some printouts).

Another interesting parameter is item 29, the ``2nd AP size''.  It now
defaults to whatever value the variable {\tt PKPWD2} has in the file
{\tt PAPC.INC}.  This file is found in either {\tt\dol INC}, the include
file area, or a system-specific version of this (\eg, {\tt \dol INCALLN}).
The default value is 1216 which gives a total pseudo-AP size of 5
Megabytes.  On systems with significant amounts of memory, you may want
to raise this limit to, \eg, 17 or 65 megabytes (these would allow a
full 2k or 4k image, respectively, to fit in memory).

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:
  Using host-specific file /AIPS/DA00/BABOON/DADEVS.LIST
  for AIPS data area definitions ("disks")
   Disk 1 is /DATA/BABOON_1
   Disk 2 is /DATA/BABOON_4

Starting up SETPAR (RELEASE OF 15JUL94)
Enter:  1=Start Over, 2=Change parameters, 3=Change DEVTAB, 4=Quit
2
  1  No. of AIPS data disks                 15
  2  No. of tape drives                      3
  3  No. of lines per CRT page              24
  4  No. of lines per print page            97
  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                 7
 11  No. of words in REAL 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)  Baboon (NRAO-CV SS2)
 20  Maximum user number (<= 4095)        4095
 21  TIMDEST minima disks  1 -  3 days   14.  14.  14.
 21  TIMDEST minima disks  4 -  6 days   14.  14.  14.
 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
 34  Delay time print file delete (secs)  1200
Enter number to change or  0 = Print, -1 = Return
-1
Enter:  1=Start Over, 2=Change parameters, 3=Change DEVTAB, 4=Quit
4
\endfortran
%%% dollar to match one above: $ (for emacs TeX mode; get colors straight)

\medskip\noindent
Many of the parameters are self-explanatory.  Others are largely
irrelevant, \eg, the AP parameters if you do not configure batch queues.
In general the figures above are what you should use, at least for the
more obscure items.

New to this release
%%% @@@
is the presence of item 34, ``{\it Delay time print file delete\/}''.
This quantity governs the time delay between submission of a print file to
be printed and its deletion by {\tt AIPS}.  If set to zero, it means the
temporary files created by any and all printing/plotting verbs and tasks
(\eg, {\tt LWPLA}, {\tt PRTMSG}) {\it will not get deleted\/}.  If set to
a non-zero positive number, the units are seconds, and the recommended
value is at least 300 (5 minutes).  While some Unix spooling systems
permit a ``delete on printed'' flag to the {\tt lpr} or {\tt lp} command,
this option is not available in some systems, \eg, Solaris.  The
time-delayed deleting of print files is a compromise, and while it solves
the problem for most cases, there are some times when it will not work.
If the time interval is too short and the print queue very busy, files may
get deleted before they get printed.  If it is too long, the print spool
area may fill up.

The disk parameters shown above are mostly irrelevant, as they get
overridden.  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 if you anticipate users defining
personal data areas that will not be referenced in {\tt NETSP}, it may be
wise to set some suitable default parameters in item 21.  Finally, item 33
(reserved users on the data areas) is again overridden by the values in
{\tt NETSP}.

Check that item 12, the number of TV devices, is set to the number of TV
servers (\AIPS\ hosts and TV hosts) and TV devices actually used at your
site, or better still set it higher than this so you don't need to
increase the number when adding a new host.

There are two parameters related to the ``AP'' in the list above.
Items 11 and 29 will always reflect the parameters the system was built
with when you run {\tt SETPAR} for the first time.
%%% @@@ check item numbers are still correct...
The value for {\it No.~of words in AP (in 1024s)\/} should be {\tt 64} for
any installation using the Pseudo-AP Q routines (\ie, most if not all
modern installations).  If you have a real AP, set the size accordingly
(and drop us a line; we are unaware of any Unix systems with such a
device).

The {\it Pseudo-AP 2nd memory (1024s)\/} parameter will be set at {\tt
1216} for most systems; this gives a total pseudo AP memory size of 5
Megabytes.  If you changed the value in the {\tt PAPC.INC} file to define
a larger AP array size before {\tt INSTEP2}, then the size you chose will
be reflected in what you see in {\tt SETPAR}.  You can of course adjust
this value downwards by using {\tt SETPAR}, but not upwards beyond the
pre-compiled limit you have set.  If you want to change the AP size
upwards, you will need to change the corresponding values in the {\tt
PAPC.INC} include file, and also recompile all routines in the {\tt\dol
QPSAP} and {\tt\dol QOOP} areas, as well as rebuilding all tasks that call
them (areas {\tt QPGM}, {\tt QPGNOT}, {\tt QPGOOP}, {\tt QYPGM}, and {\tt
QYPGNOT}).

If you want to support an AIPS environment where one host has a large AP
size, perhaps because of its large memory size, but the remaining AIPS
hosts do not, the use of {\tt SETPAR} is recommended.  This has been used
at NRAO to provide an 80-megabyte AP for large-memory systems via {\tt
PAPC.INC}, but reduce the parameter to 20 or 5 megabytes on smaller
systems that use the same binaries.  No obvious problems relating to
memory or the AP were observed.

{\tt SETTVP} is used to set TV specific parameters, and normally should
never be needed.  The default values are appropriate for the XAS TV
server, and as long as your users remember to give {\tt tvinit} as the
first TV command when they start up.  This will initiate a handshake type
protocol between {\tt XAS} and {\tt AIPS} which will set the TV parameters
to appropriate values as dictated by the parameters compiled into {\tt
XAS} and the X server under which it finds itself running.  If you have
not edited or changed the TV server's source code, and you do not have any
hard-wired TV devices, skip past the examples to the description of {\tt
SETSP}.
%%% @@@ make sure you haven't added something in between!

The following examples are probably obsolete, as they show the parameters
for a couple of ``hard-wired'' TV displays as they were on NRAO's Convex
C1 systems almost two years ago.  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 had 512 lines configured.

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 simplified 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
The only item not set in the handshake between the TV server and
\ttaips\ is item 3, and this will always be 256 unless you make drastic
changes to the source code of the TV server and have an X display with
more than 8 bits.

Finally, the {\tt SETSP} program may be useful to large sites.  It uses a
file called {\tt\dol 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 \dol AIPPGM/SETSP.FOR} command.
\medskip

\newsubsubsection{Setting up TEMPLATE areas and running SYSETUP}

Once you have a set of system files that is suited to your installation
for one host of a given architecture, you should create a {\tt TEMPLATE/}
directory under {\tt\dol AIPS\char95 VERSION/\dol ARCH/} if it does not
already exist, and copy a subset of the files into it (while they are
``virginal'', \ie, untouched by \AIPS).  While this has to be done by hand
for the source-only installation, the binary installation gives you a
choice: either use the pre-generated system files, or re-run {\tt FILAIP}
and {\tt POPSGN} to modify the parameters.  If you need to populate the
template area by hand, the following line should do it (for Bourne-like
shells):\medskip

\example{\dol\ cp \dol DA00/[ABMST]* \dol AIPS\char95 VERSION/\dol
                ARCH/TEMPLATE/}
\example{\dol\ cp \dol DA00/I[CD]C0000[01]* \dol AIPS\char95 VERSION/\dol
                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 one or more later, it is still best to set up the area at this
point.

Now you are almost ready to run the {\tt SYSETUP} script.  An attempt has
been made (with the {\tt 15JUL94} version)
%%% @@@ update as needed
to insert the knowledge of IC and ID files into this script, but early
reports indicate that it may not work perfectly; check the patch area on
the \AIPS\ anonymous ftp server, or contact the \AIPS\ group if in doubt.

If you need to fix up the image catalogs by hand, first make
sure you have enough image catalogs by counting the number of {\tt
IDC000*} files in your first {\tt\dol DA00} area.  Then compare this to the
number of AIPS and TV hosts in {\tt HOSTS.LIST} (this discussion assumes
no ``hardwired'' TV's).  If this sum exceeds the number of ID files, copy
the {\tt ICC00001;1} and {\tt IDC00001;1} files in the template area to,
\eg, {\tt ICC0001A;1} and {\tt IDC0001A;1}\footnote*{\eightrm You will
       have to escape the semicolons with a backslash for most shells.},
%%% placeholder
 in the {\tt\dol DA00} area, if the next TV would be number 26 (hex 1A).

When you run the {\tt SYSETUP} script, 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 \dol SITE}.  Then it operates in a loop on
all hosts in the list (skipping the one you indicated as the master).
If you call it with, \eg, {\tt SYSETUP FOOBAR PLUGH}, it will only
process hosts called foobar and plugh.  Whether these are new or old,
they should be already entered in {\tt HOSTS.LIST}.

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\dol 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\dol arch} (lowercase).  Then it copies
the files {\tt\dol AIPS\char95 VERSION/\dol arch/TEMPLATE/[ABMST]*} to the
{\tt\dol 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.  It also checks how many TV devices are defined (including TV
servers) and makes sure there are enough IC and ID files in the master
area.  If not, it copies more from the template area.

Then it will insert hard links in the host's {\tt\dol DA00} area to the
master machine's gripe, password, and image catalog/lock files ({\tt
GR}, {\tt PW}, {\tt IC} and {\tt ID} types).  Note that it does {\it
not} create new image catalogs; you have to do this yourself as
indicated above if you add new hosts.

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.

If you have multiple ``sites'' in the same {\tt\dol AIPS\char95 ROOT} to
support two or more incompatible architectures, you need to go through the
template area creation and {\tt SYSETUP} for each of them.  The
script will only process hosts within one {\tt\dol SITE} variable and so
limits itself to compatible architectures (if you have multiple sites
defined in your {\tt HOSTS.LIST}).

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.

In addition to checking for the usual things (see if it starts up, try
{\tt print 2 + 2}, look at a few inputs, try {\tt GO DISKU} and so on),
you can try the so-called DDT tests (if you're feeling ambitious).  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.  For
already-ported-to systems, if the simple tests above work, you probably
don't need to bother with the DDT.

%%% @@@ May need updating
However, please note that the DDT test underwent significant changes with
the {\tt 15JAN94} release of \AIPS.  See \AIPS\ memo 85 for the full
details.  The master DDT images are available via anonymous ftp from {\tt
baboon.cv.nrao.edu} in the directory {\tt pub/aips/DDT/15JAN94}.  Please
exercise discretion and ``netiquette'' if you wish to retrieve the large
ones!

When you have new DDT timing/accuracy results, {\it please\/}
communicate the results to the \AIPS\ group.  We strive to keep those
results in our memos and databases (and give you credit for it, of
course!)  Also if you are interested in timing tests, be sure to be
aware of the various factors that can affect this: NFS versus local
disks, system load or other users, 2nd AP memory size, slow v. fast
SCSI disks, amount of memory, OS version, and so on.  See \AIPS\ memo 85
for more details.

\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 displayed on your window or terminal, but the
basic system will still work.  You just won't have things like the TV
server, tek and message servers, and remote tape capability.

The way the {\tt aips} command is made available is via the {\tt
LOGIN.CSH} or {\tt LOGIN.SH} command; users who want access to
\ttaips\ should include the appropriate one in their login/profile files
(see ``{\it Login Procedures}'' above).  Then no additional work is
necessary on their part (or hopefully yours) to enable them to use
\AIPS.  It may be convenient for people in ``uppercase mode'' to make a
symbolic link in {\tt\dol SYSLOCAL} called {\tt AIPS}, in addition to the
one already there called {\tt aips}.

You may find it useful to copy the \AIPS\ ``man'' or manual page to your
local ``man'' area (your sysadmin will probably know where this is), \eg:
\medskip

\example{\# cp \dol 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\char95 AIPS} procedure goes through many steps, calling
some of the other files in the {\tt\dol AIPS\char95 ROOT} and {\tt\dol
SYSUNIX} areas, before it finally performs an ``exec'' to the {\tt\dol
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\char95 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? @@@  Probably.  Noone complains though.

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 actual program 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 network features,
\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.  The exception is machine foo, which just has to have its
X server grant permission to display X11 images from machine bar.  For
additional details on these options, see the \AIPS\ manual page in {\tt
\dol SYSAIPS} (or wherever you installed it), or type {\tt HELP AIPS} inside
\ttaips\ itself.

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

\fortran
$ aips

You have a choice of 10 printers.  These are:

     1.  Library FAST PostScript printer, Duplex
     2.  Library Fast PostScript printer, normal
     3.  Postscript printer downstairs
     4.  Postscript printer in room 215
     5.  Color Postscript printer, AIPS Cage
     6.  Postscript 35mm slides
     7.  GNU Ghostview X-windows previewer
     8.  Sun OpenWindows previewer
     9.  QMS1725 Postscript printer in GREEN BANK
     10.  Printer not.available, assume PostScript

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.LIST}
file.  The tenth printer would have indicated something other than {\tt
not.available} had the {\tt PRINTER} environment variable been defined.
At this point, you enter a number for the printer you want, and
continue:\medskip

\fortran
The output print queue is ps0dup, type PS

Data disk assignments:
  Using site-wide default file /AIPS/DA00/DADEVS.LIST
  for AIPS data area definitions ("disks")
   Disk 1 is /DATA/POLARIS_1
   Disk 2 is /DATA/BABOON_1
   Disk 3 is /DATA/BABOON_2

Tape assignments:
   Tape 1 is Exabyte 8500 (Sun) on BABOON
   Tape 2 is REMOTE
   Tape 3 is REMOTE

You seem to be at a workstation called baboon

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

   *   This is the AIPS login notice.  If this file is in $AIPS_ROOT,
       it will be printed out each time AIPS is started up.  You may
       also want to have it printed out by the .login or .profile if
       you have a dedicated AIPS account.

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

Starting up 15JUL94 AIPS with normal priority
Begin the one true AIPS number 1 (release of 15JUL94) at priority =   0
AIPS 1: You are assigned TV device   5
AIPS 1: You are assigned graphics device   5
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 There will be additional messages that may come out asynchrously
for additional {\tt TPMON} d\ae mons, and also some from the XAS
TV server and the {\tt TEKSRV} and {\tt MSGSRV} servers:\medskip

\example{XASERVERS: Starting TEKSRV on baboon, DISPLAY :0}
\example{XASERVERS: Starting MSGSRV on baboon, DISPLAY :0}
\example{XASERVERS: Starting XAS on baboon, DISPLAY :0}\medskip

\noindent The startup procedure tries to identify the username and
{\tt DISPLAY} variable if a server is found to be already running.

Unfortunately, these asynchronous messages 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 appeared
(two of them 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 color map.  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 color map becomes the
default.  When you move the focus (move the mouse or click on a
different window), the default color map 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\dol AIPS\char95 ROOT} area.  It is a good place
to put messages concerning the \AIPS\ system for all your users to
see.  The original is in {\tt\dol SYSUNIX}.

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.

If you have an older version of \AIPS\ and are sharing the data areas, you
may see the message:\medskip

\example{VERS TOO OLD}
\example{ABORT!}\medskip

\noindent when you first start the new version up.  This is not a
significant problem; it is simply the result of a failed attempt to read
the {\tt LASTEXIT} ``save-get'' file that contains various settings from a
given user number's last \AIPS\ session.  The {\tt\thisver} save-get files
are incompatible with some older versions.  Conversely, if you switch from
the new version to the old, it will complain about {\tt VERS TOO NEW}.
These messages will not hamper you in any other way.

\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 embarrassing).  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 Drives}

The major tasks that use the tape drives other than \ttaips\ itself are
{\tt FITLD} and {\tt FITTP}; the former reads FITS data and the latter
writes it.  Both can handle either UV or Image data, and both accommodate
tape or disk as the medium.  There are two older tasks: {\tt UVLOD} (reads
UV data only), and {\tt IMLOD} (reads images) but these each only have a
subset of the functionality of {\tt FITLD}.  The latter also has more VLBI
capabilities than its predecessors.

Getting tape I/O to work correctly in \AIPS\ is often extremely difficult
and frustrating.  Any tape device that \AIPS\ uses {\it must support
backspace operations on a per-file and per-record basis\/}.  This
eliminates all quarter-inch cartridge (QIC) devices as the nature of the
format they use prohibits such operations.  In addition, the tape driver
must support variable record-length read and write operations.

The success or failure of \AIPS\ tape I/O depends critically on the tape
interface routines {\tt ZTAP2} and {\tt ZMOUN2}.  These will require local
development for new ports, and they may require modification for existing
ports that have tape systems other than the specific types NRAO has direct
experience with.  Versions of {\tt ZTAP2} already exist in the various
subdirectories of {\tt\dol APLUNIX} and these should work without
modification on tape drives as follows:\medskip

%%% @@@ get from TPDEVS.LIST
\item\bul Exabyte 8mm 8200 and 8500 drives on a Sun, SCSI bus
                 (SunOS 4.1, 5.1, 5.2, 5.3) Vendor: Sun
\item\bul Exabyte 8mm 8200 on Sun (SunOS 4.1, SCSI) Vendor: CoComp
\item\bul Exabyte 8500 on Sun (SunOS 5.3, SCSI) Vendor: ZZYZX
\item\bul 4mm DAT drive on a Sun, SCSI bus (SunOS,
                 possibly with patches for backspace, variable records, and
                 knows-end-of-data).  Vendors: Exabyte, ZZYZX (HP 35470A)
\medskip
\item\bul IBM-supplied Exabyte 8200 and 8500 drives, SCSI bus
                 (AIX 3.1, 3.2)
\item\bul IBM-supplied 9-track drive (9348-012), SCSI bus (AIX 3.1, 3.2)
\item\bul HP 9-track 88780B drive, SCSI bus (AIX, SunOS too?)
\item\bul HP DAT drive on IBM, SCSI bus (AIX 3.2 or later)
\item\bul ZZYZX 1.3Gb 4mm DAT drive on IBM, SCSI, 150Mb personality
\item\bul ZZYZX Exabyte 8500 on IBM, SCSI bus (AIX 3.2 or later)
\medskip
\item\bul Convex 9-track drives (Convex-OS 8.0 or later)
\item\bul Storage-Tek 9-track drives on a convex (Convex-OS 8.0 or later)
\medskip
\item\bul TK50 on SCSI bus on DecStation/System (Ultrix 4.0/4.3);
                 Exabyte also?
\item\bul DEC 4mm DAT drive on Alpha OSF/1 systems (OSF/1 1.2) and
                 Intel/Linux systems with SCSI card.
\medskip
\item\bul HP 4mm DAT drive on HP 9000/7xx series (HP-UX 9.x).
\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} and possibly the {\tt ZMOUN2} routines, both of which have
extensive debug {\tt printf} statements in comments ready for your use.

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.  If you are
selecting a vendor for a tape drive and are concerned whether it will work
with \AIPS, you should impress on your sales representative the
requirement that the device provide status information (current file,
record number), perform backspaces over files and records, and reliably
report end of information and beginning of tape.

The way in which tape ``mounting'' in \AIPS\ works is as follows.  The
file {\tt TPDEVS.LIST} should contain the tape definitions for all systems
within a given site.  The tape names therein may need to be in a specific
format; comments in the file and in {\tt INSTEP1} should be a guide for
the format needed.  The reason for this need will be obvious momentarily.
When a user issues the {\tt MOUNT} command from within \ttaips, the {\tt
ZMOUN2} routine is called and is expected to do the following:\medskip

\item{1.} Check what sort of tape drive it actually is, if possible, via
        system calls.
\item{2.} Retrieve the value of the {\tt TAPEn} environment variable; {\tt
        TPDEVS.SH} will have defined this at \ttaips\ startup ({\tt n} is
        a number).
\item{3.} Check the value of the {\tt DENSITY} adverb from \ttaips.
\item{4.} Modify the device name if the density and tape drive type permit
        it, \ie, dual density exabytes or multi-density 9-track.
\item{5.} Store the modified device name in a special environment variable
        {\tt AMT0n}.\medskip

\noindent Subsequent access to the tape device will be through this hidden
{\tt AMT0n} environment variable.  The user should normally not ever know
about this variable, and it should {\it only\/} need to be set in the {\tt
ZMOUN2.C} routine.

The {\tt\dol APLGEN} directory itself contains stubbed versions of {\tt
ZTAP2} and {\tt ZMOUN2}.  If these are the versions that actually get
processed by the {\tt INSTEP2} phase and added to your Z-routine object
library, programs linked with it will tell you that one or both of the
routines ``requires local development'' whenever any tape manipulation is
attempted.  If you need to develop versions for a new architecture, use
either the {\tt \dol APLSUN} or {\tt\dol APLSOL} versions as a starting
point.

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 programs 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} for source installations
(see below).  For details on the DDT suite of programs, see \AIPS\ memos
73 ({\it AIPS DDT History}) and 85 ({\it DDT Revised and AIPSMark(93)
Measurements\/}.  You may want to request a DDT tape from the \AIPS\ group
in Charlottesville, or get them over the internet network via ftp or
world-wide web.

To obtain the small, medium, or large 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/15JAN94} and have names
beginning with {\tt DDTS} for the small set, {\tt DDTM} for medium and
{\tt DDTL} for large.  Preserve the names if you want the {\tt DDTEXEC}
procedure to read the files from a FITS disk area.  There should be 11
files for each set.  Please be considerate about getting the large data
set; we will appreciate it if you restrict such access to off hours as
the files are at least 4 megabytes apiece.

The world-wide web location of the \AIPS\ home page is given on the front
page of this document.  The DDT page is referenced therein, and can be
directly addressed via:\medskip

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

\noindent The master DDT images were recomputed (for the first time in
years) for the {\tt 15JAN94} release, and the procedure itself was also
overhauled.  {\tt ASCAL} was omitted and replaced with {\tt CALIB}, and
likewise {\tt UVLOD} and {\tt IMLOD} were replaced with the generic {\tt
FITLD}.  The ability to read the DDT files from FITS disk instead of tape
was also added.  See \AIPS\ memo 85 for the full details.  Also note that
you cannot use the older DDT images with the new procedures, and vice
versa.

Memos are also available on the {\tt baboon.cv.nrao.edu} anonymous ftp
server in the directory {\tt pub/aips/TEXT/PUBL}, and via WWW through the
\aips\ home page.  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
\dol AIPSPUBL} area you will find on your \AIPS\ installation, with the
difference that the ftp/WWW area is constantly being updated.  Most
\TeX\ memos will have a PostScript version as well.  For the DDT, the
relevant memos are numbers 85 and 73.

\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\char95
LICENSE\char95 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$}.
%%% placeholder
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 \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 should 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{\dol \ 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}.  Once again, if you have a binary tape, {\it you do not need to
run \/{\tt INSTEP4}; the task binaries were copied from the tape\/}.
For source installations, 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?  Not yet.
%%% 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 \dol AIPPGM/AIPS.FOR}\medskip
%
%%% \noindent but {\tt \dol AIPPGM/AIPS.o} exists and is
%%% up-to-date, {\tt SEARCH} will substitute {\tt\dol 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 is no doubt 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 testbed 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 or
580 workstations running AIX 3.2.5 as our main \AIPS\ workhorses.  These
have completely replaced the functionality of our older Convex C1's (we no
longer have any Convex systems in-house).  The main Scientist and
Programmer systems are mostly SparcStation IPC and IPX workstations at
SunOS 4.1.2 (with some at 5.3).  In addition, we have one Sparc--10 (SunOS
5.3, with 4 ``heads''), a few additional smaller IBM RS/6000s (AIX 3.2),
one DecStation (Ultrix 4.3/DEC Fortran), a Dec Alpha 3000 model 300
workstation (OSF/1), and our newest member of the \AIPS\ family, a Gateway
2000 486DX2/66V PC clone (Linux 1.1.47, OS updated almost daily).  VAX-en
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, and the Goddard
Space Flight Center in Greenbelt Maryland, we made a full port to the HP
9000 series 700 systems running HP--UX 8 and 9, and also to a Silicon
Graphics Indigo 2 system based on the 150MHz MIPS R4400 chip, running Irix
version 5.  A port to Apple's A/UX is in progress at the time of writing,
again, through the courtesy of outside users and a guest account accessible
to NRAO staff via internet.

In addition, \AIPS\ has been ported in the (somewhat distant) past to the
Alliant FX architecture and to Cray's UNICOS.  Non-NRAO sites have also
ported (or attempted to port) \AIPS\ to a variety of UNIX environments,
though not all these attempts worked, and we have never heard from some of
you who initially told us you were starting a port (are you still
there???)  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).

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''; at least it's more
common in the \AIPS\ world).  \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 VAX-en, DecStations (MIPS/RISC), Dec
Alpha (OSF/1), SGI (?) 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, select-able only at power-up.
However, the highest profile MIPS-based processor is easily the DecStations
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), Intel $\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\bul {\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 \dol QPSAP} routines mainly.

\item\bul {\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 \dol APLGEN/ZTTYIO.FOR}).

\item\bul {\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 may Require Local Development}

{\bf For new ports}, some Z routines may require local development.  These are
in the {\tt\dol APLGEN} and/or {\tt\dol 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\dol APLIBM}, {\tt\dol APLSOL} and {\tt\dol 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\bul tape manipulation ({\tt ZTAP2} and {\tt ZMOUN2}); look
                 at Sun and IBM versions for examples;
\item\bul line printer output spooling ({\tt ZLPCL2.C}
\item\bul IEEE to local floating-point conversion ({\tt ZR32RL},
                 {\tt ZR64RL}, {\tt ZRLR32} and {\tt ZRLR64})
\item\bul VLA archive tape data handling ({\tt ZDM2DL},
                 {\tt ZMCACL}, {\tt ZRDMF} and {\tt ZRM2RL})
\item\bul Other data conversion routines (\eg, {\tt ZI16IL},
                 {\tt ZILI16}, \etc) if you are installing \AIPS\ on a
                 64-bit machine
\item\bul Getting accumulated CPU time ({\tt ZCPU}; make sure
                 the units are right)
\item\bul Getting free space ({\tt ZFRE2}; the {\tt\dol APLUNIX}
                 version works for most systems)
\item\bul 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}, {\tt ZTAP2} and {\tt ZMOUN2}.  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}
and {\tt ZMOUN2} 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 \dol AIPGUNIX}.  {\tt
ZSTRTA} is executed as part of the \AIPS\ startup procedure
{\tt\dol 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 \dol 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
\dol 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 general, 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
file-systems 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 15JUL94 Release}

\medskip\newsubsubsection{Binary ``Load and Go'' Tapes}

The major difference in the {\tt 15JUL94} release --- as far as the
installer is concerned --- is the availability of a binary installation
tape for several architectures.  Using such a tape, there should be no
need to compile or link any of the source code.  However, the complete
source code is included on all binary tapes for completeness, and also to
allow additional architectures to be added to the installation (see
the section on Multiple Architectures near the beginning of this
document).

With so many possible variations in Operating System versions, compilers,
\etc., it is not realistic for NRAO to even try to provide a separate
binary tape for each combination.  What has been possible is to perform
the test installs prior to the release in as generic a way as possible,
using few or none of the ``add-on'' tools or packages that exist locally,
and create a binary tape based on the end product of the test
installation.  This has been performed, disk space and access to the
relevant systems permitting, for the following systems:\medskip

\item{\bul} SparcStation IPX, SunOS 4.1.2
\item{\bul} IBM RS/6000 model 580, AIX 3.2.5
\item{\bul} Dec Alpha AXP 3000/300, OSF/1 1.2
\item{\bul} SparcClassic LX (SunOS 5.3)
\item{\bul} Gateway 2000 486DX2/66V (Linux 1.1.23)
\medskip

\noindent In many cases, if your hardware/OS combination does not {\it
quite\/} match the above configurations, the binary installation should
still work.  In particular, it is highly likely that SunOS 4.1.3, OSF/1
1.3 and 2.x, and later versions of Linux will accept the binaries on the
distribution tapes and run them with no problems.  However, this cannot be
guaranteed.

There is no special procedure to accommodate the binary installations.  It
is still necessary to run {\tt INSTEP1} which in turn has been modified to
detect and correctly handle (we hope) both binary and source
installations.  Of course, the {\tt INSTEP2} et al.~procedures are
unnecessary for the binary case.

\medskip\newsubsubsection{Changes to how AIPS handles Printers}

The definition of printers is now handled in a way that is consistent with
that for tape drives, disks, and hosts.  A brand new generic {\tt
PRDEVS.SH} script has been written which gets its information from {\tt
PRDEVS.LIST} in the {\tt\dol NET0} area.  The external actions of the
script appear identical to the older {\tt PRDEVS.SH} files that had to be
hand-edited, so it is possible to use the newer version of the script with
older \AIPS\ versions.

The format of the {\tt PRDEVS.LIST} file is very similar to that of
{\tt TPDEVS.LIST}, \ie, a printer name as the first column, ancillary
information in following columns, and a description at the end.  If you
have an existing {\tt PRDEVS.SH} file with printer definitions, the {\tt
INSTEP1} script will attempt to use it to automatically generate the {\tt
PRDEVS.LIST} file.  Failing this, it checks to see if {\tt /etc/printcap}
exists and if so, gets a list of printer names from it.  If there is no
printcap file, it asks how many printers you want and what their names
are.

In addition to this change, two new programs were added: {\tt F2PS} and
{\tt F2TEXT}.  The former takes the place of the third party filters such
as {\tt lwf} and {\tt nenscript} that were required in older versions if
you wanted to convert plain text to PostScript.  You no longer need these
third party filters for \AIPS\ printing.  The latter essentially does the
same job as the {\tt fpr} or {\tt asa} programs (Fortran carriage control
converters).  These are built automatically during {\tt INSTEP1}.

\medskip\newsubsubsection{File Delete-on-Print delay Change}

Whereas in the last release, the parameter controlling the time delay
between submitting a file to the print queue and deleting it was a {\tt\#
define} in the source code, it is now a configurable parameter that you
can set via {\tt SETPAR}.

\medskip\newsubsubsection{Linux ``hack'' Removed}

The kludge alluded to in the {\tt 15JAN94} release notes below
%%% @@@ still there?
is no longer needed.  The {\tt MAX} function in the {\tt PARAMETER}
statements was removed from the two tasks and they now compile and link
without additional help under Linux.

%%% @@@ Probably more but that's all I can think of.

\medskip\newsubsection{Notes for the 15JAN94 Release}

Refer to the \AIPS Letter for {\tt 15JAN94} for lots of interesting
details about this release.  Some of the highlights are pointed out here.

\medskip\newsubsubsection{File Deletion before the darn thing is printed}

One rather nasty problem with previous releases of \AIPS\ was the
``feature'' that the \aips\ tasks themselves wanted to delete a file after
it was submitted to the print queue.  If the Berkeley {\tt -s} option
to {\tt lpr} was used in the {\tt ZLPCL2} shell script, a symbolic link is
made by the spooler to the file and the file itself is not copied to the
spool area.  This also happens by default on some systems, often triggered
by file sizes in excess of 1 megabyte.  However, if there are other
entries in the queue and the file is not processed right away, then the
\aips\ task will delete the file before the spooler can open it.

The ideal way around this would be to pass on an option to the {\tt lpr}
or {\tt lp} command to delete the file after printing.  Unfortunately this
feature is not in general available on System V spoolers.  So the
compromise arrived at in {\tt ZLPCL2.C} and {\tt ZLASC2.C} was to remove
the {\tt unlink()} call and replace it with a set of commands that in
effect delay the deletion by a fixed amount.  The default delay is 300
seconds and is set as a {\tt \#define} in the source code.  This feature
works nicely on Suns but seems to have some problems on AIX; the subject
is under investigation at the time of writing.  Watch in the patch area of
the \AIPS\ anonymous ftp server (see above) or the web \AIPS\ home page
for updates on this story.\medskip

\newsubsubsection{AIPS on a PC with Linux}

For many years, people within and without the \AIPS\ group talked and
sometimes joked about the idea of running \AIPS\ on a personal computer.
In recent years with the development of full 32-bit Intel 80386, 486, and
pentium based systems, the idea became more than just a fantasy.

Towards the end of 1993, Jeff Uphoff who was then a grad student at
Virginia Tech, contacted NRAO through his supervisors with the idea of
porting \AIPS\ to a 386-based PC that ran Linux.  This is a complete
operating system, available in the public domain, that is very Unix-like
and completely replaces the restrictive {\it DOS\/} or {\it MS-Windows\/}
environment.  See the Vendor-specific notes for more details on Linux and
what bits and pieces one needs to put together for an \AIPS\ machine.

Within a few weeks, Jeff was running the DDT tests on his home PC and
getting acceptable numbers --- at least in terms of accuracy!  Shortly
afterwards, Jeff visited NRAO with a tape, and installed Linux and his
port of \AIPS\ on a 486DX2/66V system within an afternoon.  The DDT
results on this indicated performance at about the level of an IPC.  Since
then, Jeff's work has been incorporated into the main \AIPS\ distribution
and {\tt tarsier}, an identical machine to the above, is now served by a
midnight job just as our IBM, Dec Alpha, and other in-house systems.

The only compiler needed for this port is Gnu C.  The public domain {\tt
f2c} (Fortran-to-C) translator is used on all the Fortran source in \AIPS.
Its use caused us to discover a veritable rat's nest of coding errors in
certain calling sequences that other compilers had completely missed.
There are two programs that use {\tt PARAMETER} statements with a function
embedded ({\tt MAX}) and a kludge has to be applied to get the converter
and compiler to work correctly with this (see the {\tt INSTEP1}
description earlier in this document).

Additional details can be seen in the ``AIPS on a Personal Computer!''
article in the {\tt 15JAN94} \AIPS letter (available online via ftp or
web).

\newsubsubsection{AIPS on Dec/Alpha}

The port to the Digital Equipment Corp. ``Alpha'' AXP architecture running
the OSF/1 operating system is also complete.  The fact that the compiler
technology used here and that used for Ultrix is very similar made this
quite an easy port (by \AIPS\ standards).  The {\tt \dol APLDEC} area is now
shared by both OSF/1 and Ultrix, with an additional Ultrix-specific
{\tt\dol APLULTRX} area for a few routines.  To really confuse you, the
{\tt\dol SYSDEC} area still refers to Ultrix, however, and {\tt\dol SYSALPHA} is
the Dec/Alpha system area.

\newsubsubsection{Improved HELP Facilities}

Two new verbs, {\tt APROPOS} and {\tt ABOUT}, make their debut in {\tt
15JAN94}.  The former works pretty much like {\tt man -k} in Unix, except
its database is derived from the \AIPS\ help files.  In other words, {\tt
APROPOS CLEAN} will show a 1-line summary for any help file that contain
words beginning with ``CLEAN'' in either the 1-line summary or the keyword
section of the help file.  It does this via a file {\tt LSAPROPO.HLP}
which is analogous to the ``whatis'' database for the Unix manual pages.
The {\tt LSAPROPO.HLP} file is in turn generated by the {\tt HLPB.EXE}
program.  If you modify a help file other than this one, you can update
{\tt LSAPROPO.HLP} as follows:\medskip

\example{\% cd /tmp; cp \dol HLPFIL/LSAPROPO.HLP .}
\example{\% \dol LOAD/HLPB.EXE FOOBAR.HLP}\medskip

\noindent This will create a LSAPROPO.OUT in the same area.  If it
differs from {\tt LSAPROPO.HLP}, you should rename the {\tt .OUT} file
to be {\tt LSAPROPO.HLP} and put it back in the help file area.

On the master \AIPS\ machine in Charlottesville, the above is performed
anytime someone checks in a help file; this keeps the ``apropos'' database
current at all times.

The {\tt ABOUT} pseudo-verb is similar, but it takes a restricted
``category'' as its argument.  Each help file in \AIPS\ has one primary
and one or more secondary keywords.  The allowed values for these keywords
can be found simply by saying {\tt HELP ABOUT} in \AIPS, and they are also
listed in {\tt PRIMARY.HLP} and {\tt SECONDRY.HLP}, respectively.

There is a new shell script {\tt SHOPH} in {\tt \dol SYSUNIX} that automates
the generation of the {\tt ZZ*.HLP} files used by {\tt ABOUT}.  It has not
been extensively tested but has worked for us on the few occasions we used
it.  You should not have to worry about this, as the {\tt ZZ*.HLP} files
are distributed with \AIPS and do not have to be regenerated.

\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\dol 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 accommodate both the {\tt
lpr}/{\tt lpq} Berkeley printing commands and the {\tt lp}/{\tt lpstat}
System V commands.

\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 81 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\dol 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\dol SYSUNIX}, or
{\tt\dol 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 occurrence 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 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.

\newsubsection{Notes for the 15APR91 Release}

No major system-level changes to report.  {\tt ZFRE2.C} in the
{\tt\dol 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\dol 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

%%% 15JAN91 release notes!  Nah.

\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


\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 will
%%% was ``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:
%
%%% \medskip
%%% \example{RUN UPDAT}
%%% \medskip\noindent
%
%%% The program responds with the following prompt.

%%% \medskip
%%% \example{ENTER : 1=RANGE OF USERS, 2=USER NUMS IN TEXT FILE :}
%%% \medskip\noindent
%
%%% 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\dol AIPS\char95 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:
%%% \medskip
%%% ENTER USER NUMBER RANGE. (DEFAULT=    1 4095)  :
%%% \medskip\noindent
%%% 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:
%%% \medskip
%%% ENTER AIPS DISK NUM RANGE (DEFAULT=  1  1)  :
%
%%% ENTER OLDEST VERSION DATE AS 15MMMYY  (DEFAULT= 15OCT89 ) :
%%% \medskip\noindent
%
%%% The program will then display a summary of the data you have entered
%%% and give you a chance to re-enter.
%%% \medskip
%%% USER NUMBER RANGE :     1  100
%%% DISK RANGE        :     1    1
%%% OLDEST DATA       : 15OCT89
%%% ENTER : 1=I MADE A MISTAKE, REENTER, 2=CONTINUE :
%%% \medskip\noindent
%%% 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 quite outdated 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 find solutions to problems you encounter
from the notes below.\medskip

\newsubsection{Sun Systems}

The primary workstation at all of NRAO's sites is Sun's Sparc.  At the
time of writing, the mix includes IPX, IPC, Sparc2, Sparc10, and
SparcClassic systems.  There are one or two Sun--3's hanging on and used
only as X terminals.  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 4.1.3.  See the separate section on Solaris below for versions
SunOS 5.x.

\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 never got 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}.  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 \dol 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 \dol APLUNIX/ZACTV9.C}) {\it from an older
release of \AIPS, \eg {\tt 15OCT92}} instead by moving it to
your {\tt\dol 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: {\parindent=3cm
\item\bul by defining the environment variables {\tt COMP} in the
        section of {\tt \dol SYSUNIX/FDE\-FAULT.SH} relevant to your
        architecture, and
        {\tt LINK} in your local version of {\tt LDOPTS.SH}, to include
        the the desired floating point option, or:
\item\bul by defining the environment variable {\tt
        FLOAT\char95 OPTION} as part of your login procedure.
}
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 co-processor.  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 {\it 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 {\tt
\char95 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\dol SYSLOCAL/SYSTEM.C}
containing:
\fortran
          system_(s,n)
          char *s;
          int n;
          {
              system(s);
              return;
          }
\endfortran
Then {\tt CC \dol SYSLOCAL/SYSTEM.C} and modify {\tt\dol SYSLOCAL/LDOPTS.SH}
so that the link options line looks like: {\tt LINK="\dol DEBUG
\dol SYSLOCAL/SYSTEM.o /usr/lib/libc.a"}.

%%% no longer relevant?
\item{7)} For {\tt SUN3}, there was a change in the fpa floating-point
exception handling as of OS 4.0.  In {\tt \dol APLSUN/ZABORS.C}, the call to
{\tt sigfpe\char95 handler} should be changed to a call to {\tt fpa\char95 handler}
for systems with floating-point accelerators.  {\it No modifications are
necessary for Sparc systems.}

%%% \item{7.5)} Under OS 4.0, in {\tt \dol APLUNIX/ZTPCL2.C}, errno 1 (not
%%% owner) occurs while closing the 2nd {\it dup'ed\/} (see {\tt
%%% \dol 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
%%% \dol 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}.  You can alleviate
this to some extent by specifying {\tt SAVE=TRUE} in your local {\tt
LDOPTS.SH} file; this moves the {\tt AIPS.EXE} file to {\tt AIPS.EXE.OLD}
before inserting a brand new {\tt AIPS.EXE} (similarly for any {\tt
COMLNK}'d task).

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, or use the SAVE option.}

\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}.  As of {\tt 15JAN94}, {\bf this should not happen}.  It
is a fatal error under Solaris 2 (see below), and we have tried to
eliminate all causes for this error.  In previous \AIPS\ versions, the
advice given here was to ignore the warnings.  Don't; instead, let us know
the details.

\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\dol 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

\item{13)} If you are using GNU C in place of the Sun C compiler, be sure
to include the GNU C library in the link options in {\tt LDOPTS.SH}.  If
you do not, tasks will fail to link with an unresolved reference to {\tt
\char95\char95\char95 eprintf}.

\medskip\newsubsection{Solaris (Sparc) Notes}

\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 in addition to the default.

\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.  This test install was for
{\tt 15JUL93}.  For later releases, the data disk was on a regular disk
and no problems were found.

\item{4)} The Solaris version of the {\tt ZLPCL2} shell script did not get
upgraded or removed when the generic version was modified to use the new
{\tt F2PS} and {\tt F2TEXT} printers.  You should rename this script to be
something else (or {\tt chmod -x} it to make it not executable), so that
the generic version in {\tt\dol SYSUNIX} is used instead.  The older
Solaris version uses something called {\tt postprint} which we found on
our machine in the {\tt /usr/lib/lp/postscript/} directory.

\item{5)} Some Solaris sites have reported problems with the Solaris 2.3
automounter.  If an \AIPS\ data area has not been accessed for 5 minutes
(or whatever the automounter timeout is), that area is unmounted and the
next access by \AIPS\ may get a ``file not found'' error.  Repeating the
\AIPS\ task is usually enough to get around the problem.  Another possible
solution is to have a shell process sitting with its current working
directory in the relevant data area.  Yet another is to increase the
automounter timeout (\eg, to $200,000$ seconds).

\item{6)} See items 10, 12, and 13 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, Convex-OS, 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.  Fortunately, the {\tt -qextname} option
takes care of this rather nicely.  Older versions of \AIPS\ used a
rather tortuous and occasionally unreliable method of preprocessing to
correct the problem.

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\char95 POSIX\char95 SOURCE} and {\tt -D\char95 ALL\char95 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).  Since the {\tt 15JUL93} release,
%%% @@@
Ultrix 4.3 and DEC Fortran are the tools of choice.  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{Dec Alpha AXP, OSF/1}

The similarities between the compilers on this system and those available
under Ultrix were so great that there are few differences between the
ports.  The default Bourne shell is a lot better on OSF/1 but {\tt
INSTEP1} still needs to run as a Korn shell script; it will modify itself
and ask to be restarted.

As this system is fundamentally a 64-bit architecture, the memory
requirements for it seem to be considerably higher than for typical 32-bit
systems.  We have run DDT tests on an AXP 3000 model 300 system under
OSF/1 1.2 with both 32 and 64 megabytes of memory.  In the former case,
the elapsed time was dominated by OS disk activity, whereas there was a
notable improvement in the latter case.  We suspect that 128 megabytes of
memory would have been a lot more comfortable.  For more on these tests,
refer to AIPS memo 85.

Certain older versions of the compilers and operating system seem to cause
floating point underflows to generate an exception, regardless of {\tt
-fpe} options used for the compiler.  This has been seen with OSF/1
version 1.2 and DEC-Fortran 3.3 at NRAO.  Reports from outside users
indicate that an upgrade to OSF/1 2.0 and DEC-Fortran 3.4 solves this
problem; as the problem existed in the system shared libraries, a
re-compilation is not necessary (unless you used additional directives in
{\tt LDOPTS.SH} to force completely static binaries to be created).
\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 for {\tt 15JUL93} was
done on this newer system; at the time of writing, a test install has not
been performed on {\tt 15JAN94} or {\tt 15JUL94}.
%%% @@@ update as needed.

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 (and
switch to non-shared for your sanity).  Conversely, if you find shared
libraries work well for you, {\it please\/} let us know the details!
\medskip

\newsubsection{Intel/Linux}

Currently the only PC operating system \AIPS\ runs on is Linux, which is a
free (public domain) UNIX-like operating system available by anonymous ftp
from {\bf sunsite.unc.edu} (preferred) and {\bf tsx-11.mit.edu}.  See
below for more details on versions of the bits and pieces you will need.
In the future, alternate freely-available Unix-like operating systems may
also be supported, but we can make no promises.

Initial benchmarks in November 1993 put \AIPS\ on an Intel {\it
486DX2/66V\/} at roughly the same speed as a Sun IPC (roughly 0.5 AIPSMARKS
as defined by the old "large DDT").  A 486DX/33 runs the DDT (small) just
over half as fast as a DX2/66, and a 386DX/33 (even with a 80387
installed) is so slow as to be nearly unusable in any serious applications
(about 45 minutes for the Small DDT; compare this to 10 minutes on the
486DX2/66V).  Tests with a 486SX/33 (The author's home system!) reveal
that the DX processor (which has hardware floating point support) is
almost a pre-requisite for running \AIPS.  It works with only the SX
processor, but it is painfully slow mainly due to the floating point
emulation.

The official {AIPSMark$^{(93)}$} for the {\it 486DX2/66V\/} system is 0.51
(see \AIPS\ memo 85).  The minimal and ``comfortable'' system requirements
are as follows:

\item\bul A 386 or better (486, pentium) processor.  A 486DX at 33
        MHz is probably the lowest ``usable'' system.  On 486SX or any 386
        systems, make sure you have the math co-processor.

\item\bul 8 Megabytes of RAM (more if you plan on running X windows and/or
        AIPS heavily; our benchmarks on the 486 were with 16 and 32 megs).
        16 Megabytes of swap space is also recommended; you can have
        multiple swap partitions/files and this will improve performance
        for largish problems.

\item\bul If you want to run X windows, a color monitor is
        recommended.  Most SVGA card/monitor combinations are supported by
        the Linux X server.  The NRAO system we run has an ATI Mach\_32
        chip-set accelerated SVGA card.

\item\bul For a full Linux/X11/\AIPS\ installation, you will need
        about 100 Megabytes for the Linux/X11 part, and about 170--200
        Megabytes for all of AIPS, assuming you strip the {\tt *.EXE}
        files (they are stripped on the binary Linux tape and take up 103
        megabytes).  Add to that whatever you want for local user data.  A
        400 megabyte disk would give you $100+$ Megabytes for AIPS data
        after you are done with everything else.

\item\bul All software needed is in the public domain or under a
        GNU Copy-Left (except \AIPS\ which is of course freely available
        under the usual user agreement to academic/education/research
        sites).

\medskip\noindent
The software pieces that you will need include:\medskip

\item\bul Any Linux kernel since about $0.99.12$ (except $0.9.13$ which
          had file locking problems) with {\tt gcc} (GNU C}.
\item\bul The {\tt f2c} Fortran to C converter (versions from Oct 1993 or
          more recent).  The {\tt f77} shell script front-end to {\tt f2c}
          was modified locally to perform some \AIPS -specific functions,
          and the modified version is included in the \AIPS\ distribution,
          making its way to {\tt\dol SYSLOCAL} via the installation
          procedure {\tt INSTEP1}. \medskip

\noindent
All kernel sources, libraries, and compilers that you will need are in the
public domain, covered by the GNU public license.  They are available on
the sites mentioned above.  There are also several Linux "packages"
available on these archives that can be used to build a complete, working
system.  These are not necessarily needed for \AIPS\ but you may want them
for other purposes.

Some of the details of the port follow.

\item{1.} The {\tt /usr/lib/libbsd.a} library was used for the socket
        library, because of BSD-style {\tt ioctl()} calls used by \AIPS.
        This should be transparent to both the installer and the end user,
        as it is included in {\tt LDOPTS.SH}.  This also necessitated
        using the include file {\tt <bsd/sgtty.h>} as the definitions of
        {\tt TIOCGETP} and {\tt TIOCSETP} are here.  {\tt sgtty.h}
        redefines {\tt ioctl()} as {\tt bsd\char95 ioctl()}, which is only in
        {\tt libbsd.a}.  Again, everything should be taken care of and no
        code changes should be needed.

\item{2.} {\tt INSTEP2} was observed to hang when compiling large
        libraries (those containing a large number of object files).  This
        may have been due to an old version of {\tt bash} and has not
        happened recently.  It may have also been due to the passing of a
        greater number of command line parameters to COMRPL than the
        environment can handle.  A simple {\tt CONTROL-C} and re-execution
        of {\tt INSTEP2} will restart it where it left off.  Likewise for
        {\tt INSTEP4}.
%%% @@@ update above as needed.

\item{3.} Local tape access has been investigated by using an Adaptec (?)
        SCSI card and borrowing the DEC Alpha's 4mm tape drive (vendor:
        Digital).  We have managed to get some functionality with this
        system, but it is still not as robust as we would like.  Currently
        it supports writing but reading does not work.  The workaround for
        FITS tapes is to use {\tt dd bs=28800} to dump files from tape to
        disk and thence into {\tt AIPS} via {\tt FITLD}.
%%% @@ Didn't Eric say something about rewriting the driver?  Details?
        Most PC's have either no tape drive or have a QIC (quarter inch
        cartridge) or similar drive.  The latter is incapable of backspace
        operations (other than rewind) so is of little interest to \AIPS,
        other than for backup of FITS disk files.
        Remote tape access, and FITS disk file access both work.

\medskip\newsubsection{Silicon Graphics}

The port to Irix version 5 on a Silicon Graphics workstation was performed
by Jeff Pedelty at NASA's Goddard Space Flight Center (GSFC) in Greenbelt,
Maryland.  It went quite smoothly, and was probably made easier by the
improved System V (''Bell'') support obtained from previous ports
(Solaris, HP).

Once again, the weak point of this port is mag-tape access.  Work is
continuing (at the time of writing) on improving this, but without an
actual machine for us to ``beat on'' in-house, progress on sorting out the
magnetic tape access problems will be unavoidably slow.

%%% @@@ ask Jeff for more info?

\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\char95 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 quite 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 \dol SYS\-CVEX/\-OPT2.LIS} (yes, {\tt
\dol 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\dol SYSCVEX/OPT2.LIS} (yes, {\tt\dol 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\dol 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\dol 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 \dol OPT0 \dol 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\dol 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\dol 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\dol 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}.  The section of
code around statement 110 should read:\medskip
\fortran

      SUBROUTINE QCLNSU (COMP, LMAP, L1MAP, L2MAP, IBX, IBY, JNDEX,
     *   INDEX)

      ....
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.
      IRCALL = 0
      DO 120 LOOP = 1,NIB
         IF (IB(LOOP).EQ.0) IRCALL = 1
 120     CONTINUE
      IF (IRCALL .EQ. 1) GO TO 110
C                                        Subtraction loop
      ...
\endfortran
\medskip\noindent

\item{6)} The call of {\tt\dol QALN/SCFFT.o} by {\tt\dol 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\dol 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\dol SYSLOCAL/LIBR.DAT}) for all programs linked with the Q-routine
object library (see {\tt \dol 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\dol 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 also with an IVAS.  All three had
several Gigabytes of striped disk.

However, all of these Convex systems have been de-commissioned and removed.
Our last, {\tt yucca}, was turned off for the last time in early 1994.
Thus, our support for Convex systems in the future will not be at the
level found in older releases.

The last release of \AIPS\ to be run in production mode on a NRAO Convex
was {\tt 15JUL93}.  The configuration was Convex-OS 9.0 with IEEE
floating-point selected via the {\tt -fi} compiler switch.  \AIPS\ is
still in production use elsewhere on other Convex models, including the C2
and C3 series.  However, as the \AIPS\ code and the Convex OS both
continue to change, the possibility of encountering bugs/problems in the
Convex version will no doubt increase.

\item{1)} The {\tt\dol SYSCVEX} directory contains a number of files used
in \AIPS\ programming that are setup for Convexes.  These files will
be copied to your {\tt\dol SYSLOCAL} directory by the {\tt INSTEP1}
procedure and override the versions found in {\tt\dol SYSUNIX}. The {\tt
\dol SYSNRAO1} and {\tt \dol SYSVLAC1} directories are the {\tt\dol 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.  You should try to
rely as much as possible on the generic {\tt\dol SYSCVEX} files where
possible.

\item{2)} The {\tt\dol 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\dol APLCVEX} version of this last file is set up for ``native''
floating point, whereas the {\tt\dol APLNRAO1} and {\tt\dol APLVLAC1}
versions (identical) both use IEEE format.

\item{3)} The routine {\tt QRECT.S} in the directory {\tt \dol QVEX} will
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 Convex-OS releases.  If not,
the {\tt \dol 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 Convex-OS broke the old version of
{\tt ZDELA2.C}.  The symptoms were that tasks refuse to go away
when they complete.  The file {\tt\dol APLCVEX/ZDELA2.C} will work fine
for this version, but pre-9.0 systems should use the more general
{\tt\dol APLBERK} version (otherwise tasks won't even get started!).

\item{7)} {\tt\dol APLBERK/ZCREA2.C} failed to compile on Convex-OS 9.0
because of problems in the included file {\tt <sys/mount.h>}.  The
version in {\tt\dol 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 \dol 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)!  Also, {\tt\dol APLUNIX/ZCREA2.C} will need
some attention as it also uses 32-bit integers to calculate the number of
free {\it bytes\/} on the relevant file-system before creating a new file.
On systems where the free space can exceed 2 Gigabytes, this will cause
overflow and tasks will die.
\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 the
files {\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

\vfill\eject
\input UGUIDE_APDX_1.TEX
\end
