%-----------------------------------------------------------------------
%;  Copyright (C) 1995, 1998, 2000-2001, 2004, 2007, 2009, 2013-2014
%;  Copyright (C) 2016, 2018, 2024-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{Exiting from, and Solving Problems in, \AIPS}{exit}

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


     This chapter contains a grab-bag of miscellaneous advice on
exiting from \AIPS\ and on solving a variety of common problems that
may arise.  The latter are also addressed in \Sec{Zproblems}.

\Sects{Helping the \Aips\ programmers}{gripe}

     Comments, suggestions and bug reports about any facet of \AIPS\
are very useful to the \AIPS\ programming and management group.  Note
that ``gripes'' are only useful when they are informative --- \eg\
giving details of the circumstances under which a task failed with
accompanying system error messages (if any).  Terse gripes along the
lines of ``{\tt UVCOP} doesn't work!'' whilst perhaps true in some
circumstances, are unlikely to arouse the \AIPS\ programmers'
enthusiasm.  In many cases, it may be necessary for the programmer to
use your data to fix the bug.  A FITS-disk file read over the net is a
common means to this end.  The \AIPS\ group may often seem
unresponsive to your gripe.  This is an unavoidable consequence of the
breadth of the \AIPS\ project combined with the small size of the
group.  Nonetheless, if you do not tell the programmers that there is
a problem or a good idea, then you are almost certain to encounter the
same problem years later and never to see your good idea put into
practice.  The \AIPS\ group depends on help from users.

     Gripes can be entered into a site-wide ``{\tt GR}'' file and
automatically mailed to {\tt daip@nrao.edu} by typing:
\dispt{\tndx{GRIPE} \CR}{ }
\dispe{while in {\tt AIPS}.  Follow the directions to record your
comment.    Current gripes in the file may be read via}
\dispt{\tndx{GRINDEX} \CR}{to display an index of all gripes in the
    file.}
\dispt{JOBNUM\qs{\it n\/} ; \tndx{GRLIST} \CR}{to list the $n^{\uth}$
    gripe in the file.}
\dispe{and a gripe may be deleted with}
\dispt{JOBNUM\qs{\it n\/} ; \tndx{GRDROP} \CR}{to delete the
    $n^{\uth}$ gripe in the file and notify {\tt daip}.}
\dispe{Note that the deleted gripe has already been e-mailed to the
\AIPS\ group in Socorro, so dropped ones get sent too.  Do not do a
{\tt GRDROP} unless you realize that the gripe was erroneous.  (An
explanatory ``gripe'' would be appreciated.) If you change your mind
about a gripe before you finish it, type {\tt \_forget} or {\tt
\_FORGET} (case sensitive!) to stop the gripe before it is mailed and
entered in the file.  The addition of automatic e-mail gives immediacy
to all gripes and provides, for the first time, real access to the
gripe system for sites outside of the \hbox{NRAO}.}

\sects{Exiting from \AIPS}

     Before ending a period of data reduction with \AIPS, you should
back up those data files which you wish to keep, delete all of your
disk data files, tidy up your work area, and then issue the {\tt
\tndx{KLEENEX}} (to stop the TV, Tek, and message servers too) or {\tt
EXIT} (to leave the servers running) command to the {\tt AIPS}
program.  Of course, if the computer and disks are part of your very
own workstation in your office, you may ignore all this advice.  Backups
on magnetic tape used to be a good idea, but there are few if any such
devices now available.  Disk files are easily deleted due to software or
user malfunction, or lost due to disk hardware malfunction.

Note that, when you exit {\tt AIPS} you leave behind some nearly
invisible files even if you have attempted to remove al of your data
files.  The ``hidden'' files are in your \AIPS\ data area number one and
include message ({\tt MS}), readline ({\tt RL}), {\tt SAVE}/{\tt GET}
({\tt TG}), and task data ({\tt TD}) files.  In {\tt 31DEC23}, task {\tt
\Tndx{CLNUP}} will list these files as well as data files older than a
specified interval and will delete old ``hidden'' files.  Old data files
must be deleted using {\tt ZAP} or {\tt ALLDEST}\@.

\Subsections{Backups}{fittp}

     While processing and particularly just before exiting from \AIPS,
please \indx{delete} as many of your own data sets as
possible.\Iodx{Backups}  Images and \uv\ data may be backed up on disk
in FITS format using the task \hbox{{\tt \tndx{FITTP}}}.  This task can
write only one disk file at a time; tapes were more cooperative.  For
example, to backup a \uv\ file, type
\dispt{TASK\qs 'FITTP' ; INP \CR}{to review the inputs.}
\dispt{DOALL\qs FALSE \CR}{to specify that only one file is written.}
\dispt{IND {\it n\/} ; GETN {\it ctn\/} \CR}{where {\it n\/} and {\it
          ctn\/} select the disk and catalog numbers of the data set
          to be deleted.}
\dispt{DATAOUT\qs 'FITS:Mydata.fits \CR}{Output file name; note the lack
          of a close quote to maintain case.}
\dispt{DOPLOT\qs 1 \CR}{to include any plot and slice files in {\tt
          31DEC25}.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to write the disk file.}
\dispe{The FITS format used for plot and slice files will not be useful
to any software other than \AIPS, but it does allow saving the plot
files for later use in \AIPS\@.  The {\tt RUN} file {\tt WRTPROCS}
contains two procedures to assist in writing more than one \AIPS\ data
set or image to disk.  {\tt \tndx{FITDISK}} generates the full {\tt
DATAOUT} from an input {\tt DATAOUT} and the \AIPS\ file name.
{\tt \tndx{WRTDISK}} generates the full {\tt DATAOUT} from an input {\tt
DATAOUT} and the \AIPS\ disk and catalog numbers.  These procedures and
{\tt FITAB} support the plot file option.}

Task {\tt \tndx{FITAB}} also writes FITS disk files.  For \uv\ data it
has the advantage of being able to write the data in compressed form,
saving disk space, and of writing the data in multiple ``pieces'' for
increased reliability.  Unfortunately, the table form of data used may
not be understood by other software systems.  Note that {\tt FITAB} is
used for processed $uv$ data by the NRAO archive --- it will matter to
many users to update to a modern release.  {\tt FITAB} may apply a
quantization to images on output that allow the FITS files to be
compressed very much more efficiently.  If the quantization level is
set below 1/4 of the image noise, then the noise in the output image
will only be 1--2\%\ larger than in the input image.

\subsections{Deleting your data}

     Please \indx{delete} redundant images and data as soon as
possible to preserve disk space for yourself and other users.  It is
tempting to work on many sets of data at the same time, but this
generally takes a lot of disk space and users should limit the amount
of data resident on disk to that which will be processed during the
session.  A data set and all extension files can be deleted by:
\dispt{IND {\it n\/} ; GETN {\it ctn\/} \CR}{where {\it n\/} and {\it
          ctn\/} select the disk and catalog numbers of the data set
          to be deleted.}
\dispt{\tndx{ZAP} \CR}{to do the deletion.}
\dispe{To delete data in contiguous slots from {\it n\/} to {\it m\/}
in a catalog, set the {\us INDISK} and use the loop:}
\displ{FOR I = {\it n\/} TO\qs{\it m\/} ; GETN\qs I ; ZAP ; END
           \CR}{}
\dispe{For massive deletions --- the kind we hope you will use when
you leave an NRAO site --- use:}
\dispt{\tndx{ALLDEST} \CR}{to destroy all data files consistent with
       the inputs to {\tt ALLDEST}.}
\dispe{And to compress your message file, after using {\tt PRTMSG} to
print any you want to keep, use:}
\dispt{PRNUM\qs -1 ; PRTASK\qs ' ' ; PRTIME\qs 0 \CR}{to do all
                   messages.}
\dispt{\tndx{CLRMSG} \CR}{to do the clear and compress.}
\dispe{DO NOT DELETE OTHER USERS' DATA OR MESSAGES WITHOUT THE
EXPLICIT PERMISSION EITHER OF THE OTHER USER OR OF THE AIPS
MANAGER.}

\subsections{Exiting}

     To exit from {\tt AIPS} type:
\dispt{\tndx{EXIT} \CR}{to leave TV, message, and graphics servers
     running, or }
\dispt{\tndx{KLEENEX} \CR}{to kill server processes as well as {\tt AIPS}.}
\dispe{Please clean up any papers, tapes, etc. in the area around your
terminal before you go.}

\sects{Solving problems in using \AIPS}

     On all computer systems things go wrong due to user error, program
error, or hardware failure.  Unfortunately, \AIPS\ is not immune to
this.  The section below reviews several general problem areas and
their generalized solutions.  Refer to \Sec{Zproblems} for the details
appropriate to NRAO's computer systems.  Some well-known possibilities
follow.

\subsections{``Terminal'' problems}

     If your workstation window is alive, but {\tt AIPS} has
``disappeared'' you may have ``suspended'' it by typing {\tt
\hbox{\tndx{CTRL Z}}}.  The {\tt AIPS} can be
left in a suspended state, placed into the ``background'' with {\tt
bg}, or returned to the ``foreground'' again with {\tt fg} after which
it will resume accepting terminal input.  If your \AIPS\ appears to be
``suspended'', try typing {\tt jobs} to see which jobs are attached to
your window and then use {\tt fg \%{{\it n\/}}} to bring back job {\it
n\/} where {\it n\/} is the job number of the suspended {\tt AIPS}\@.
If no \AIPS\ job is suspended from the current window, check all other
windows you have running on the workstation for the missing simian
before starting a new {\tt AIPS}\@.  Otherwise, you may run out of
allowed {\tt AIPS}es and/or encounter mysterious file locking
problems.

     If your workstation window (or terminal on obsolete systems) is
``dead'', \ie\ refuses to show signs of talking to your computer, you
have a problem. There are numerous possible causes.  If typed
characters are shown on the screen, but not executed, then
\xben
\Item Are you executing a long verb, \eg\ {\tt REWIND}, {\tt AVFILE},
      {\tt RESCALE}?  If so, be patient.
\Item Are you executing some interactive TV or Tek verb which is
      waiting for input from the cursor or buttons?  If so, provide
      the input.
\Item Have you started a task with {\tt \tndx{DOWAIT}} set to
      {\tt TRUE} ($+1.0$)?  If so, wait for the task to finish.  Most
      tasks report their progress on the message monitor window (or
      your input window).
\Item Is {\tt AIPS} waiting while a tape rewinds or skips files
      or is it waiting to open some disk file currently being used by
      one of your tasks?  Be patient.
\xeen
\vfill\eject
\noindent If typed characters do not appear, then
\xben
\Item Have you stopped output to your window accidentally by
      hitting the appropriate {\tt NO SCRL} or other XOFF control
      sequence?  If so, hit the XON control sequence. (These are {\tt
      \tndx{CTRL S}} and {\tt \tndx{CTRL Q}}, respectively.)
\Item Do other windows connected to the computer appear to be
      ``alive''?  If so, use one of them and inquire about the status
      of your {\tt AIPS} program and tasks; on Linux and Berkeley Unix
      try {\us ps\qs aux \CR} and on Linux, Solaris and other Bell
      Unix try {\us ps -elf \hbox{\CR}}.  It might be necessary to
      stop your old {\tt AIPS} session from your new window and then
      use that window to start a new {\tt AIPS}\@.
\Item Can you abort {\tt AIPS} at your window using the appropriate
      system commands (\ie\ {\tt \tndx{CTRL C}} on Unix machines)?
\Item If all windows appear dead, then your computer or its
      X-Windows server may have ``crashed.''  Try a remote login from
      another computer.  If that works, check on your processes and
      try to kill the server and other tasks.  This should return your
      computer to a login state.  Otherwise, report the problem to
      your \AIPS\ Manager or System Administrator.  If you feel you
      must reboot the system, do so {\it only\/} after checking that
      all current users and the System Administrator (if available)
      agree that that action is required.
\Item If even a reboot fails, report the problem to the System
      Administrator or hardware experts and go do something else.
      UNDER NO CIRCUMSTANCES SHOULD YOU ATTEMPT TO REPAIR ANY
      HARDWARE DEVICES. Such repairs must be performed by trained
      personnel.
\xeen

\subsections{Disk data problems}

     If you encounter the message {\tt CATOPN: ACCESS DENIED TO DISK
{\it n\/} FOR USER {\it mmm\/}}, it means that user {\it mmm\/} has
not been given access to write (or read) on limited-access disk {\it
n\/}.  The access rights for all disks can be checked by typing {\tt
\tndx{FREESPAC}} in the {\tt AIPS} session.  In the list of mounted
disks, the {\tt Access} column can say {\tt Alluser}, {\tt Scratch}
(scratch files only), {\tt Resrved} (limited access including you),
and {\tt Not you} (limited access not including you).  If you feel
that you should have access to that particular disk, resume using
your correct user number or see your \AIPS\ Manager about enabling
your user number.

     If your data set seems to have disappeared, consider
\xben
\Item Have you set {\tt INDISK} {\it et al.} (especially {\tt
       INTYPE}) correctly before running {\tt CAT}\@?  Type {\us
       INP\qs CAT \CR} to check.  Is {\tt USERID} not set to 0 or your
       user number?
\Item Are you connected to the right \AIPS\ computer, if your
       site has more than one?\iodx{catalog file}
\Item Are the desired disks mounted for your {\tt AIPS} session?
       Type {\us FREE \CR} to see which disks are currently running
       and which numbers they are assigned in this session.  When you
       attach disks from other computers (using the {\tt da=} option
       of the {\tt aips} command --- \Sec{stAIPS}), they are assigned
       numbers which depend on the list of computers and which may
       thus vary from session to session.
\Item Did you leave your file untouched for a ``long'' time on a
       public disk?  System managers may have had to delete ``old''
       files to make room for new ones.  In this case your data are
       gone and we hope you made a backup FITS file on disk.
\xeen

     The message {\tt write failed, file system is full} will appear
when the search for scratch space encounters a disk or disks without
enough space.  (\AIPS\ usually emits messages at this time as well.)
This is only a problem when none of the disks available for scratch
files has enough space, at which point the task will ''die of
unnatural causes.''  Run the verb {\tt \tndx{FREESPAC}} to see how
much disk is available and then review the inputs to the task to make
sure that {\tt OUTDISK} and {\tt BADDISK} are set properly.  Change
them to include disks with space.  Check the other adverbs to make
sure that you have not requested something silly, such as a
2000-channel cube 8096 on a side.  Then try again.

     If there simply is not enough space, try some of the things
suggested in \Sec{diskspace}, such as {\tt \tndx{SCRDEST}} to delete
orphan scratch files, {\tt \tndx{DISKU}} to find the disk hogs, and,
if all else fails, {\tt \tndx{ZAP}} to delete some of your own files.
{\tt DISKU} may be run with {\tt DOALL = $n$} to list catalog entries
that occupy more than $n$ Megabytes.  This will help identify those
files which will yield the most new space when deleted.  Your \AIPS\
Manager may help you by removing non-\AIPS\ files from the \AIPS\ data
disks.  Do not do this yourself unless they are your files.

\subsections{Printer problems}

     All \AIPS\ print operations now function by writing the output to
a disk text file, then queuing the file to a printer, and then
sometime later, deleting the file.  After the job is queued, the
\AIPS\ task or verb will display information about the state of the
queue.  Read this carefully to be sure that the operation was
successful and to find out the job number assigned to your print out.
If you are concerned that your print job may be lengthy, or expect
that you will only need a few numbers from the job, please consider
using the {\tt DOCRT} option to look at the display on your terminal
or the {\tt OUTPRINT} option to send the display to a file of your
choosing without the automatic printing.  See \Sec{Zprint} for
information about printing such files later.

     To find out what jobs are in the spooling queue for the relevant
\indx{printer}, type, at the monitor level:
\dispx{{\tt \$\qs} lpq\qs -P{\it ppp\/} \CR}{to show printer {\it
            ppp\/}.}
\dispx{{\tt \$\qs} lpstat\qs {\it ppp\/} \CR}{to show printer {\it
            ppp\/} under Solaris, HP, SGI (Sys V systems).}
\dispe{where {\it ppp\/} is the name of the printer assigned to you
when you began {\tt AIPS}\@.  If the file is still in the queue as job
number {\it nn\/}, you can type simply}
\dispx{{\tt \$\qs} \tndx{lprm} -P{\it ppp\/} {\it nn\/} \CR}{to remove
            the job.}
\dispx{{\tt \$\qs} cancel {\it nn\/} \CR}{to remove the job under
            Sys V systems.}
\dispe{{\tt lprm} and {\tt cancel} will announce the names of any files
that they remove and are silent if there are no jobs in the queue which
match the request.}

     Since modern printers are capable of swallowing large amounts of
input, your job may still be printing even though it is no longer
visible in the queue.  If you turn off the printer at this stage, you
are likely to kill the remainder of your print job and quite possibly
one or more other print jobs that followed yours.  Use discretion.
Do not turn the printer back on if the job is still in the queue.
Most systems will start the print job over again after you turn the
power back on without doing a {\tt lprm} or {\tt cancel}.

     If your printout fails to appear
\xben
\Item Did the print queuing actually work?  Review the
     messages at the end of the verb or task.
\Item Did the printout go to a printer other than the one you
     expected?  Was it diverted to a printer used for especially
     long print jobs or one used for color plots?  The messages at the
     end of the verb or task should show this.
\Item Was the printer not working or backed up for so long that
     the file was deleted before it could be printed?  The delay time
     for deletion is shown at the end of the verb or task.  It can be
     changed by your \AIPS\ Manager for future jobs.
\Item Was your print job, or that of a user in the queue ahead of
     you, a large plot?  These can take a long time in some PostScript
     printers (usually indicated by a blinking green light), so be
     patient.
\xeen

\subsections{Tape problems}

    The main problem with tapes these days is that no one has any tape
devices.  The following applies if you are one of the ``lucky'' few.

     When {\tt AIPS} does a software {\tt MOUNT} of a \indx{magnetic
tape}, it actually reads the device on most systems.  An error
message along the lines of {\tt ZMOUN2: Couldn't open tape device
$\ldots$} usually means that you have attempted the {\tt MOUNT} before
the device was ready.  Wait for all whirring noises and blinking
lights to subside and try again.  Remote tape mounts are more fragile.
If you get a message such as {\tt ZVTPO2 connect (INET): Connection
refused}, then the tape d\ae mon {\tt TPMON} is probably not running
on the remote host.  {\tt EXIT} and restart {\tt AIPS}, specifying the
remote host in the {\tt tp=} option (see \Sec{stAIPS}).  If you are
told {\tt AMOUNT: TAPE IS ALREADY MOUNTED BY \tndx{TPMON}}, then there
is a chance that you are trying to mount the wrong tape or that
someone left the tape device in a mounted state.  See \Sec{Zdisk} for
advice on curing this stand-off between {\tt AIPS}, which knows that
the tape is not mounted, and {\tt TPMON} which knows that it is.

     If you are having problems reading and writing a tape, consider
\xben
\Item Did you actually mount the tape in software from the \AIPS\
      level with the {\tt \tndx{MOUNT}} verb.  A message like {\tt
      ZTPOPN: NO SUCH LOGICAL DEVICE = AMT0{\it n\/}:} indicates that
      you have not.
\Item Have you specified the {\tt INTAPE} or {\tt OUTTAPE} number
      to correspond with the drive you mounted the tape on?
\Item Does your computer have access to tapes on the remote host?
      The message {\tt AIPS TAPE PERMISSION DENIED ON REMOTE HOST}
      suggests not.  See the \AIPS\ Manager for the remote host.
\Item Is the \indx{tape} correctly loaded in the drive and is
      the drive ``on line'' (check the {\tt ON LINE} light)?
      \iodx{magnetic tape}
\Item Have you set the density correctly?  Some drives need the
      density to be set by a switch, others have software control.
      Some try to read the tape and sense the density automatically.
      Be aware that some drives do not set the density until you
      actually read or write the tape.  Under these circumstances, the
      density indication on the drive can be misleading.  If in doubt,
      consult your local \AIPS\ Manager about the meaning of the tape
      density indicator lights on the drive you are using.
\Item Are you using the correct program to read the tape?  If you are
      unsure of the format of a tape, use the task {\tt PRTTP} to
      diagnose it for you.  It will recognize any format that \AIPS\ is
      able to read.
\Item Are you writing to a completely blank tape?  This fails
      sometimes.  Or are you writing to an old tape which is new to
      you?  In both cases, try specifying {\us DOEOT\qs FALSE \CR} and
      then rerunning the tape-writing program.
\Item Has the drive been cleaned recently?  Do {\it not\/} attempt to
      clean a drive yourself.  Using the wrong cleaning fluid or
      cleaning the wrong parts of a drive can do serious damage.  If
      you have any doubts, use another drive.
\Item Is your tape defective?  Tapes can lose oxide or become
      stretched, creased, or dirty, all of which will cause problems.
      Try using another tape, if possible.
\xeen
