%-----------------------------------------------------------------------
%;  Copyright (C) 1995-1998, 2000-2009, 2012-2018, 2020, 2022-2025
%;  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
%-----------------------------------------------------------------------
\chapts{Basic \AIPS\ Utilities}{basic}

\renewcommand{\titlea}{31-December-2025 (revised 10-October-2025)}
\renewcommand{\Rheading}{\AIPS\ \cookbook:~\titlea\hfill}
\renewcommand{\Lheading}{\hfill \AIPS\ \cookbook:~\titlea}
\markboth{\Lheading}{\Rheading}

     This chapter reviews some basic \AIPS\ utilities with which you
should be familiar before you start calibrating data or processing
images in \hbox{\AIPS}.  Many of these utilities will appear in later
chapters on calibration, image making, and so on.  However, in those
chapters, these utilities will be explained only briefly.

\sects{Talking to \AIPS}

\subsections{\POPS\ and \AIPS\ utilities}

     When using the \AIPS\ system, you talk to your computer through a
command processor called \iodx{POPS}\POPS\ (for People Oriented
Parsing System) that lives in the program \hbox{{\tt \tndx{AIPS}}}.
The steps needed to start this basic program are discussed in
\Sec{stAIPS}.  The copy of this program that you get will be called
{\tt AIPS{\it n\/}} where {\it n\/} is often referred to as the
``\POPS\ number'' of your session.

     The \POPS\ command processor is not unique to \hbox{\AIPS}.  It
has been present in other programs at the NRAO for many years, and
will be familiar to users of the NRAO single-dish telescopes.
Chapters 4 to 11 of this \Cookbook\ give explicit examples of most of
the \POPS\ commands that a new \AIPS\ user needs to know, so we will
not give a separate \POPS\ tutorial here. The command {\us HELP
\tndx{POPSYM} \CR} will list the major \POPS\ language features on
your terminal, and \Rchap{pops} below reviews some advanced features
of \hbox{\POPS}.

     As well as providing a command processor, \AIPS\ replaces many
features of your computer's operating system with its own utilities.
This may seem inconvenient at first --- you will have to learn the
\AIPS\ utilities as you go along. You will see the advantage of this
approach when you use \AIPS\ in a computer that has a different
operating system.  Your interface to \AIPS\ will be almost identical
on a VAX, or a Convex C-1, or a Unix-based workstation, or a Cray
\hbox{X-MP}.  Once learned, your \AIPS\ skills will therefore be
highly portable.

     Lists of the important \AIPS\ utilities can be obtained at your
terminal by typing {\us ABOUT CATALOG \CR} and {\us ABOUT GENERAL
\hbox{\CR}}.  See also \Rchap{list} for a relatively recent version of
all such category lists.

\Subsections{Tasks}{tasks}

     \AIPS\ provides a way for you to set up the parameters for, and
then execute, many applications programs sequentially or in parallel.
The more computationally intensive programs may take many minutes, hours
(or even days) of CPU time to run to completion.  They are therefore
embodied in \AIPS\ ``\Indx{task}s'' --- programs that are spawned by
the {\tt AIPS} program to execute independently and asynchronously
(unless you choose to synchronize them).  This lets you get on with
other work in {\tt AIPS}, while one or more tasks are running.  You
may spawn, however, only one copy at a time of each task from a given
\AIPS\ session (\ie\ \POPS\ number.)

      A typical task setup will look like:
\btd
\dispt{TASK \qs `{\it task\_name\/}` \CR}{to make {\it
        task\_name\/} the default for later commands; note the quote
        {\tt `} marks.}
\dispt{\tndx{HELP} \CR}{to write helpful text on your terminal about
        the purpose of the task and about its input parameters.}
\etd
\dispe{You will then spend some time setting up parameter values, as
in \Sec{adverbs} below.  Then, type}
\btd
\dispt{INP \CR} {to review the parameter values that you have set and}
\dispt{\tndx{GO} \CR} {to send the task into execution.}
\etd
\dispe{You may also specify which task you want to execute by an
immediate argument, \eg\ {\us GO \qs UVSRT \CR} to execute the task
\hbox{{\tt UVSRT}}.  After the {\tt GO} step, you will watch for
messages saying that the task has started executing normally, has
found your data, etc., while you get on with other work in
\hbox{\AIPS}.}

     If you discover that you have started a task erroneously, you may
stop it abruptly with
\btd
\dispt{\tndx{ABORT} \CR}{to kill the task named by {\tt TASK}, or}
\dispt{ABORT \qs {\it task\_name\/} \CR}{to kill {\it task\_name\/}.}
\etd
\dispe{This will stop the job quickly and delete any standard scratch
files produced by it.  However, input data files --- and output data
files that are probably useless --- may be left in a ``busy'' state in
your data catalog.  The catalog file is described in \Sec{catalog},
including methods to clear the ``busy'' states and to delete
unwanted files.  Note that you may also stop a task running under
another \AIPS\ number by setting adverb {\tt NUMTELL} to that number.}

     Similarly, you may tell the current {\tt AIPS} session to wait
for the completion of a task before doing something else using
\btd
\dispt{\tndx{WAIT} \CR}{to wait on the task named by {\tt TASK}, or}
\dispt{WAIT \qs {\it task\_name\/} \CR}{to wait on {\it task\_name\/}.}
\etd
\dispe{You may also wait on a task running under another \AIPS\ number
by setting adverb {\tt NUMTELL} to that number.  Note that {\tt AIPS}
will continue after the task finishes even if it finishes badly;
see  \Sec{moreGO}.}

     The current full list of tasks may be obtained on your terminal
(or workstation window) by typing {\us ABOUT \qs TASKS \hbox{\CR}}.
Since this list runs for many pages, you may wish to direct the output
to the line printer (with {\us DOCRT = -2 \CR}) or to consult the
list in \Rchap{list} of this \Cookbook.

\subsections{Verbs}

     Some of the smaller \AIPS\ utilities run quickly enough to be run
inside the {\tt AIPS} program rather than being spawned.  These
``\Indx{verbs}'' include simple arithmetic and \iodx{POPS}\POPS\
operations, the {\tt HELP}, {\tt ABOUT}, {\tt INP}, and {\tt GO}
commands mentioned already, interactive manipulations of the TV-like
display, and many more.  Verbs are sent into action simply by setting
their input parameters and typing the name of the verb followed by
\hbox{\CR}. (The sequence {\us GO \qs {\it verb\_name\/} \CR} will also
work, but a bit more slowly since it also saves the input parameters
of the verb for you; see \Sec{inputs} for a further discussion of saved
parameters. The sequence {\us TASK \qs `{\it verb\_name\/}' ;  \qs GO
\CR} will not work, however.)  While a verb is executing, {\tt AIPS}
will not respond to anything you type on the terminal (but it will
remember what you type for later use).  Just watch out for messages
and do what is called for with the TV cursor or terminal.  You may, of
course, think about what you will do next.

     You can list all the verbs in \AIPS\ on your terminal by typing
{\us \tndx{HELP VERBS} \CR}, but the output lists only the names.  To
find out more, type {\us ABOUT \qs VERBS \CR} which describes what the
verbs do.  Since this output fills several pages, you may wish to
direct it to the line printer (set parameter {\tt DOCRT} to -2), or to
consult the (perhaps dated) list printed in \Rchap{list} of this
\Cookbook.
\vfill\eject

\Subsections{Adverbs}{adverbs}

     \AIPS\ uses ``\Indx{adverb}s'' (which may be real numbers or
character strings, scalars or arrays) to pass parameters to both
``verbs'' and ``tasks.''  A significant part of your personal time
during an \AIPS\ session will be spent setting adverbs to appropriate
values, then executing the appropriate verbs or tasks.  Examples of
adverb-setting commands in \AIPS\ are:
\btd
\dispt{CELL 0.5 \CR}{to set a single scalar {\tt CELL} to {\tt 0.5}}
\dispt{CELL 1/2 \CR}{alternate for above with \POPS\ in-line
                      arithmetic}
\dispt{IMSIZE 512,256 \CR}{to set a two-element array {\tt IMSIZE} to
                      {\tt IMSIZE(1)=512, IMSIZE(2)=256}}
\dispt{IMSIZE 512 256 \CR}{an alternate for the above if both values
                       are positive}
\dispt{IMSIZE 256+256,256 \CR}{an alternate for the above using \POPS\
                       in-line arithmetic}
\dispt{UVWTFN 'NA' \CR}{to set a string variable {\tt UVWTFN} to the
                       value {\tt NA}}
\dispt{LEVS 0 \CR}{to set all elements of the 30-element array {\tt
                       LEVS} to zero}
\dispt{LEVS = -2,-1,1,2,3,4,5 \CR}{to set {\tt LEVS(1)=-2,
                       LEVS(2)=-1,} {\tt LEVS(3)=1}, etc.  The {\us =}
                       avoids in-line arithmetic that would otherwise
                       subtract 2 from {\tt LEVS(1)}}
\dispt{LEVS = -2,-1 1 2 3 4 5 \CR}{an alternate for the above; the
                       comma avoids in-line arithmetic that would
                       otherwise set {\tt LEVS(1) = -3}}
\etd

     Many \AIPS\ tasks will assume sensible ``default'' values for
adverbs that you choose not to (or forget to) specify.  Some adverbs
cannot be sensibly defaulted; these should be clearly indicated in the
appropriate help information.  You may review the current input
parameters for any \AIPS\ task or verb by typing
\btd
\dispt{\tndx{INP} \CR}{to review the parameters for task {\tt TASK},
            or}
\dispt{INP \qs {\it task\_name\/} \CR}{to review the adverbs for task
            {\it task\_name\/}.}
\etd
\dispe{Any adverbs which you have set to {\it \`a priori\/} unusable
values will be followed on the next line by a row of asterisks and an
informative message.  Details of the input parameters used by any
\AIPS\ verb or task can be obtained on your terminal by typing:}
\btd
\dispt{HELP \CR}{to review the parameters for task {\tt TASK}, or}
\dispt{\tndx{HELP} \qs {\it task\_name\/} \CR}{for task {\it
            task\_name\/}}
\dispt{HELP \qs {\it verb\_name\/} \CR}{for verb {\it verb\_name\/}}
\dispt{HELP \qs {\it adverb\_name\/} \CR}{for adverb {\it adverb\_name\/}}
\etd
\dispe{See \Sec{help} below for more methods of obtaining on-line help
with \hbox{\AIPS}.}

     You can list all the adverbs in \AIPS\ on your terminal by typing
{\us \tndx{HELP ADVERBS} \CR}, but the output lists only the names.
To find out more, type {\us ABOUT \qs ADVERBS \CR} which describes
what the adverbs do.  Since this output fills several pages, you may
wish to direct it to the line printer (set parameter {\tt DOCRT} to
-2), or to consult the (perhaps dated) list printed in \Rchap{list} of
this \Cookbook.

\vfill\eject
\Sects{Your \AIPS\ message file}{message}

    {\tt AIPS} and all tasks talk back to you by writing messages to a
disk file called the ``\Indx{message file}'' and/or by sending them to
you on the appropriate ``message monitor.''  Simple instructions and
progress messages usually go only to the monitor; very few (if any)
messages go only to the file.  For {\tt AIPS} itself, the
\indx{message monitor} is always the workstation window or terminal
into which you are typing your commands.  For the tasks, the monitor
can also be a separate terminal (on well-equipped, but old, systems)
or a second workstation window under control of the \AIPS\ d\ae mon
process \hbox{{\tt MSGSRV}}.  You can control whether or not you get
the message server window by the setting of a Unix environment
variable ({\tt AIPS\_MSG\_EMULATOR}).  Enter
\btd
\dispt{HELP \qs \tndx{MSGSRV} \CR}{for details.}
\etd
\dispe{At most \AIPS\ installations, you get a message server by
default.  You may also control the size and appearance of the message
server with parameters in the X-Windows {\tt \tndx{.Xdefaults}} file.
These parameters are also listed in by {\us HELP \qs MSGSRV
\hbox{\CR}}.  If the message server window has quit, you can restart it
with the verb {\tt \tndx{STARTTV}}\@.}

     You may review the contents of the message file by typing {\us
\tndx{PRTMSG} \CR} at the {\tt >} prompt at your terminal.  {\tt
PRTMSG} is an example of an \AIPS\ ``verb'' --- it does not need a
{\us GO} from you to execute, and it is {\it not\/} shed from your
terminal.  Each message in the file has, associated with the text, the
time, task name, \POPS\ number, and the priority of the message.  The
priority codes range from 0 for user input to 2 for ``unimportant''
messages to 5 for ``answers'' and  other significant normal messages
to 8 for serious error messages.  The {\tt PRTMSG} verb has adverbs to
let you select either the printer or your window or terminal for the
display and to let you control which messages will be displayed.  For
example, to set the minimum priority level for messages to be
displayed, type:
\btd
\dispt{PRIORITY \qs {\it np\/} \CR}{where {\it np\/} is the desired
                                 minimum level,}
\etd
\dispe{before running {\tt PRTMSG}; then only messages at this level or
above will be listed on the printer or terminal.  If {\it np\/} is
$\leq$ 5, then messages at level 0 are also shown.  {\tt PRTMSG} has
further adverbs to limit the output by program name ({\tt PRTASK},
uses minimum match), message age ({\tt PRTIME} as upper limit to the
age), and \AIPS\ number \hbox{({\tt PRNUM})}.  Note that {\tt PRNUM}
must be your \AIPS, \ie\ \POPS, session number, not your user
identification number.  The choice of the output device is made with}
\btd
\dispt{\tndx{DOCRT} \qs -1 \CR}{to select the line printer or a text
                 file under control of {\tt OUTPRINT}.}
\dispt{DOCRT \qs 1 \CR}{to select the terminal at its current width
                 $\ge 72$ characters}
\dispt{DOCRT \qs {\it nc\/} \CR}{to select the terminal at width {\it
                 nc\/} characters: $72 \le nc \le 132$.}
\etd
\dispe{The wider you can make your window display, up to 132
characters, the more information \AIPS\ can put on a line.  You may
change the line printer selection with {\tt \tndx{PRINTER}}\@.  If the
line printer is selected ({\tt DOCRT=-1; OUTPRINT=''}), {\tt PRTMSG}
will ask for permission to proceed if more than 400 lines will be
printed.}

     {\tt PRTMSG} does not delete messages from your message file.
Use:
\btd
\dispt{\tndx{CLRMSG} \CR}{to delete messages and to compress the
         message file.}
\etd
\dispe{{\tt CLRMSG} supports adverbs like those of {\tt PRTMSG},
except that the deletion is of messages older than {\tt PRTIME} and
the printing is of messages younger than {\tt PRTIME} seconds ago.
Old messages are automatically deleted from your message file when you
{\tt EXIT} (or {\tt KLEENEX})from \hbox{{\tt AIPS}}.  (The time limit
for ``old'' messages is set by your local \AIPS\ Manager.  Usually, it
is about 5 days.)}

\vfill\eject
\Sects{Your \AIPS\ data catalog files}{catalog}

     Your \uv\ data sets and images are your largest inputs to, and
outputs from, \hbox{\AIPS}.  A summary record of all your disk data
sets (\uv\ data, images, beams and temporary ``scratch'' data created
by active tasks) is kept in your disk \indx{catalog file}s (one per
disk).  To interrogate this catalog file, use:
\btd
\dispt{INDI \qs 0 ; \tndx{MCAT} \CR}{to list all images on all disks,
              or}
\dispt{INDI \qs 0 ; \tndx{UCAT} \CR}{to list all \uv\ data sets on all
              disks, or}
\dispt{\tndx{SCAT} \CR}{to list all scratch files on all disks.}
\etd
\dispe{{\tt MCAT} and {\tt UCAT} list files based on the {\tt INDISK}
adverb, {\tt SCAT} always lists all disks.  {\tt \tndx{M2CAT}} and
{\tt \tndx{U2CAT}} list files based on the {\tt IN2DISK} adverb.
{\tt \tndx{M3CAT}}, {\tt \tndx{U3CAT}}, {\tt \tndx{M4CAT}},
{\tt \tndx{U4CAT}}, {\tt \tndx{OCAT}}, and {\tt \tndx{UOCAT}} are
similar for the {\tt IN3DISK}, {\tt IN4DISK}, and {\tt OUTDISK} adverbs,
respectively.}

A complete listing of the catalog file, which may be printed
with {\tt PRTMSG}, can be generated by:
\btd
\dispt{\tndx{CLRNAME} \CR}{to reset {\tt INNAME}, {\tt INCLASS}, {\tt
              INSEQ}, {\tt INTYPE}, and {\tt INDISK},}
\dispt{\tndx{CATALOG} \CR}{to generate the listing.}
\etd
\dispe{which will list all of your disk data sets.  To limit the
listing to a particular name, class, sequence number, type, and/or
disk, use a combination of the adverbs {\tt INNAME}, {\tt INCLASS},
{\tt INSEQ}, {\tt INTYPE}, and \hbox{{\tt INDISK}}.  Verbs
{\tt \tndx{CAT2LOG}}, {\tt \tndx{CAT3LOG}},  {\tt \tndx{CAT4LOG}},
{\tt \tndx{CAT5LOG}}, and  {\tt \tndx{CATOLOG}} are similar but use
the matching set of input or output name adverbs.  The {\tt INNAME}
and {\tt INCLASS} type adverbs allow a rather powerful wild-card
grammar; type {\us HELP \qs INNAME \CR} for details.  Unless you want a
hard copy, it is faster to use {\tt MCAT} and {\tt UCAT}, although they
respond only to the {\tt INDISK} adverb.  A typical listing looks like:}
\bve
CATALOG ON DISK  1
CAT USID MAPNAME      CLASS   SEQ  PT     LAST ACCESS      STAT
 18   76 3C166L5OK   .IIM001.    1 MA 27-OCT-1996 22:30:18
 19   76 3C166L5OK   .IBM001.    1 MA 27-OCT-1996 23:02:14
 22   76 3C166L5OK   .IIM001.    2 MA 28-OCT-1996 15:30:45
CATALOG ON DISK  2
CAT USID MAPNAME      CLASS   SEQ  PT     LAST ACCESS      STAT
 22   76 1200+519    .IIM001.    1 MA 01-NOV-1996 23:50:10
 23   76 1200+519    .IBM001.    1 MA 01-NOV-1996 23:59:58
 24   76 1200+519    .QIM001.    1 MA 28-OCT-1996 00:10:10
 25   76 1200+519    .UIM001.    1 MA 28-OCT-1996 00:19:19
 28   76 1200+519    .ICL001.    1 MA 02-NOV-1996 00:35:20 WRIT
 31   76 SCRATCH FILE.IMAGR1.    1 SC 02-NOV-1996 00:35:37 WRIT
 32   76 SCRATCH FILE.IMAGR1.    2 SC 02-NOV-1996 00:35:39 WRIT
CATALOG ON DISK  3
CAT USID MAPNAME      CLASS   SEQ  PT     LAST ACCESS      STAT
  2   76 3C138 A C   .UVSRT .    1 UV 22-OCT-1996 12:56:50
 36   76 1200+519    .UVXY  .    1 UV 02-NOV-1996 00:32:50 READ
 37   76 1200+519    .IMAGR .    1 UV 02-NOV-1996 00:34:25 WRIT
\end{verbatim}\eve
\dispe{This user (identification number 76) has eight image files,
three on disk 1 and six on disk 2.  He also has two sorted \uv\ data
sets and an {\tt IMAGR} \uv\ work file on disk 3.  There are two
scratch (temporary) files on disk 2 which were created by {\tt IMAGR}
running out of {\tt AIPS1} (this determines their {\tt IMAGR1}
classname).  Image data files (images and beams) are distinguished by
the type code \hbox{{\tt MA}}.  The \uv\ data files are distinguished
by the type code {\tt UV} and scratch files by type \hbox{{\tt SC}}.}

     Note that this user has encoded useful information other than the
source name into the image file names on disk 1.  These images were of
3C166 at L band with 50 kilo-wavelength (\uv) taper.  Such information
is also carried in \AIPS\ history files (see \Sec{history} below), but
it is often useful to place it at a level where {\tt CAT} can see it.
The user also gave the {\tt UVSRT} file in slot 2 on disk 3 a name
that encodes the source name (3C138), the VLA configuration (A), and
the observing band (C). Careful choice of \AIPS\ file names can save
much other bookkeeping.  The file name can be any valid string up to
12 characters long. Also note how {\tt SEQ} numbers distinguish
different versions of a file with the same name; this and the global
variables in \AIPS\ are helpful features when doing iterative
computations such as self-calibration.

\Subsections{Speedy data file selection}{getname}

     Each catalog entry has an identification number called the
``catalog slot number''.  The {\tt CAT} column at the left of the
listing above shows these catalog numbers.  They can be used to set up
inputs quickly for \AIPS\ programs that read cataloged disk data sets.
Use:
\btd
\dispt{INDI \qs{\it n1\/} ; GETN \qs {\it ctn1\/} \CR}{where {\it
            n1\/} selects the disk and {\it ctn1\/} is the catalog
            slot number.}
\etd
\dispe{The verb {\tt \tndx{GETNAME}} (abbreviated through minimum
           match as {\tt GETN} above) sets the adverbs {\tt
\tndx{INNAME}}, {\tt \tndx{INCLASS}}, {\tt \tndx{INSEQ}}, and {\tt
\tndx{INTYPE}} used by many tasks and verbs.  Some tasks require a
second, a third and even a fourth set of input image name adverbs.
For these, use:}
\btd
\dispt{IN2D \qs{\it n2\/} ; \tndx{GET2N} \qs {\it ctn2\/} \CR}{to set
             the second set, and}
\dispt{IN3D \qs{\it n3\/} ; \tndx{GET3N} \qs {\it ctn3\/} \CR}{to set
             the third set.}
\dispt{IN4D \qs{\it n4\/} ; \tndx{GET4N} \qs {\it ctn4\/} \CR}{to set
             the fourth set.}
\etd
\dispe{The verb {\tt \tndx{GETONAME}} ({\tt GETO} for minimum match)
sets the adverbs {\tt \tndx{OUTNAME}}, {\tt \tndx{OUTCLASS}} and {\tt
\tndx{OUTSEQ}} to those of a pre-existing output file.  {\tt GETO} is
particularly useful with calibration tasks that copy extension tables
(\eg\ {\tt CL} or {\tt FG} tables) from one database to another or for
restarting an image deconvolution.}

\subsections{Catalog entry status}

      Note that several catalog slots on disks 2 and 3 in our sample
catalog listing above do not have blank entries in the {\tt STAT}
column.  This listing was made while the user was running a Clean
deconvolution with {\tt IMAGR} on the sorted \uv\ data set in slot 36
--- this \uv\ data file is opened for {\tt READ}ing.  The Clean image
file, {\tt ICL001} in slot 28, and the scratch and {\tt IMAGR} files
are opened for {\tt WRIT}ing.  Procedures that attempt to read files
which are opened for writing, or vice versa, will be rejected with
appropriate error messages.  You must therefore note any non-blank
entries in the {\tt STAT} column carefully.  In some situations
(mainly involving system crashes or abortion of tasks [\Sec{tasks}])
files may be left in {\tt READ} or {\tt WRIT} \indx{status}
indefinitely.  If this happens, you may reset the file status with
{\us \tndx{CLRSTAT} \CR} after issuing the appropriate {\us INDISK}
and \hbox{{\us GETNAME}}.  Note that a {\tt WRIT} status on a file
which is not, in fact, being used at present probably indicates that
the data in the file have been corrupted.  Such files should usually
be removed from your catalog by first clearing the file status with
{\us GETN {\it nn\/}; CLRST \CR} then deleting them with {\us
\tndx{ZAP} \CR}\@.

     Before using a data set as input to an \AIPS\ task, check that
the data set has a clear status.  (It is possible to let two tasks
read the same data at the same time, but this is not recommended as it
will usually slow execution.) Also note the data set's disk number and
its ordinal number in the catalog, as these are useful for {\tt GETN},
{\tt GET2N}, etc.

\Subsections{Renaming data files}{rename}

      Files may be renamed, after they have been cataloged, using
the \AIPS\ verb \hbox{{\tt \tndx{RENAME}}}.  Typical inputs might be:
\btd
\dispt{INDI \qs 2 ; INNA \qs '1200+519' \CR}{to select disk 2 and set
                     the input (old) name.}
\dispt{INCL \qs 'IIM001' ; INSEQ \qs 1 \CR}{to set the rest of the
                     input name adverbs, \ie\ to select the file in
                     slot 22 on disk 2 in the example above.}
\dispt{OUTN \qs '1200+51 15K' ; OUTSEQ \qs 2 \CR}{to set desired
                     output name and sequence number.}
\dispt{INP \qs RENAME \CR}{to review the inputs.}
\dispt{RENAME \CR}{to rename the {\tt I} image to '1200+51 15K' and
                     reset its sequence number to 2.}
\etd

     Two verbs can be used to alter the catalog numbers of files.
{\tt \tndx{RENUMBER}} moves a file to an empty, user-specified slot; a
one-line command to do this would be {\us SLOT {\it n\/}; RENUM \CR}
where {\it n\/} is the new slot number.  Note that {\it n\/} may now
be higher than any slot numbers currently in use.  {\tt \tndx{RECAT}}
compresses the catalog (\ie\ it removes gaps in the catalog numbers)
without changing the order of the entries in the catalog.

\Subsections{Header listings}{header}

     Every image or \uv\ data set in \AIPS\ has an associated header
file that contains information needed to describe the data set in
detail.

     The header also contains information on the number of
\indx{extension files} of each type that have been associated with the
data set.  The most important file extensions that can be associated
with \AIPS\ image data are the {\tt HI}story file described below, the
{\tt CC} or Clean component files (see \Rchap{image}) and the {\tt
PL}ot files and {\tt SL}ice files (see \Rchap{plot}).

     Multi-source \uv\ data files may have many extensions (see
\Rchap{cal}).  The most important are the {\tt HI}story file, the {\tt
AN}tennas file (subarray geometric data, date, frequency and
polarization information, {\it etc.\/}), the {\tt BP} (bandpass) file
for bandpass calibration data, the {\tt CL} (calibration) file for
calibration and model information, the {\tt FQ} (frequency) file for
frequency offsets of the different IFs, the {\tt FG} (flag) file for
editing information, the {\tt NX} (index) file (which assists rapid
access to the data), the {\tt SN} (solution) file for gain solutions
from \AIPS\ calibration routines, and the {\tt SU} (source) file with
source-specific information such as name, position, and velocity.
\Rchap{cal} describes the use of these extensions in some detail.

     You can list the header file of any catalog entry on your
terminal by following the {\us GETNAME} step above with\
\btd
\dispt{\tndx{IMHEAD} \CR}{for a detailed listing, or}
\dispt{\tndx{QHEADER} \CR}{for a shorter listing.}
\etd
\dispe{The output of {\tt IMHEAD} and {\tt QHEADER} can also be
printed using {\us PRTMSG} (at {\us PRIORITY \qs 2}).}

%\vfill\eject
     Output from {\tt IMHEAD} on a multi-source \uv\ data set might
look like:
\bve
Image=3C345     (UV)         Filename=Z17G1_A     .MULTI .   1
Telescope=SBLNKGYO           Receiver=VLBI
Observer=FAP                 User #= 1353
Observ. date=27-FEB-1991     Map date=13-JUN-1995
# visibilities    112813     Sort order  TB
Rand axes: UU-L  VV-L  WW-L  BASELINE  TIME1  WEIGHT  SCALE
           SOURCE
--------------------------------------------------------------
Type    Pixels   Coord value  at Pixel    Coord incr   Rotat
COMPLEX      1   1.0000000E+00    1.00 1.0000000E+00    0.00
STOKES       4  -1.0000000E+00    1.00-1.0000000E+00    0.00
FREQ       128   2.2228990E+10   63.50 5.0000000E+05    0.00
RA           1    16 41 17.608    1.00      3600.000    0.00
DEC          1    39 54 10.820    1.00      3600.000    0.00
--------------------------------------------------------------
Maximum version number of extension files of type SU is   1
Maximum version number of extension files of type CL is   3
Maximum version number of extension files of type HI is   1
Maximum version number of extension files of type AN is   1
Maximum version number of extension files of type NX is   1
Maximum version number of extension files of type FG is   1
Maximum version number of extension files of type SN is   1
\end{verbatim}\eve

    Output from {\tt \tndx{IMHEAD}} on an image file might look like:
\bve
Image=3C219     (MA)         Filename=3C219-BC-6  .ICL001.   1
Telescope=VLA                Receiver=
Observer=BRID                User #=   76
Observ. date=06-SEP-1992     Map date=18-APR-1994
Minimum=-1.89720898E-04      Maximum= 5.05501366E-02 JY/BEAM
--------------------------------------------------------------
Type    Pixels   Coord value  at Pixel    Coord incr   Rotat
RA---SIN   510    09 17 50.662  263.00     -0.300000    0.00
DEC--SIN   640    45 51 43.555  294.00      0.300000    0.00
FREQ         1   4.8726000E+09    1.00 2.5000000E+07    0.00
STOKES       1   1.0000000E+00    1.00 1.0000000E+00    0.00
--------------------------------------------------------------
Map type=NORMAL              Number of iterations=   50000
Conv size=   1.40 X   1.40   Position angle=   0.00
Observed RA   09 17 50.600    DEC  45 51 44.00
Maximum version number of extension files of type HI is   1
Maximum version number of extension files of type PL is   5
Maximum version number of extension files of type SL is   1
\end{verbatim}\eve

     Both {\tt QHEADER} and {\tt IMHEAD} list the maximum version
numbers of the table extension files associated with a data set.
Because you may acquire many versions of such tables during
calibration, these verbs are often invoked during calibration in
\hbox{\AIPS}.  Verbs {\tt \tndx{IM2HEAD}}. {\tt \tndx{IM3HEAD}},
{\tt \tndx{IM4HEAD}}, and {\tt \tndx{IMOHEAD}}, as well as
{\tt \tndx{Q2HEADER}}, {\tt \tndx{Q3HEADER}}, {\tt \tndx{Q4HEADER}}, and
{\tt \tndx{QOHEADER}} appeared to make comparable  listings for the
second, third, and fourth input and the output file naming adverb
groups, respectively.

\Sects{Your \AIPS\ history files}{history}

     Every \uv\ and image file has an associated ``history'', or {\tt
HI}, file.  This {\tt HI} ``extension'' of the data set stores
important information about the processing done so far on the data in
the file.  Every \AIPS\ task and verb that alters either the data or
the file header will record its key parameters in the \indx{history
file}.  The history file is written to the disk file when you use FITS
format, so you can preserve it for reference in later \AIPS\ sessions or
when sending data to colleagues.

     In general, each ``card'' in the history file begins with the
task or verb name.  It then gives one or more of the input adverb
values it used (\ie\ the defaults are filled in).  All or parts of the
file may be displayed on your terminal or printed on the line printer.
For example, use:
\btd
\dispt{INDISK \qs {\it n} ; GETN \qs {\it ctn} \CR}{to select the file
                  to be displayed.}
\dispt{PRTASK \qs 'IMAGR' \CR}{to examine only history information
                  from {\tt IMAGR}.}
\dispt{DOCRT \qs 1 \CR}{to direct the display to your terminal, using
                  its full width.}
\dispt{\tndx{PRTHI} \CR}{to print the {\tt IMAGR} history.}
\dispt{KEYSTRNG\qs 'robust'; PRTHI \CR}{to display only {\tt IMAGR}
                  history lines containing the string {\tt ROBUST}.}
\dispt{PRTASK \qs ' \qs' ; DOCRT \qs FALSE \CR}{to select all history
                  cards and direct the output to the line printer.}
\dispt{PRTHI \CR}{to print the full history file.}
\etd

     There are several (legitimate) reasons why you might wish to edit
your history files.  Repetitive self-calibration cycles, or image
combinations, can lead to very long and very repetitive histories
which could be substantially shortened with no real loss of
information.  Also some entries in the history file may become
obsolete by, say, the deletion of plot files.  The verb {\tt
\tndx{STALIN}} allows you to send a range of history lines to Siberian
salt mines (\ie\ delete) by number with optional selection by task and,
optionally, interactive confirmation of each deletion.  You may, of
course, simply wish to add information to the history file.  The verb
{\tt \tndx{HINOTE}} can be used to append one line, given by the
adverb {\tt COMMENT}, or many lines, typed in interactively, to the
history file.  Even more powerfully, the verb {\tt \tndx{HITEXT}}
allows you to write your history file to an external text file (see
\Sec{textfile}).  You may edit that file with your favorite Unix file
editor and then read it back, writing your edited file into any \AIPS\
history file you want (with verb \hbox{{\tt HINOTE}}).

\Sects{Saving and restoring inputs}{inputs}

     All input and output parameters (``adverbs'') are global
throughout {\tt AIPS}\@.  When an adverb value is specified for, or
set by, a task or verb, it remains at that value for any other task or
verb that uses an adverb of the same name (until you change it).  This
global nature of the \AIPS\ adverbs is useful in most cases.  It can,
however, be inconvenient --- especially if you are taken by surprise
because you have not reviewed the adverb values before running a task.
Before running any task or verb, check your current input adverbs
carefully with:
\btd
\dispt{INP \qs {\it name\/} \CR}{where {\it name\/} is the program
            name, or}
\dispt{\tndx{INPUTS} \qs {\it name\/} \CR}{to write the input values
            to the message file.}
\dispt{\tndx{QINP} \CR}{to resume the previous {\tt INP} or {\tt
            INPUTS} with the page last displayed.}
\etd
\dispe{Some tasks have multiple pages of input parameters.  {\tt QINP}
allows you to change a parameter on a page, review that page and then
go on to the next page without having to view the first pages over
again.  Some verbs and a few tasks have {\it output} adverbs.  Unless
they are also used on input, they will not appear when you do {\tt INP}
or {\tt INPUTS}\@.  After running such verbs and tasks, do}
\btd
\dispt{\tndx{OUTPUTS} \qs {\it name\/} \CR}{to view the output values
            and write them to the message file.}
\etd

     To reset all adverbs for a particular task or verb to their
initial values, without changing any other adverbs or procedures,
enter
\btd
\dispt{\tndx{DEFAULT} \qs {\it name\/} \CR}{to reset the values for
            {\it name}.}
\dispt{DEFAULT \CR}{to reset the values for the verb or task named in
            the {\tt TASK} adverb.}
\etd


      You can save all adverbs you have specified for \AIPS\ to disk
at any time by typing:
\btd
\dispt{\tndx{SAVE} {\it aaaaa\/} \CR}{where {\it aaaaa\/} is any
             string of up to 12 characters.}
\dispt{\tndx{GET} {\it aaaaa\/} \CR}{will restore these inputs later.}
\etd
\dispe{These commands save or restore your entire {\tt AIPS}
``environment''.  For this reason, {\tt GET} must be the only command
on the input line; {\tt SAVE} may appear with other commands, but will
be executed before {\it any\/} of the other commands on the line.  Thus,
the sequence {\us INNAME \qs '3C123' \CR\qs INNAME \qs 'BLLAC' ; SAVE
\qs BLLAC \CR} will save a 3C123 environment, not a BLLAC one. {\tt
AIPS} automatically saves your environment in a disk area called {\tt
\tndx{LASTEXIT}} whenever you use the {\tt EXIT}, {\tt KLEENEX}, or
{\tt RESTART} commands.  The command {\tt GET LASTEXIT} is
automatically executed whenever you start up the {\tt AIPS} program
again on the same machine.  Thus, you retain your own \AIPS\
environment from one use of {\tt AIPS} to the next.  To obtain a null
version of the adverb values and of the rest of the \AIPS\
environment, type:}
\btd
\dispt{\tndx{RESTORE} \qs 0 \CR}{}
\etd
\dispe{There is also one temporary area for saving your {\tt AIPS}
environment. To save your inputs temporarily, type:}
\btd
\dispt{\tndx{STORE} \qs 1 \CR}{to save your inputs in area 1, and}
\dispt{RESTORE \qs 1 \CR}{to recover the inputs you previously stored
                     in area 1.}
\etd
\dispe{When new verbs and adverbs are created at your site, your old
{\tt SAVE} files will not know about them.  Beginning with the {\tt
15JAN96} release, you may update the old files with the sequence:}
\btd
\dispt{GET {\it aaaaa\/} \CR}{to recover the old {\tt SAVE} area.}
\dispt{COMPRESS \CR}{to get the new basic vocabularies without losing
            your adverb values and procedures.}
\dispt{SAVE {\it aaaaa\/} \CR}{to save the updated area for later; use
            the full name of the {\tt SAVE} area here.}
\etd
\dispe{The list of {\tt SAVE} areas may be reviewed with the verb {\tt
SGINDEX}\@.  A {\tt SAVE} area may be written as a {\tt RUN} file
(\Sec{run}) if you first {\tt GET} the area and then use {\tt
\tndx{SG2RUN}}\@.}

     The input adverb values associated with a task or a verb can be
stored by the command:
\btd
\dispt{\tndx{TPUT} {\it name\/} \CR}{where {\it name\/} is the verb,
                    task, or procedure name.}
\etd
\dispe{and retrieved by the command:}
\btd
\dispt{\tndx{TGET} {\it name\/} \CR}{ }
\etd
\dispe{{\tt TPUT} and {\tt TGET} allow you to avoid, to some extent,
the global nature of the adverb values in \hbox{{\tt AIPS}}.  This is
sometimes advantageous.  Whenever a task (or a verb, for that matter)
is executed by the verb {\tt GO}, {\tt TPUT} runs automatically.  {\tt
TGET} will therefore recover the last set of input adverbs used to
execute the task, unless you deliberately overwrite them with a {\tt
TPUT} of your own.  Note that \AIPS\ will complain if you try to {\tt
TGET} input adverbs for a task for which no {\tt TPUT} has previously
been run (either manually or automatically).  You must ``put'' before
you can ``get.''  {\tt \Tndx{TGINDEX}} will show you what tasks have
been {\tt TPUT} and when.  {\tt \Tndx{VPUT}}, {\tt\Tndx{VGET}}, and
{\tt \Tndx{VGINDEX}} allow you to save, recover, and list
task-specific adverbs from up to 35 completely user-controlled storage
areas.  All {\tt TGET} and {\tt VGET} files have a new format which
includes adverb names.  Then, when the adverbs to a task or verb change,
{\tt TGET} and {\tt VGET} will still work.  In {\tt 31DEC23}, the
command {\tt \Tndx{TUGET}} will do a {\tt TGET} but from a different
user number.  This may be convenient when the user uses multiple user
numbers on his/her computer.  In {\tt 31DEC24}, {\tt TUGET} was enhanced
to read not only from the current user's \AIPS\ disk 1, but also from
another disk which was {\tt USERID}'s disk 1.  New verbs {\tt \tndx{
TGUINDEX}} and {\tt \tndx{SGUINDEX}} were written to list those tasks
and {\tt SAVE}/{\tt GET} files, respectively, available from another
user number and disk.  New verb {\tt \tndx{SGUGET}} allows you to {\tt
GET} a saved \POPS\ environment from another user number and disk.}

{\tt \tndx{PLGET}} lets you recover the adverbs used to construct a
user-selected plot file.  As of {\tt 31DEC23}, these are known by name.
Older plot files depend on the list of adverbs having not changed.
Check the {\tt INPUTS} carefully after a {\tt PLGET}\@.

You can change between versions of \AIPS\ software once you are inside
{\tt AIPS}\ by typing
\btd
\dispt{\tndx{VERSION} '{\it version\/}' \CR}{where {\it version\/} is
           one of {\tt OLD}, {\tt NEW} or {\tt TST}}
\etd
\dispe{Alternatively, you may use this command to access a private
version of a program in some other area --- see \Sec{moreGO}.  Note
that toggling between different versions of \AIPS\ is possible only
when the data formats are the same.  Unfortunately, recent versions
are not fully compatible with previous versions of \hbox{\AIPS}.  (The
antenna file format changed in 2009, the internal $UV$ format changed
in 2015.)  Note also, that you are toggling between different versions
of tasks, not the verbs within the {\tt AIPS} program.  That version
is selected when you start the program (\Sec{stAIPS}) and can be
changed only by exiting and start anew.}

\Sects{Monitoring disk space}{diskspace}

Since the {\tt 15APR92} release of \AIPS, the availability of data
areas via NFS has vastly increased the amount of \indx{disk space}
accessible from a given \AIPS\ session.  The {\tt da=} command line
option to the {\tt aips} command allows you to specify ``disks'' (data
areas) from many hosts in addition to the current host, subject to a
maximum of 35 disks per session.  Note, however, that the {\tt
\tndx{BADDISK}} adverb has a limit of 10 disks.  Thus, if more than 10
disks are accessed via NFS, you will not be able to prevent one or
more from being used for scratch files.  This can be important.
Reading data over NFS is relatively efficient, but writing data is
not.  Even file creations (under Unix) require the writing of zeros to
the whole file in order to guarantee later access to the requested
space.  Over NFS, this can be a slow process.  For example, if user
disk 1 is accessed via NFS, then every line of the message file must
be written with \indx{NFS}, a process which has been observed to
require about one second of real time per message!

Another aspect of the new disk allocation system is a scheme by which
the local \AIPS\ Manager may restrict the availability of some disk
areas to a set of user numbers, specified on a disk-by-disk basis.
Managers usually use this tool to set aside most disks on a staff
member's workstation for his/her sole use and to reserve space for
visitors or other special projects on ``public'' workstations on a
case-by-case basis.  Use the {\tt \tndx{FREESPAC}} verb within {\tt
AIPS} to show you the space used and available on all disks for your
session and also to show whether or not that space is reserved.  The
right-most column of {\tt FREESPAC}'s output will show {\tt Alluser} if
the space is not reserved, {\tt Resrved} if you are one of the users
for which the space is reserved, {\tt Not you} if you are not allowed
to use the space, and {\tt Scratch} if the space is to be used only
for scratch files.  Use {\tt FREESPAC} often to keep track of how much
space is available and where the space can be found.

     Disk space is still generally at a premium.  If more than one
user has access to the disk areas you are using, or you use more than
one user number to separate projects, then another useful
tool for monitoring disks is the \AIPS\ task called \hbox{{\tt
\tndx{DISKU}}}.  To run it, type
\btd
\dispt{USER \qs 32000 ; INDISK \qs 0 \CR}{to get all disks and users.}
\dispt{BADDISK\qs 0 \CR}{to allow all disks; can be used to skip chosen
      disk numbers in {\tt 31DEC23}\@.}
\dispt{DOALL\qs 0 ; GO \qs DISKU \CR}{to run the \AIPS\ disk user task.}
\etd
\dispe{This will (eventually) list on the {\tt AIPS} monitor (and the
message file) the amount of data space in use by each user for all
\AIPS\ disks.  Identify the worst disk hogs and apply appropriate peer
pressure.  If you are, mysteriously, the culprit on some disk, then}
\btd
\dispt{USER \qs 0 ; INDISK \qs{\it n\/} \CR}{where {\it n\/} is the
              mysteriously eaten disk}
\dispt{DOALL \qs $m$ ; GO\qs DISKU \CR}{to run the job, listing all
              catalog entries requiring more than $m$ Megabytes.}
\etd
\dispe{will give you the size of your larger files on the specified
disk.  Armed with this information, you may be able to take
appropriate action upon your own data.}

     Sometimes the available disk space has been eaten up by \AIPS\
scratch files that are no longer in use.  Tasks that abort while
executing (and other mysterious events) may produce this situation.  To
delete all your scratch files, except those for tasks which are still
running, type:
\btd
\dispt{\tndx{SPY} \CR}{to see which tasks are running.}
\dispt{SCRD \CR}{to delete the files.}
\etd
\dispe{{\tt \tndx{SCRDEST}} is run automatically whenever {\tt EXIT},
{\tt KLEENEX}, {\tt RESTART}, or {\tt ABORT} {\it task\_name\/} are
executed.  Note that the imaging and deconvolution tasks {\tt IMAGR},
{\tt APCLN}, and {\tt VTESS}, the data editor {\tt TVFLG}, the sorter
{\tt UVSRT} and other tasks may create large scratch and ``work''
files, so you should watch for ``dead'' copies of scratch and work
files from these programs in your disk catalog.  Both {\tt MCAT} and
{\tt UCAT} will show scratch files as well as the requested file type,
but {\tt \tndx{SCAT}} will be easier to use.  Note too that, if you
are using more than one computer on a given disk area, only those
scratch files created by your current computer will be deleted when
you run the {\tt SCRD} verb.  Work files have to be deleted
individually since they can be still of use after the task which
created them has finished.}

     \Rchap{exit} of this \Cookbook\ tells you how to backup or delete
your own data to relieve disk crowding.  At present, all other methods
for managing disk space involve system-dependent commands of one sort
or another.  Since these may have unexpected consequences they are not
recommended.
%To use these methods:
%\btd
%\dispt{\tndx{EXIT} \CR}{to exit from {\tt AIPS}, saving your {\tt
%            AIPS} inputs in the {\tt LASTEXIT} area.}
%\etd
%\dispe{Then consult with your local \AIPS\ Manager.  Normal users
%should not employ system methods of disk-space creation without being
%fully apprised of the possible consequences.}

%\vfill\eject
\sects{Moving and compressing files}

     Two \AIPS\ tasks are frequently used to move files from one disk
to another with options to reduce the file size.  They are {\tt
\tndx{SUBIM}}, used on images, and {\tt \tndx{UVCOP}}, used on \uv\
data sets.  {\tt SUBIM} uses the adverbs {\tt BLC} and {\tt TRC} to
select a portion of the input image and {\tt XINC} and {\tt YINC} to
select a pixel increment through the portion.  If these adverbs are
defaulted (set to 0), the entire image is copied.  Clean component,
history, and other table extension files are copied as well, but plot
and slice extensions are not.  Similarly, {\tt UVCOP} uses a wide
range of adverbs to select which IFs, channels, frequency IDs, times,
antennas, and sources are to be copied.  If all of these adverbs are
defaulted (set to 0 or blank), then all data are copied except
(optionally) for completely flagged records.  A flag table may also be
applied to the data. including flag tables too large to be handled by
most tasks.  With extensive data editing, {\tt UVCOP} may produce a
rather smaller data set even with no other selection criteria.
Antenna, gain, and other table extension files are copied, but plot
files are not.  The task {\tt \tndx{MOVE}} may be used to copy all
files associated with a catalog number (without modification) to
another disk or to another user number.

\Sects{Finding helpful information in \AIPS}{help}

     Much \AIPS\ documentation can be displayed on your terminal by
typing {\us \tndx{HELP} {\it word\/} \CR}, where {\it word\/} is the
name of an \AIPS\ verb, task or adverb.  The information given will
supplement that given in the {\tt INPUTS} for a verb or task.  It is
the only source of information on the adverbs.  Type  {\us
\tndx{XHELP} {\it word\/} \CR} to display the help file in your WWW
browser with links to adverbs from task help files.

     To print the {\tt HELP} information on your line printer, set
{\tt DOCRT = -1} and enter {\us \Tndx{EXPLAIN} {\it word\/} \CR}
instead.  (Using {\tt DOCRT = 1} with {\tt EXPLAIN} will send the
output to your terminal screen.)  For the more important verbs and
tasks, {\tt EXPLAIN} will print extra information, not shown by {\tt
HELP} about the use of the program, with detailed explanations, hints,
cautions and examples.

     {\tt HELP} may also be used to list the names of all \POPS\
symbols known to {\tt AIPS} by category, an operation helpful when you
can't remember the name of something.  Type:
\btd
\dispt{\tndx{HELP ADVERBS}\CR}{to get a list of all adverbs in the
             symbol table}
\dispt{\tndx{HELP ARRAYS}\CR}{to get a list of all array adverbs in
             the symbol table}
\dispt{\tndx{HELP REALS}\CR}{to get a list of all real adverbs in the
             symbol table}
\dispt{\tndx{HELP STRINGS}\CR}{to get a list of all character string
             adverbs in the symbol table}
\dispt{\tndx{HELP VERBS}\CR}{to get a list of all verbs, pseudo-verbs,
             and procedures in the symbol table}
\dispt{\tndx{HELP PSEUDOS}\CR}{to get a list of all pseudo verbs in
             the symbol table}
\dispt{\tndx{HELP PROCS}\CR}{to get a list of all procedures in the
             symbol table}
\etd

     In the past, \AIPS\ contained a range of general {\tt HELP} files
which purported to list all verbs and tasks in various categories.
Since these were maintained by hand, they were essentially never
current and complete.  That entire system has been replaced by the
verbs {\tt ABOUT} and {\tt APROPOS} to be discussed below.  A few
general help files do remain, and they may even be relatively current.
A list of these may be found by typing:
\btd
\dispt{HELP\qs HELP\CR}{for help on {\tt HELP}.}
\etd
\dispe{A few general help files remain.  They are {\tt POPSYM}
(symbols used in \POPS\ interpretive language ), {\tt NEWTASK}
(writing and incorporating a new task into \AIPS), and {\tt PANIC}
(solutions to common problems).}

     The {\tt HELP} verb is very useful, but only if you know that the
function you want exists in \AIPS\ and know its name.  Two functions
have appeared in {\tt AIPS} to assist you in this search.  The first
of these, {\tt \tndx{APROPOS}}, searches all of the one-line summaries
and keywords of all \AIPS\ help files for matches to one or more
user-specified words.  For example, type
\btd
\dispt{APROPOS \qs CLEAN \CR}{to display all keyword and 1-line
              summaries of help files containing words beginning with
              ``clean'' (in upper and/or lower case), and}
\dispt{APROPOS \qs 'UV PLOT' \CR}{note the quote marks which are
              required if there are embedded blanks, or}
\dispt{APROPOS \qs UV,PLOT \CR}{to display all keyword and 1-line
              summaries of help files containing {\it both\/} words
              beginning with ``uv'' and words beginning with
             ``plot.''}
\etd
\dispe{The text files used by {\tt APROPOS} are maintained by the
\AIPS\ source code maintenance (check-out) system itself.  As a
result, they should always be current.  Of course, the quality of the
results depends on the quality of the programmer-typed one-line and
keyword descriptions in the help files.  These were not regarded
as important previously and hence are of variable quality.}

     The second new method for finding things in \AIPS\ is the verb
\hbox{{\tt \tndx{ABOUT}}}.  Type
\btd
\dispt{ABOUT \qs {\it keyword\/} \CR}{to see a list of all \AIPS\
              tasks, verbs, adverbs, etc.~which mention {\it keyword\/}
              as one of their ``keywords.''}
\etd
\dispe{You need only type as many letters of {\it keyword\/} as are
needed for a unique match.  The source-code maintenance system is used
to force all help files to use only a limited list of primary and
secondary keywords.  Software tools to update the list files have also
been written, and are used at least once with every \AIPS\ release.
The list of categories recognized is as follows (where only the
upper-case letters shown in the name are actually used):}
\bve
  ADVERB        POPS symbol holding real or character data
  ANALYSIS      Image processing, analysis, combination
  AP            Tasks using the "array processor"
  ASTROMETry    Accurate position and baseline measurements
  BATCH         Running AIPS tasks in AIPS batch queues
  CALIBRATion   Calibration of interferometer uv data
  CATALOG       Dealing with the AIPS catalog file
  COORDINAtes   Handling image coordinates, conversions
  EDITING       Editing tables, uv and image data.
  EXT-APPL      Access to extension files (tables)
  FITS          FITS format for data interchange
  GENERAL       General AIPS utilities
  HARDCOPY      Creating listings and displays on paper
  IMAGE-UTil    Utilities for handling images
  IMAGE         Transforming of images
  IMAGING       Creation of images: FFT, Clean, ...
  INFORMATion   General lists and user help functions
  INTERACTive   Functions requiring user interaction
  MODELING      Model fitting to uv or image data
  OBSOLETE      Functions slated for removal
  ONED          Functions for one-dimensional image slices
  OOP           Tasks coded with object oriented principles
  OPTICAL       Functions of interest for optical astronomy data
  PARAFORM      Skeleton tasks for use in building new tasks
  PLOT          Displays of image and uv data
  POLARIZAtion  Calibration, analysis, display of polarization
  POPS          Aspects of the AIPS' user language POPS
  PROCEDURe     Creation of and available procedures
  PSEUDOVErb    Pseudo-verbs in the POPS language and AIPS
  RUN           Creation of and available RUN files
  SINGLEDIsh    Functions of interest for single-disk radio data
  SPECTRAL      Functions for spectra-line and other 3D data
  TABLE         AIPS table extension files
  TAPE          Use of magnetic tapes (obsolete)
  TASK          AIPS tasks - available asynchronous functions
  TV-APPL       Tasks using the TV display
  TV            Basic functions on the TV display
  UTILITY       Basic functions on tables, uv and image data
  UV            Functions dealing with interferometer uv data
  VERB          Synchronous functions inside the AIPS program
  VLA           Functions of particular interest for the VLA
  VLBI          Functions of particular interest for very long
                baseline data.
\end{verbatim}\eve
A variety of synonyms are also recognized.  Besides those that are
merely spelling variants, the currently accepted synonyms are
\todx{ABOUT}
\bve
  FILES       ->  CATALOG           POSITION   ->  COORDINATES
  FLAGGING    ->  EDITING           EXTENSION  ->  EXT-APPL
  PRINTING    ->  HARDCOPY          PRINTER    ->  HARDCOPY
  MAP         ->  IMAGE             MAP-UTIL   ->  IMAGE-UTIL
  MAPPING     ->  IMAGING           LANGUAGE   ->  POPS
  CUBE        ->  SPECTRAL          LINE       ->  SPECTRAL
  VISIBILITY  ->  UV                VLBA       ->  VLBI
  PARAMETERS  ->  ADVERB            HELPS      ->  INFORMATION
  SLICE       ->  ONED
\end{verbatim}\eve

More detailed descriptions of new developments in \AIPS\ can be found
in the \Aipsletter\ published by the NRAO every six months and tied to
each \AIPS\ software release.  It is available from the web site
{\tt https://www.aips.nrao.edu/} and is included with \AIPS\
distributions.  An \AIPS\ Memo series is published by the NRAO with
details of various aspects of the implementation of, and planning for,
\hbox{\AIPS}.  Advanced users may also wish to receive,
and contribute to, the \AIPS\ electronic mail forum --- \hbox{{\tt
BANANAS}}.  There is also an electronic news group called {\tt
alt.sci.astro.aips} devoted to \AIPS\ matters.  This \AIPS\ \Cookbook,
many of the \AIPS\ Memos, and various other publications of the \AIPS\
group are available via anonymous {\tt ftp} (at {\tt
ftp.aoc.nrao.edu}) and via the Internet and the ``\indx{World-Wide
Web}'' starting with ``\indx{URL}'' (Universal Resource Location) {\tt
https://www.aips.nrao.edu/}).

     Your local \AIPS\ Manager probably receives the \Aipsletter,
\iodx{Aipsletter} \AIPS\ Memos, and {\tt BANANAS} and can make
information from them available at your site.  He/she should also be
aware of the electronic means of information retrieval, and be able to
help you use them.  If this is not the case, write to the \AIPS\ Group
(at NRAO, P. O. Box O, Socorro, NM 87801-0387) or send electronic mail
to {\bf daip@nrao.edu} for further information about these services.

\vfill\eject
\Sects{Magnetic tapes}{magtape}

    Large volumes of data were once brought into, and taken away
from, \AIPS\ using \indx{magnetic tape}.  Disk files are now much more
frequently used; see \Sec{externfile}.  Tape usage in \AIPS\ is
described here, in case you still have need of it, but the
descriptions of tapes elsewhere in this \Cookbook\ have been greatly
reduced.  The \indx{tape} drives assigned to you are displayed as you
start up {\tt AIPS}, \eg\
\disps{{\tt Tape assignments: }}
\disps{{\tt Tape 1 is IBM 9-track model 9348-012 on LEMUR}}
\disps{{\tt Tape 2 is HP 9-track model 88780B on LEMUR}}
\disps{{\tt Tape 3 is IBM 7208/001 Exabyte 8200 (external) on LEMUR}}
\disps{{\tt Tape 4 is ZZYZX 1.3Gb DAT (left, Model\# ZW/HT1420T-CC6)
             on LEMUR}}
\disps{{\tt Tape 5 is ZZYZX 1.3Gb DAT (right; both 150mb personality)
             on LEMUR}}
\disps{{\tt Tape 6 is IBM Exabyte 8200 (internal) on LEMUR}}
\disps{{\tt Tape 7 is REMOTE}}
\disps{{\tt Tape 8 is REMOTE}}
\dispe{for the heavily loaded, and now obsolete, IBM called {\tt
lemur}.  The tape numbers you see above correspond to {\tt AIPS}
adverb {\tt  INTAPE} values of 1, 2, 3, and so on.  The description is
meant to give you some idea of which box or slot is to receive your
tape.  Most of the drives will have a label on them identifying their
\AIPS\ tape number.  If in doubt, ask a local guru for help.  The last
two tape ``drives,'' called {\tt REMOTE}, will be discussed separately
below.}

In case you forget this list, the verb {\tt \tndx{TAPES}} will show
it to you.  {\tt TAPES} is even capable of going out on the Internet
and asking what devices are available to an \AIPS\ user at the
computer specified by the {\tt REMHOST} adverb (if it is running {\tt
\tndx{TPMON}})!  Note however that instances of {\tt TPMON} are no
longer started automatically when {\tt AIPS} is started.

\subsections{Hardware tape mount}

     On some \AIPS\ systems, tapes are handled by designated operators.
Before mounting tapes, read \Rappen{sys} (for NRAO sites) or obtain
directions from your local \AIPS\ Manager or operators for methods by
which tapes are to be handled.  Most \AIPS\ systems, however, are on
the self-service plan.  In that case, the simplest thing to do is to
find a drive of the required type without a tape in it.  There is no
way in most Unix systems (certainly not in Linux or Mac OS/X) of
reserving a tape drive globally for your exclusive use, though once
you have it {\tt \tndx{MOUNT}}ed from within {\tt AIPS}, no other {\tt
AIPS} user can access it.  It is most efficient to use a tape drive
directly connected to your computer (and hence listed as you started
up \hbox{{\tt AIPS}}).  However, any ``AIPSable'' drive will do.
Mount the tape physically on the drive following the mounting
instructions in \Rappen{sys} or those posted at your installation for
the particular kind of tape drive.  For half-inch (nine-track) tapes,
don't forget to insert a write ring if you intend to write on the tape
or to remove any write ring if you intend only to read the tape.
Exabyte and DAT tapes have a small slide in the edge of the tape which
faces out which takes the place of the write ring of 9-track tapes.
For 8mm (Exabyte) tapes push the slide to the right (color black
shows) for writing and to the left (red or white shows) for reading.
With 4mm DAT tapes, the slide also goes to the right for writing (but
white or red shows) and to the left for reading (black shows).  Note
the identification number {\it m\/} marked on the drive you are using,
as you will need to provide that number to the software for mounting
and dismounting the tape and for executing \AIPS\ tasks which read or
write tape.

\subsections{Software mounting local tapes}

      {\it After\/} you have the tape physically mounted on the tape
drive, \AIPS\ must also be told that you have done this and which tape
drive you have chosen.  This step is called a ``software tape mount.''
It is necessary to wait until the mechanism in the drive has ``settled
down'', \ie\ when the noises and flashing lights have stopped, before
you can do the software mount.  This operation is done from inside
{\tt AIPS} by typing:
\btd
\dispt{INTAPE \qs {\it m\/} \CR}{to specify the drive labeled {\it
              m\/}.}
\dispt{DENSITY \qs {\it dddd\/} \CR}{to set the density to {\it
              dddd\/} bpi if needed.}
\dispt{\tndx{MOUNT} \CR}{to mount the tape in software.}
\etd
\dispe{Read any messages which appear on your terminal carefully since
they report the success, failure, and/or limitations of the
operation.  The meaning of ``density'' with modern magnetic tape
devices is mostly a matter of convention.  With half-inch, 9-track
tapes, \AIPS\ understands the usual 800, 1600, and 6250 bytes per inch
densities.  A special value for density, 22500, is taken to mean high
density (5-Gbyte) mode on 8mm (Exabyte) tapes.  You must set the {\tt
DENSITY} adverb to one of these magic values, but in many cases it
does not matter which one you use.}

Please dismount the tape as soon as you are finished with it, using:
\btd
\dispt{INTAPE \qs {\it n\/} ; DISMO \CR}{to dismount a tape from
            the drive labeled {\it n\/}.}
\etd
\dispe{The dismount \todx{DISMOUNT} verb should cause the tape to be
rewound and, in most cases, ejected from the drive.  Please remove the
tape from the tape drive promptly so that others may use the drive.
Note that exiting {\tt AIPS} under most circumstances --- even with
{\tt CTRL C} --- will cause your mounted tapes to be dismounted
automatically.}

\subsections{Software mounting REMOTE tapes}

     \Iodx{REMOTE tapes} On all \AIPS\ systems, the last two tape
drives are indicated as \hbox{{\tt REMOTE}}.  This means you can use
two additional adverbs in {\tt AIPS} to access tape drives on other
computers.  It doesn't matter where the computer is, as long as it's
connected via \indx{Internet} and has \AIPS\ installed on it in the
conventional way.  For example, if you wanted to use \AIPS\ tape drive
2 on remote host {\tt rhesus}, you would type:
\btd
\dispt{\tndx{REMHOST} \qs 'RHESUS' ; \tndx{REMTAPE} \qs 2 \CR}{}
\dispt{DENSITY \qs {\it dddd\/} \CR}{to set the density to {\it
                dddd\/} bpi if needed.}
\dispt{INTAPE \qs {\it n\/} ; \tndx{MOUNT} \CR}{set local ``tape''
                number and software mount}
\etd
\dispe{where {\it n\/} is the number of one of the REMOTE tape
assignments in the list of tape drives you see on {\tt AIPS} startup.
If you know which computers are to provide remote tape services for
you, it is a good idea to specify them when you start {\tt AIPS} using
the {\tt tp=}{\it hostname\/} option (see \Sec{stAIPS}).  In this way,
you make certain that the \AIPS\ d\ae mon tasks {\tt \tndx{TPMON}}{\it
n\/} which provide the remote service are running where they are
needed.  Note that this option is commented out of {\tt START\_AIPS} in
{\tt 31DEC24}\@.}

\Subsections{Using tapes in \AIPS}{tapeuse}

     \AIPS\ provides a number of basic tools for managing magnetic
tapes.  It is very helpful to have a list of the contents of
\indx{magnetic tape}s you intend to read.  To list the contents
of a \indx{tape} on the line printer:
\btd
\dispt{TASK\qs 'PRTTP' ; INP \CR}{to review the inputs.}
\dispt{NFILES\qs 0 \CR}{to list all files on the tape.}
\dispt{PRTLEV\qs 0 \CR}{to list the image headers but not the details
              --- both more and less detailed listings are available.}
\dispt{DOCRT\qs FALSE \CR}{to print on the line printer.}
\dispt{GO \CR}{to run the task.}
\etd
\dispe{It is also a good idea to run {\tt \tndx{PRTTP}} on your data
tapes after you have written them, but before you have deleted the
data from disk.  {\tt PRTTP} reads the the tape record by record to
test for tape errors as well as to check the data format.}

     The {\tt AIPS} program has a number of verbs to position and
check magnetic tapes.  These include
\btd
\dispt{\tndx{REWIND} \CR}{to rewind the tape, \eg\ after running {\tt
          PRTTP}.}
\dispt{NFILES\qs {\it n\/} ; \tndx{AVFILE} \CR}{to advance the tape $n >
          0$ file marks.}
\dispt{NFILES\qs -{\it n\/} ; AVFILE \CR}{to move the tape backwards to
          the $n^{\uth}$ previous file.}
\dispt{NFILES\qs 0 ; AVFILE \CR}{to position the tape at the start of
          the current file.}
\dispt{\tndx{AVEOT} \CR}{to advance the tape to the end of
          information, usually for the purpose of adding more data at
          the end.}
\dispt{\tndx{TPHEAD} \CR}{to display the contents of the data file at
          the current tape position.}
\etd
\dispe{Users are encouraged to treat \indx{magnetic tape}s with some
caution.  The tapes themselves can have --- or develop --- errors
which render the data in the file unavailable.  Furthermore, there are
no generally accepted standards governing magnetic \indx{tape}
software in the industry.  As a consequence, each Unix operating
system handles them differently and each can change over time.  This
creates great difficulties in \AIPS\ and may cause your version not to
handle all tape devices in a fully compatible manner.}

\AIPS\ tasks are still able to handle tapes, should the need arise.
Output tapes may be written with {\tt FITTP}, {\tt FITAB}, and {\tt
TCOPY}\@.  Input tapes are read by {\tt IMLOD}, {\tt UVLOD}, {\tt
FITLD}, {\tt FILLM}, {\tt M3TAR}, {\tt MK3IN}, and {\tt MK3TX}\@.

\Sects{\AIPS\ external disk files}{externfile}

    \AIPS\ maintains a wide range of disk files for its own use
internally.  Unless you intend to write programs for \AIPS\ you need
not be concerned about their formats or, in many cases, even their
existence.  However, recent versions of \AIPS\ also support
``external'' disk files to be read from and written to disk
directories controlled by you.  You may read and write from/to binary
``\indx{FITS-disk}'' files with {\tt TPHEAD}, {\tt UVLOD}, {\tt
IMLOD}, {\tt FITLD}, {\tt FITTP}, and {\tt FITAB}\@..  {\tt AIPS} and
some tasks also allow \indx{text files} to be read or written from/to
disk.  For example, all print tasks can be instructed to append their
output to user-specified text files.  These can be examined later with
an editor or written to tape with standard tape utilities.  The two
PostScript tasks, {\tt LWPLA} and {\tt TVCPS}, can be instructed to
write their output plots in user-specified text files for later
processing and, for example, inclusion in manuscripts.  And {\tt AIPS}
itself can be instructed to take its input commands from user-created
text files.

\Subsections{Disk text files}{textfile}

     The most significant user control over external files is the
specification of the file's full name, \ie\ its directory path and its
name in that path.  You specify the directory path by creating an
environment variable (``logical name'' in \AIPS peak) {\it before\/}
starting {\tt AIPS}\@.  The simplest way is to change directory
({\tt cd} Unix utility) to the area you wish to use and enter
\btd
\dispx{{\tt \%\qs}setenv \qs MYAREA \qs `pwd` \CR}{}
\etd
\dispe{where {\it MYAREA\/} is a logical name of your choosing (but
all in {\it upper case\/}).  Note that the {\us pwd} is surrounded by
backward single quote marks.  The grammar above is for users of
c-shell and tc-shell.  Users of korn, bourne, and bash shells would
type:}
\btd
\dispx{{\tt \$\qs} MYAREA=`pwd`; export MYAREA \CR}{}
\etd
\dispe{also with backward single quote marks.  If you are going to
read a text file into \AIPS, its name must also be in upper-case
letters.  Finally, inside {\tt AIPS}, you specify the file with, \eg}
\btd
\dispt{OUTPRINT \qs = 'MYAREA:3C123.PRT' \CR}{}
\etd
\dispe{where {\tt 3C123.PRT} is any all upper-case file name of your
choosing.  Note the surrounding quote marks and the colon that
separates the logical name and the file name portions.  You may put
the file anywhere under any name you choose, but we request that you
put it an area owned by you, if you have one, or that you use an
identifying name and a standard \AIPS\ area set aside for the purpose.
Files left around in the \AIPS\ directories are subject to summary
deletion.  Be sure that \AIPS\ has the privilege to write into your
directory; use {\tt chmod} to allow appropriate write privilege on the
directory file (try to avoid world write!).  On Unix systems,
duplicate file names are not allowed and \AIPS\ tasks will usually die
when trying to write a file name that already exists.  Print tasks
will append to pre-existing files, however.  The verb {\tt
\tndx{FILEZAP}} allows you to delete external files from inside {\tt
AIPS}\@.  The name of the file to be deleted is given as an immediate
argument.}

     File names may also be entered as complete path names, so long as
they do not require more than 48 characters, the length of the adverb
data values.  Thus\\
\centerline{{\tt INTEXT = '/home/primate2/egreisen/AIPS/Text.prt}}
\dispe{Note that the trailing quote mark is left off and this is the
last command on the input line so that the case is preserved.}

     Ordinary \indx{text files} are used in \AIPS\ for a variety of
purposes. Every print task offers the option of saving the output in a
file specified by {\tt OUTPRINT} rather than immediately printing and
discarding it.  Similarly, output PostScript files from {\tt LWPLA} and
{\tt TVCPS} may be saved in files specified by {\tt OUTFILE} rather
than immediately printing and discarding them.  They may be used later
in larger displays, or even enclosed as figures in a \TeX\ document
such as this \hbox{\Cookbook}.  {\tt OUTTEXT} is used by numerous
other tasks, such as {\tt SLICE} and {\tt IMEAN}, to write output
specific to the tasks which may be of use to other programs.  \AIPS\
tables may even be written as text files by task {\tt TBOUT}, edited
by the user, and then read back in by task \hbox{{\tt TBIN}}.  History
files may be revised in a similar manner.  Adverbs {\tt INFILE}, {\tt
INTEXT}, {\tt CALIN}, and {\tt INLIST} may be used by a number of
tasks to specify source models, lists of ``star'' positions,
holography data, and the like.  Television color tables are read from
and written to disk text files specified with the {\tt OFMFILE}
adverb.

\Subsections{{\tt RUN} files}{run}

     {\tt \tndx{RUN}} files are ordinary text files containing {\tt
AIPS} commands to be executed in sequence in a batch-like manner.
They are often used to define procedures which you save in your own
area or in an \AIPS-provided public area with the logical name
\hbox{{\tt \$RUNFIL}}.  The name of the file must be all upper case
letters, followed by a period, followed by your user number as a
three-digit ``extended-hexadecimal'' number with leading zeros.  (To
translate between decimal and \indx{extended hexadecimal}, use the
\AIPS\ procedures or the {\tt AIPS} verbs called {\tt \indx{EHEX}} and
\hbox{{\tt \tndx{REHEX}}}.)  The files are edited from Unix level
using {\tt emacs}, {\tt vi}, {\tt textedit} or your other preferred
text editor. For example, log in to the {\tt aips} (or your own)
account.  From Unix level, type:
\btd
\dispx{{\tt \%}\qs cd \qs \$RUNFIL}{to change to {\tt RUN} area.}
\dispx{{\tt \%}\qs emacs \qs MAPIT.03D \CR}{ }
\etd
\dispe{to edit with {\tt emacs} a file called {\tt MAPIT} for user
121.  You may now also use any area of your choosing instead of the
public {\tt \$RUNFIL} area.  For instructions on the individual
editors, consult the appropriate Unix Manuals.  Instruction manuals
for the GNU {\tt emacs} editor are available from local computer
staff.    A {\tt SAVE} area (\Sec{inputs}) may be written as a {\tt
RUN} file if you first {\tt GET} the area and then use {\tt
\tndx{SG2RUN}}\@.}

     To use the {\tt RUN} file, define a logical name as in the
previous Section.  Then start up {\tt AIPS} under your user number and
enter
\btd
\dispt{VERSION \qs = 'MYAREA' \CR}{where {\us MYAREA} is your disk
                area, or}
\dispt{VERSION \qs = '\ \qs' \CR}{if {\tt \$RUNFIL} is to be used}
\dispt{RUN \qs {\it FILE\/} \CR}{to execute the file named {\it
                FILE.uuu\/}}
\etd
\dispe{where {\it uuu\/} is your user number if extended hexadecimal
with leading zeros to make three digits.}

\Subsections{FITS-disk files}{fitsdisk}

     \indx{FITS} is an IAU-endorsed binary format standard for
astronomical data heavily used by \AIPS\ for almost all of its data on
disk and magnetic tape.  In fact, it is the only format written by
\AIPS\ except for simple tape copying.  The basic FITS paper (by
Wells, Greisen, and Harten) appeared in {\it Astronomy \&\
Astrophysics Supplement Series\/}, Volume 44, pages 363--374, 1981.
The newsgroup {\tt sci.astro.fits} is devoted to discussion of FITS\@.
World-wide web users can access the FITS home page at
\disps{{\tt https://fits.gsfc.nasa.gov/fits\_home.html}}
\dispe{\AIPS\ also supports the FITS format written to disk in exactly
the same form as it is written to magnetic tape.  The tasks {\tt
FITTP} and {\tt FITAB} may be instructed to write their output files
on disk rather than on tape.  Likewise, {\tt TPHEAD}, {\tt FITLD},
{\tt UVLOD}, {\tt IMLOD}, and {\tt PRTTP} can read from disk.  To
write to a FITS-disk file, specify:}
\iodx{FITS-disk}
\btd
\dispt{DATAOUT \qs '{\it filename\/}'  \CR}{where {\it filename\/} is
            the name of the desired output file.}
\dispe{and to read from a FITS-disk file, you specify:}
\dispt{DATAIN \qs '{\it filename\/}' \CR}{}
\etd
\dispe{where you must specify {\it filename\/} with environment
variables (``logical names'' in \AIPS peak), \eg}
\btd
\dispt{DATAOUT \qs = 'MYDATA:3C123.FIT' \CR}{}
\etd
\dispe{in exactly the same way as described for text files in
\Sec{textfile}.  There is a standard public area, called logically
{\tt FITS}, which you may use for reading and writing FITS-disk files.
{\tt FITTP} will use this area if you do not specify a logical name.
Be aware that older files will be purged from this public area when
space is needed.  Note too that {\tt FITTP} will write only one disk
file per execution; the {\tt DOALL} option is disabled when writing to
disk.}

     There is a package of procedures to assist in writing and reading
more than one FITS-disk file at a time.  Enter {\tt RUN WRTPROCS} to
define the procedures.  The procedure {\tt \tndx{FITDISK}} will write
a single disk catalog file to a disk file using a name based on the
\AIPS\ file name parameters.  You may then construct loops invoking
{\tt FITDISK} to write multiple files.  For example:
\btd
\dispt{FOR I=1:10; GETN(I); FITDISK; END \CR}{}
\etd
\dispe{Such file names are useful for their mnemonic content, but must
be read back one at a time.  The procedure {\tt \tndx{WRTDISK}} will
dump a range of catalog numbers to disk under names that allow the
procedure {\tt \tndx{READISK}} to read them back as a group.  These
two procedures are particularly useful when moving your data between
computer architectures (\eg\ from a Solaris to a Linux computer).
Note that there is a stand-alone program {\tt \tndx{REBYTE}} which can
do the conversion directly including files of all types.}

     {\tt \tndx{FITLD}} can read multiple disk files in either the
normal FITS format (as written by {\tt FITTP}) or the special FITS
format written by the VLBA correlator.  The only requirement for this
operation is that file names end in sequential numbers beginning with
1.  {\tt FITAB} has the ability to write special FITS files with
visibility data in tables.  These files may be broken up into multiple
files, called ``pieces,'' for size and reliability considerations.
These pieces, when written to disk, have names ending in sequential
numbers.  Special code in {\tt FITLD} and {\tt UVLOD} recognize these
pieces and read the requested number of them as if they were in one
file.

     Remote FITS-disk files may be read in much the same manner as
remote magnetic tapes.  Type {\us HELP DATAIN \CR} or {\us HELP
DATAOUT \CR} for details.

     FITS-disk files are written as Fortran files and hence are
available also to user-coded programs.  The Fortran specifications for
the file are {\tt ACCESS='DIRECT', RECL=2880, FORM='UNFORMATTED'} in
the {\tt OPEN} statement for Unix systems.  Most Fortrans cannot read
or write files larger than 2 Gigabytes, so \AIPS\ now reads and writes
these files with C subroutines.  Users may also, of course, code
programs to create such files to be read by {\tt FITLD}, {\tt IMLOD}
or \hbox{{\tt UVLOD}}.  Consult {\it GOING AIPS\/}, Volume 2,
\Rchap{list} for details on how to do this.

    One of the main uses for FITS-disk files is to transfer data over
the \indx{Internet} between computers.  For example, to transfer a
file from {\tt rhesus} (in Charlottesville) to {\tt kiowa} (at the
AOC), log in to {\tt rhesus}, change to the directory in which you
wish to store the file (for example, {\us cd \$FITS \CR}), and enter:
\btd
\dispx{{\tt \%\qs} ftp kiowa \CR}{to start {\tt ftp} to the remote
                        system.}
\dispx{{\tt Name (kiowa:$\ldots$):\qs} {\it loginame\/} \CR}{to log in
                        to account {\it loginame\/}.}
\dispx{{\tt Password:\qs} {\it password\/} \CR}{to give the account's
                        password.}
\dispx{{\tt ftp>\qs} cd \qs {\it directory\/} \CR}{to change to the
                        {\it directory\/} name containing the file.}
\dispx{{\tt ftp>\qs} binary \CR}{to allow reading of a binary file.}
\dispx{{\tt ftp>\qs} hash \CR}{to get progress symbols as the copy
                        proceeds.}
\dispx{{\tt ftp>\qs} put \qs {\it filename\/} \CR}{to send the file}
\dispx{{\tt ftp>\qs} quit \CR}{to exit from {\tt ftp}.}
\etd
\dispe{The file should then be in the desired directory.  You may have
to rename it, however, to a name in all upper-case letters since that
may be required by \hbox{\AIPS}.  (See \Sec{textfile} for a trick
that allows you to use lower-case letters in file names.)  The file
format will be correct.  In general it is better to use the ftp
program to ``get'' files instead of ``put''ting them; things tend to
go faster that way.}

    An alternative to using {\tt ftp} is to use the {\tt scp} (remote
secure copy) Unix utility to write the output file directory in the
appropriate area on the other computer.  The syntax for the remote copy
is:
\btd
\displx{{\tt \%\qs} scp\qs \$FITS/MYFILE.FITS\qs
     {\it username}@kiowa:/AIPS/FITS/MYFILE \qs \CR}{}
\etd
\dispe{(this shows how you would copy it from {\tt rhesus} to {\tt
kiowa}).}

If you wish to copy a FITS-disk file from one machine to another
within a site, check if you can just use the Unix {\tt cp} command;
this is often possible if the remote disk is mounted (or can be
auto-mounted) via NFS (the Network File System).

FITS files may be compressed with standard utility programs such as
{\tt gzip}.  This does not produce much compression for files written
with full dynamic range and floating-point format.  However, {\tt
\tndx{FITAB}} offers the option of writing images (not \uv\ data)
which are quantized at some suitable level.  These are capable of
significant compression even if they are in floating-point format.

\Subsections{Other binary data disk files}{fillmdisk}

Data written by the on-line system of the VLA are now often found in
disk files rather than on tape.  These data are available from an
archive of all VLA data.  See \\
\centerline{{\tt https://data.nrao.edu/}}\\
for information on how to access your current data and all data for
which the proprietary period has expired.  {\tt \tndx{FILLM}} and {\tt
PRTTP} can read the disk files produced from the archive, including
reading more than one such file in a single execution.  In this case,
the file names must end in consecutive numbers beginning with ${\tt
NFILES}+1$\@.

\vfill\eject
\sects{The array processor}

In running numerous important tasks in \AIPS\ you will notice
references to an ``array processor.''  This used to be an expensive
device attached to computers which allowed them to run some \AIPS\
tasks 100 times faster than they would run without the device.  To
support our less fortunate colleagues, we wrote a software emulation
of the array processor which we call the \Indx{pseudo array
processor}.  This uses highly optimized routines running on data
stored in the ``AP memory.''  By now, the hardware devices are all
gone and only the software emulation remains.  We have found that this
is still a good model to obtain highly optimized software performance.

The pseudo-AP now uses dynamic memory allocated by the calling task as
needed rather than a fixed amount of memory that would be much too
large for some problems and too small for others.  The largest \AIPS\
tasks, including {\tt IMAGR} and {\tt CALIB} in self-cal mode, have
changed to use rather large amounts of memory if needed to reduce the
number of times the visibility data need to be read.  Two new verbs
appeared at this time: {\tt \Tndx{SIZEFILE}} returns the size of a
disk file and {\tt \Tndx{SETMAXAP}} sets the maximum computer memory
that may be used for the pseudo-AP\@.  The latter allows the user to
limit the AP on smaller or busier machines or to permit really large
memory usage when large amounts of memory are available.  See {\us
HELP SETMAXAP} for a discussion of the essential considerations.

The pseudo-AP has been changed to use only double precision integers and
floats.  This avoids serious overflow issues with the large number of
data samples from modern telescopes and provides much greater accuracy
especially in the gridding and Fourier transforming of visibility data.

\sects{Additional recipes}

% chapter   *************************************************
\recipe{Columbian fresh banana cake with sea foam frosting}

\bre
\Item {Open an 18.5 oz {\bf yellow cake mix} into a large mixxing
   bowl; do not use a mix that contains pudding or requires oil.
   Combine with 1/8 teaspoon {\bf baking soda}.}
\Item {Stir 3/4 cup {\bf Coca-Cola} briskly until foaming stops.
   Add to cake mix and blend until just moistened.  Then beat at high
   speed for 3 minutes, scraping the bowl often.}
\Item {Combine 2 teaspoons {\bf lemon juice} with 1 cup mashed {\bf
   bananas} and then add to batter.  Add 1/3 cup finely chopped {\bf
   nuts} and beat for 1 minute at medium speed.}
\Item {Turn the batter into a well greased, lightly floured 9x13
   baking dish. Bake in a preheated \dgg{350} oven for about 40
   minutes or until the cake tests done.   Cool on a rack for 15
   minutes, remove cake from pan and turn right side up on a rack to
   finish cooling.}
\Item {In the top of a double boiler, combine 2 large {\bf egg
   whites}, 1 1/2 cups packed {\bf light brown sugar}, 1/8 teaspoon
   {\bf cream of tartar} (or 1 tablespoon corn syrup), and 1/3 cup
   {\bf Coca-Cola}.  Beat at high speed for 1 minute with an electric
   mixer.}
\Item {Place over boiling water --- the water should not touch the
   bottom of the top half of the double boiler.  Beat on high speed
   for about 7 minutes until the frosting forms peaks when the mixer
   is raised. Remove from boiling water.  Empty into a large bowl.}
\Item {Add 1 teaspoon {\bf vanilla extract} and continue beating on
   high speed until thick  enough to spread, about 2 minutes. Spread
   on the sides and top of the cold banana cake.}
\ere

\vfill\eject

% chapter *************************************************
\recipe{Banana sweet potato puff casserole}

\bre
\Item {In a large bowl, combine 2 cups mashed {\bf sweet potatoes}, 1
     cup mashed ripe {\bf bananas} (3 medium), 3/4 teaspoon {\bf curry
     powder}, 1/3 cup {\bf sour cream}, 1/2 teaspoon {\bf salt}, and 1
     {\bf egg}.}
\Item {Beat with electric mixer until light and very fluffy. Turn into
     1 quart casserole dish.}
\Item {Bake at \dgg{350} for 20 minutes or until puffed and lightly
     browned.}
\item[ ]{\hfill Thanks to Turbana Corporation ({\tt www.turbana.com}).}
\ere

% chapter   *************************************************
\recipe{Banana poundcake}

\bre
\Item {Mix in large bowl until blended:}
\vskip 4pt
\hbox to \hsize{\hskip 75pt\baselineskip 14pt\vbox{\halign{\rt{{$#$}}\quad%
&\lft{#}\cr
1 {1\over3}&cups mashed {\bf bananas} (4 medium)\cr
1          &pkg.~($18{1\over2}$ oz.) {\bf yellow cake mix}\cr
1          &pkg.~($3{3\over4}$ oz.) instant {\bf vanilla pudding mix}\cr
1\over3    &cup {\bf salad oil}\cr
1\over2    &cup {\bf water}\cr
1\over2    &teaspoon {\bf cinnamon}\cr
1\over2    &teaspoon {\bf nutmeg}\cr
4          &{\bf eggs} at room temperature\cr}}\hfil}
\Item {Beat at medium speed for 4 minutes.}
\Item {Turn batter into greased and lightly floured 10-inch tube pan.}
\Item {Bake in \dgg{350} oven for 1 hour or until cake tester inserted
in cake comes out clean.}
\Item {Cool in pan 10 minutes, then turn out onto rack and cool
completely.}
\Item {If desired, dust with confectioners sugar before serving.}
\item[ ]{Thanks to the United Fresh Fruit and Vegetable Association.}
\ere


% chapter  *************************************************
\recipe{Banana July cocktail}

\bre
\Item {Sprinkle 3 sliced {\bf bananas} with 1 tablespoon {\bf lemon
     juice}.}
\Item {Mix with 1 1/4 cans drained and flaked {\bf tuna}, 1/2 {\bf
     onion} chopped, and 2 tablespoons chopped {\bf gherkins} or {\bf
     olives}.}
\Item {Spoon into 7 cocktail shells.}
\Item {Melt 2 tablespoons {\bf butter} in a saucepan.  Add 2
     tablespoon {\bf cake flour} and salt and pepper to taste.}
\Item {Add 1/4 cup {\bf chicken stock} and 1/4 cup dry {\bf white
     wine}.  Simmer for one minute stirring constantly.}
\Item {Add 1/3 cup grated {\bf cheddar cheese} and allow to cool.}
\Item {Add 1/4 cup fresh cream to sauce and pour over banana-tuna
     mixture.}
\Item {Sprinkle with 1 tablespoon grated {\bf cheese} and {\bf
     paprika}.  Decorate with a slice of {\bf gherkin} or {\bf
     olive}.}
\Item {Bake 15--20 minutes at \dgg{350};  serve warm.}
\item[ ]{\hfill Thanks to Turbana Corporation ({\tt www.turbana.com}).}
\ere
\eject
