%-----------------------------------------------------------------------
%;  Copyright (C) 1995, 1997-1998, 2000-2001, 2003-2005, 2008-2011,
%;  Copyright (C) 2013-2014, 2016-2018, 2022-2024
%;  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{Starting Up \AIPS}{start}

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


     This chapter contains general information concerning the steps
needed to obtain access to, and use, an \AIPS\ system.  It attempts
(as does the design and coding of \AIPS\ itself) to avoid specific
references to particular computer devices and to the peculiarities of
any one \AIPS\ installation.  We will assume, for the most part, that
you will be running \AIPS\ on a Unix workstation although \AIPS\
should still work in more classical environments.  Even for
workstations of the ``same'' operating system, some
installation-specific practicalities remain.  For the NRAO
installations, these are described in \Rappen{sys}.

\sects{Obtaining access to an \AIPS\ computer}

     Most \AIPS\ sites now possess a number of computers which are
networked together and are each individually capable of running \AIPS\
while sharing both disk resources.  Most such computers
cannot support more than a few simultaneous users (or simultaneous
incarnations of the same user) of \AIPS\@.  Thus, most locations
are obliged to institute a mechanism for distributing the available
\AIPS\ time to the people desiring it.  At NRAO, some of the computers
are assigned to individual staff members and are normally used only by
them.  Other computers, including all of the most powerful ones, are
for ``public'' use, but are mostly still on an assigned basis.  You
should arrange to have a workstation assigned to you for your \AIPS\
processing.  A few of the computers are available on a first-come,
first-served basis, and are often used remotely.  There may be sign-up
sheets and rules for their use posted in or near the principal
``\AIPS\ Caige'' (user-terminal room).  To promote fair and efficient
use of the system, there are often restrictions on the amounts of time
that any one user or user group may reserve.

     \AIPS\ can support several simultaneous users which it calls {\tt
AIPS1}, {\tt AIPS2}, {\it etc.}  In the workstation environment, this
is used primarily to allow one user to have separate simultaneous
\AIPS\ sessions using multiple windows.  This also allows users to
log in to remote computers (\eg\ with the Unix tool {\tt slogin}) and
run \AIPS\ while remaining comfortably ensconced in their offices in
front of their own (presumably lesser) workstations.  You should not
do this, of course, without permission.

\sects{Using the workstation}

     The way that a \indx{workstation} behaves is a function of the
type of workstation, the computer operating system, the window manager
program, and the set-up files for the specific computer account being
used.  Given all these variables, it is hard to give detailed usage
instructions.  Nonetheless, it is important for beginning users to
master the foibles of the workstation(s) they will be using.

\subsections{Logging in to the workstation}

    Find your assigned computer in the appropriate \AIPS\ caige or
office, or an available one intended for general use (checking any
sign-up sheets for it).  Typing \CR\ on the keyboard will reveal the
current state of the workstation.  If you see a message prompting you
to \indx{log in} (\eg\ {\tt AOC RedHat Linux, [monkey] login} on a
Socorro Linux workstation named monkey), then the computer is ready for
you to log on.  Type the account name you are supposed to use for
\AIPS\ followed by a \CR\ (use {\tt Tab} in forms) and then type the
password (it will not be visible on the screen) followed by another
\CR\@.  See your \AIPS\ Manager for the account to use and its
password (which should change with time).  Many sites will assign an
account to you personally, while some use a more generic AIPS account.
The login scripts should start the window system automatically and
produce one or more {\tt xterm} or {\tt aixterm} windows that you can
use for starting {\tt AIPS}\@.

     If the initial \CR\ produces instead a set of windows (and/or
icons), the computer is already being used.  If these windows include
the AIPS TV and possibly the {\tt TEKSRV} and {\tt MSGSRV} server
windows, it is being used for {\tt AIPS}\@.  Check with other possible
users before proceeding.  If it's okay to use the system, you should
log the previous user out and log in for yourself, restarting the
window system.  If you are patient, you can open each iconified window
(by clicking on it once or twice), see what it's doing and finish up
and/or exit.  If the prompt is {\tt >} in any text window, {\tt AIPS}
is running there and you should type:
\disps{{\tt >} KLEENEX \CR}
\dispe{which will get out of {\tt AIPS} and kill the servers.  Then
once at the system prompt (Unix), you can type {\us exit \CR}
(lowercase!) to make the window go away.  If the {\tt XAS} \AIPS\ TV
server is still running, just press the escape key while the cursor is
in the TV window.  For the {\tt MSGSRV} message server, move the
cursor into the window and press {\tt CTRL C}\@.  Finally for the Tek
server, hold the control key down while you press the left mouse
button, and choose the {\tt QUIT} option.}

     The procedure for exiting from the windowing system will depend
on what \indx{window manager} you use.  If your system uses {\tt KDE},
there will be an icon on the icon bar with a large {\tt K}
superimposed on a globe.  If the system uses Gnome, then the magic
icon is an image of a foot.  Move the mouse to the icon and hold down
the left button.  A pull-down menu will appear; select the {\tt
Logout} function.

\subsections{Control characters on the workstation}

     To correct characters which you have typed, you may have to press
either the {\tt BackSpace} key or the {\tt Delete} (or {\tt DEL}) key.
Unfortunately, which is required varies with the application you are
using and how the AIPS account (or your personal account) has been set
up.  For details, see the manual page on {\tt stty} with particular
note of the {\tt erase} function.

    A \indx{control character} is produced by holding down the {\tt
CTRL} (or {\tt Control}) key while hitting another key.  Some control
characters under Unix have characteristics that may confuse users more
used to other environments (VMS, MS-DOS).  In particular, {\tt CTRL
D}, {\tt CTRL T}, {\tt CTRL Y} and {\tt CTRL Z} behave much
differently under Unix than under VMS\@.  {\tt \tndx{CTRL D}} is
used in Unix as a signal to logout, unless otherwise inhibited.  If
you use the AIPS accounts at either Charlottesville or the AOC, this
feature is automatically disabled.  While in {\tt AIPS}, {\tt CTRL D}s
are interpreted from the {\tt >} prompt as an {\tt EXIT} command.
{\tt CTRL T} (under GNU {\tt readline}) transposes two characters,
while {\tt CTRL Y} inserts characters previously saved in the ``kill''
buffer.  {\tt \tndx{CTRL Z}} suspends the current process, printing
{\tt Stopped} on your window and leaving you at the Unix prompt level.
The {\tt Stopped} message does {\it not\/} mean that the process has
been terminated.  It simply means the process has been suspended and
placed in the background.  For \AIPS\ users, the suspended process is
normally {\tt AIPS}{\it n\/}.  Users who do not understand this state
often start up another \AIPS\ session.  In doing so, they are tying up
a second \AIPS\ number.  If a user does this enough times, s/he can
eventually tie up all available {\tt AIPS}{\it n\/}'s.  If you are
unfamiliar with the use of {\tt CTRL Z} (suspend) in Unix systems,
it's best not to use them from \AIPS, unless expert advice is close at
hand.  With an X-Window display, it is preferable to pop up a new {\tt
xterm} or other window and do whatever you want in it, leaving the
\AIPS\ session undisturbed.  (You can get a new {\tt xterm}, usually,
by moving the cursor into the root (background) window, pressing the
right mouse button, and selecting the appropriate option.)  If you
have suspended the current process (usually {\tt AIPS}) with {\tt CTRL
Z} to get to monitor level (for instance, to edit a {\tt RUN} file),
then you can bring the suspended process back into the foreground with
the command \hbox{{\us fg \CR}}.

     To abort any execution in your window, type \hbox{{\tt \tndx{CTRL
C}}}.  Using {\tt CTRL C} while in {\tt AIPS} will unceremoniously
eject you to the Unix prompt.  You will have to restart {\tt AIPS}
with all the input parameters having been lost.  In some cases, any
\AIPS\ tasks running in the background, and maybe even the TV and
other servers, will also be ``killed'' and will disappear from the
screen.  Aborting \AIPS\ ``tasks'' (sub-processes) is usually done
from within {\tt AIPS} with the command {\us ABORT {\it taskname\/}
\CR} (see \Sec{tasks}) rather than with {\tt CTRL C}'s or Unix-level
system commands.  Not only does this avoid killing {\tt AIPS}, but it
even allows for orderly deletion of scratch files.

      During execution, scrolling of output lines out of the window
can be halted by typing {\tt \tndx{CTRL S}} and resumed by typing
\hbox{{\tt \tndx{CTRL Q}}}.  If you are using an {\tt xterm} (or {\tt
cmdtool} or {\tt aixterm}) window with a scroll bar, you probably
won't have to worry too much about doing this; use the scroll bar to
review lines which have rolled off the visible part of the window.
You can specify how many lines these terminal emulator windows
remember, \eg\ for {\tt xterm} with the {\tt -ls} option or with the X
resource {\tt xterm*saveLines} (in your {\tt \tndx{.Xdefaults}} or
{\tt \tndx{.Xresources}} file).

\Subsections{Starting the {\tt AIPS} program}{stAIPS}

     As you enter the commands needed to log in to your system and
start {\tt AIPS}, please read all messages which appear.  They
are often important and relate to current system, disk, and \AIPS\
problems which may affect your reductions.

     To begin {\tt AIPS}, enter
\btd
\dispx{{\tt \%\qs} aips \CR}{with no options initially}
\etd
\dispe{You will then be shown a list of printer devices and be
prompted to {\tt Enter your choice:}.  You will then be told about the
assigned printer queue and data disks.  If all is going well it will
then tell you}
\disps{{\tt You seem to be at a workstation called} {\it monkey\/}}
\disps{{\tt Starting local TV servers on} {\it monkey\/}}
\dispe{where {\it monkey\/} is the name of your workstation.  Any news
messages about your \AIPS\ installation will then appear.  Read them;
they might be important.  Finally, you should see the messages:}
\disps{{\tt Starting up 31DEC24 AIPS with normal priority}}
\disps{{\tt BEGIN THE ONE TRUE AIPS NUMBER }{\it n\/} (release of
               31DEC24) at priority 0}
\dispe{where {\tt 31DEC24} identifies the release of \AIPS\ and {\it
n\/} is a number between 1 and 6 (typically).  If this is the only
\AIPS\ session on the computer, you should be assigned $n = 1$, with
higher numbers used for additional sessions.  If you start with $n >
1$, someone else may be using your computer remotely.  {\tt AIPS} will
then tell which TV and graphics devices have been assigned to you:}
\disps{{\tt AIPS {\it n\/}: You are assigned TV device} {\it nn\/}}
\disps{{\tt AIPS {\it n\/}: You are assigned graphics device} {\it
       mm\/}}
\dispe{where {\it nn\/} and {\it mm\/} are numbers assigned to your
workstation (or, rarely now, to real TV and graphics devices).  {\tt
AIPS} will now ask you for your user number and provide a {\tt ?}
prompt:}
\disps{{\tt AIPS {\it n\/}: Enter user ID number}}
\disps{{\tt ? }{\it uuuu\/} \CR}
\dispe{where {\it uuuu\/} is the number assigned to you for the local
\AIPS\ system (in decimal form). The {\tt AIPS} prompt {\tt >} should
now appear.}

     There is more.  Notice the line above that says ``{\tt starting
local TV servers on monkey}''?  At that point, the process of figuring
out what computer you're running on and what display you're sitting at
(they may be different) is shed in an asynchronous way while the main
process of starting the {\tt AIPS} program proceeds.  Then, sometime
later, you will see the following messages appear in the same window:
%\vfill\eject
\disps{{\tt XASERVERS: Start TV LOCK daemon TVSERV on monkey}}
\disps{{\tt TVSERVER: Starting AIPS TV locking, Inet domain}}
\disps{{\tt XASERVERS: Start XAS on monkey, DISPLAY monkey:0}}
\disps{{\tt XAS: ** TrueColor FOUND!!! }}
\disps{{\tt XAS: ***  Using shared memory option for speed ***}}
\disps{{\tt XAS: Using screen width height 2540 1920}}
\disps{{\tt \hphantom{XAS: }max grey level 8191 in 16 grey-scale memories}}
\disps{{\tt \hphantom{XAS: }characters multiplied by 2}}
\disps{{\tt XASERVERS: Start graphics server TEKSRV on monkey, DISPLAY monkey:0}}
\disps{{\tt XASERVERS: Start message server MSGSRV on monkey, DISPLAY monkey:0}}
\dispe{Each of the first four messages should announce the starting of
one of the servers.  The Tek server will appear in iconified form
somewhere on the screen, while the message server will appear opened
(not iconified) somewhere else.  Finally, the {\tt \tndx{XAS}} TV
server appears in opened form.  An environment variable can be set to
have the Tek server appear in open form and a {\tt .Xdefaults} (or  {\tt
.Xresources}) file option may be set to have the TV appear in iconified
form.  If your X-Windows supports 24-bit TrueColor, then {\tt XAS} will
use it.  Otherwise, {\tt XAS} will use 8-bit PseudoColor which is faster
but less flexible.  In this case, if you have a lot of colors in your
X11 display (\eg\ an image on the root window displayed with {\tt xv}),
you may also get the message:}
\disps{{\tt XAS: Using screen width height 1142 800, max grey level 189}}
\disps{{\tt XAS: Warning -- creating virtual colormap}}
\dispe{which means {\tt XAS} wasn't able to find enough free colors in
the main colormap (189 in the above example) and had to create its
own.  In this case, the colors of every other window will ``flash''
when you move the \indx{mouse} cursor into the opened {\tt XAS} TV
window, and vice versa.  You can use {\tt xsetroot -solid navy}
command (or other legal X colors) to blank out whatever is on the root
window; then restarting {\tt AIPS} will restart the TV server,
hopefully without a virtual colormap.  There are a number of X-Window
parameters which may be specified in your {\tt \tndx{.Xdefaults}} or
{\tt \tndx{.Xresources}} file for these three windows.  After {\tt
AIPS} begins, type {\us HELP XAS \CR}, {\us HELP \tndx{MSGSRV} \CR}, and
{\us HELP \tndx{TEKSRV} \CR} for details. Among these is a parameter
controlling how many colors {\tt XAS} tries to use in PseudoColor and
whether it tries to use TrueColor or not.  Character size multiplication
occurs by default when you have a large number of pixels on your
screen.  It can be controlled by an {\tt .Xresources} parameter and the
{\tt AIPS} verb {\tt \tndx{CHARMULT}}\@.  See \Sec{xas} for more
information about {\tt XAS}\@.}

     There are several options you can use in starting up {\tt
AIPS}\@.  To see them, just enter {\tt \tndx{man aips}} at the Unix
command prompt, or if you are already in {\tt AIPS}, type {\us HELP
AIPS \CR}\@.  This information is reproduced in part below:
\bve
       aips [OLD, NEW, or TST]
            [TV=[disp][:][host]]
         or [TV=local[:n]]
         or [TV=inet]
         or [NOTV]
            [TVOK]
            [DA=host[,host,...]]
         or [DA=default]
         or [DA=all]
            [PR=#]
            [REMOTE or REM or TEK]
            [DEBUG[=prog][:aips]]
            [LOCAL] [NORL] [NOEX]

DESCRIPTION
       The aips or AIPS command starts up the AIPS command interpreter and
       associated AIPS server processes.

OPTIONS
       All command line options are case insensitive.

       AIPS allows up to three versions to co-exist (disk space permitting) in one
       installation.  They are identified either by date (e.g. 31DEC24) or name
       (OLD, NEW, or TST).  On most installations, these will all be the same.

       OLD     Start the OLD version of AIPS.  For NRAO this is a frozen version
               which has been distributed worldwide.  Serious bugs are rarely
               corrected.

       NEW     Start the NEW version of AIPS.  For NRAO this is the most recently
               released version and is "frozen" at the date in its name.
               Serious bugs are corrected over the next year.

       tst     Start the TST version of AIPS.  For NRAO this is the development
               version which is also available to non-NRAO sites.  This is the
               default.

       TV=[tvdisp][:][tvhost] or TV=local[:n] or TV=inet

               The default TV display server is now (31DEC24) TV=local:0.

               TV display server to use instead of the default.  The AIPS startup
               script tries to deduce which host the user is sitting in front of
               (this may not work; it is often difficult or impossible to determine
               this  information).  This may not be the same as the machine on which
               AIPS is to be run if, for example, the user has remotely logged in to
               another machine within a terminal emulator window.

               The  "TV=local" option allows use of Unix based sockets for the TV and
               other servers.  If you choose this option, you MUST run the XAS server
               and any AIPS sessions that will use it on the same host, though the
               DISPLAYs can be the same or different.  Also, no remote AIPS sessions
               will be able to talk to this local TV.

               If you instead use "TV=local:0", it will attempt to start a new
               instance of the TV and ancillary servers.  This can be used to have
               multiple TV's on the same host, and is useful in a compute server
               environment with X terminals.  If you have multiple Unix-socket based
               TV's already started, you can choose which one a new AIPS session will
               use by, e.g. "TV=local:2" to choose the second one.  Note that the
               n in ``TV=local:n'' is in extended HEX or 0 to 9, A to Z.

               NOTE: The default TV behavior is no longer to use internet
               based sockets.  Such use is mostly when more than one
               computer must talk to the same incarnation of XAS, which is
               an uncommon usage.  Internet sockets also require compatible
               entries in the system file /etc/services.

               For the use of internet sockets, the full syntax of the TV= option
               is TV=tvdisp:tvhost, where tvhost is the name of the machine on which
               the TV display server (usually XAS), Tektronix  graphics  server
               (TEKSRV), message server (MSGSRV), and TV Lock server (TVSERV) are to
               run, and tvdisp indicates the machine to which the DISPLAY environment
               variable should point for XAS.  Do NOT specify TV=hostname:0.0!  Both
               TVHOST and TVDISP can be different from the machine that AIPS itself
               is running on.  See the section on X Window System servers below for
               more information on how to control the servers.

               The default behavior of this option  if only one of tvdisp and  tvhost
               is specified is

               TV=tvhost   tvdisp defaults to tvhost.

               TV=tvdisp:  tvhost defaults to the host AIPS is running on.

               TV=:tvhost  tvdisp defaults to the host AIPS is running on.

               For  the remote TV options to work, you must be able to use the rsh or
               remsh command; see the notes on it under the tp= heading below.   Also
               see  the notes on environment variable AIPSREMOTE.  By default, if you
               do not specify any tv= option, you will only get a TV if your  current
               TERM  environment  variable matches sun*, *xterm*, *hpterm, dtterm, or
               iris*.  The DISPLAY environment variable is used if set, otherwise the
               who  am  i  (on  HP-UX, with the -R option) is used to make a guess at
               "where" you really are.

       NOTV    Prevents automatic activation of the TV server if no display is
               wanted.   This option also disables the Tektronix graphics server, the
               message server and the TV lock server.  See the section on X  Window
               System  servers below for information on how to control the Tektronix
               and message servers.

       TVOK    Assume that the TV display servers are already running; the particulars
               (display, host) are still worked out -- from the TV=... argument
               (see above) if necessary -- but no servers will be started.

       DA=host[,host,...] or DA=default or DA=all
               Select user data areas (directories, or "disks" in AIPSpeak) that  are
               local to the (comma separated) list of machines.  Data areas from
               "required" hosts and those on the local machine are always added,
               regardless of the list of hosts.

               All disks from each named host will be assigned.  Use the FREE command
               within AIPS to see the disk assignments you end up with.  They are
               also shown on startup.

               AIPS has a limit of 35 disks in any one session.  The limit on the
               number of disks that can be defined for any given site is 512.  Disk 1
               is special in that it stores the AIPS message and save/get files.  The
               system is designed so that one particular required disk will almost
               always be assigned as disk 1.  For performance reasons, this may be
               undesirable if the filesystem in question is mounted via NFS.  See the
               description of personal .dadevs files below, as it can be used to cus-
               tomize the list of possible user data areas.

               Selecting DA=ALL will try to include every area defined in the startup
               file, up to the session limit.  Bear in mind that most AIPS tasks only
               have 10 slots for "BADDISK".   Selecting DA=DEFAULT will completely
               bypass the configurable data areas and choose only those data areas
               pre-configured by the AIPS manager; THIS IS NOT NORMALLY ENABLED, CHECK
               WITH YOUR AIPS MANAGER BEFORE USING DA=DEFAULT.

               There is a hierarchy of data area "lists" that AIPS will look for on
               startup.  These are:

               $HOME/.dadevs       This would be in your private login area (what
                                   $HOME points to).   It need not exist.  If it
                                   doesn't, AIPS looks for the next file:

               $DA00/DADEVS.LIST   This is a host-specific file possibly set up by
                                   the AIPS manager.  If it doesn't exist, AIPS
                                   finally looks for:

               $NET0/DADEVS.LIST   which is the site-wide data area configuration
                                   file.
               The  normal state of affairs is to have just one place for disks to be
               defined, namely $NET0/DADEVS.LIST.  Your AIPS manager can choose to
               install host-specific list files, and you can choose (if you run AIPS
               from your own private account) to override both of these two with your
               own private  version.   This  allows for considerable flexibility but
               moves the onus of maintenance of these files to the  user.   In other
               words,  if  you  have your own .dadevs file, you have to keep track of
               your site's disk configuration!

               If your AIPS installation supports multiple  sites,  e.g.  to support
               both little-endian (Intel, Mac) and big-endian (Sparc) systems, you
               can have any of these files refer to one or the othe site by appending
               the site name, e.g. $HOME/.dadevs.VCOARN for SITE=VCOARN.

               The  format for these files is all the same: a list of directory names
               preceded by a "+" for required or a "-" for optional.  There should be
               two (2) spaces between the "+" or "-" (in the leftmost column) and the
               directory name.

               In addition to all of the above,  you may define a list of  data areas
               in an optional $HOME/.dadevs.always file.  This is used in addition to
               whichever of the DADEVS files have been selected by the rules above.
               The data areas that you will be assigned  start with any required data
               areas in the $HOME/.dadevs.always file followed by any required data
               areas in the selected DADEVS file regardless of name.   The 3rd group
               of data areas are those optional ones in the selected DADEVS file
               containing a string matching the user's host name.  Then come the
               optional data areas in the  $HOME/.dadevs.always file regardless of
               name.  Finally, the optional data areas in the selected  DADEVS file
               with strings matching the names of any hosts given in the
               DA=host[,host,...] command-line  option.  The order of data areas
               within each group,  i.e. which is disk 1, etc.,  is determined by the
               order in the files.

               There is also a $NET0/NETSP file that is maintained by the AIPS manager
               and controls aips user-number access  to the disks.  Regardless of
               the number of sites in your installation, there is only one NETSP file.

       TP=host[,host,...]

              Make sure tape servers are running on the comma separated list of
              machines.  While the AIPS account is usually set up so that it can
              perform remote shell (rsh) commands, your personal account may not.
              Check with your system administrator or network guru for details.
              Also check the Unix manual pages on rsh (remsh on HP-UX), rhosts, and
              hosts.equiv.  The tp= option uses rsh to issue commands to remote hosts.

       TPOK   Do NOT check or launch the TPMON tape daemons on the local host.  The
              default is no longer to check or to start the tape daemons.  Therefore,
              if you need them, use TP= above even for the current computer.

       PR=#    Select printer number (e.g., pr=2).  If this option is not specified,
               the user will be presented with a menu of available printers and
               prompted to enter a choice.  If there is only one printer configured,
               no menu will be presented.  You may change the selected printer within
               AIPS via the PRINTER adverb.

       REMOTE or REM or TEK
               Any one of these indicates that the user is running from a terminal
               with Tektronix display capability.   Graphics output will be sent
               directly to this terminal.  NOTE: AIPS will not switch from text to
               graphics mode on terminals with a separate graphics "screen".

       DEBUG[=prog][:aips]
               Start AIPS in debug  mode.   With no arguments, the user will be
               prompted for the name of the debugger (e.g. gdb, dbx, adb, csd, xde,
               dbxtool, debugger, xxgdb) and also whether to run AIPS itself under
               the  debugger.  If you answer no, only AIPS tasks will be run in debug
               mode.  If =prog is specified, this suppresses the prompt for the name
               of the debugger program.  If :aips is specified, this suppresses the
               prompt for whether to run AIPS itself in debug mode and assumes it
               will.   Use of both these options is useful in speeding up the startup
               of the system when debugging a program or AIPS itself.

       LOCAL   Start a local copy of AIPS.EXE  residing  in  the  current  directory.
               Usually used by programmers for debugging purposes.

       NORL    Disable  GNU  readline library and command-line editing.  This is pri-
               marily useful for running backgrounded  AIPS  sessions,  running  AIPS
               from "here-document" shell-scripts, and for debugging.

       NOEX    This defers AIPS execution and is not normally used directly by users.


X WINDOW SYSTEM SERVERS
       If you are running under the X Window System, AIPS will open up to three win-
       dows: a TV window (normally XAS), a message window (MSGSRV) and a graphics
       window (TEKSRV).  If you specify the notv option on the command line, none of
       these will be started.

       MSGSRV and TEKSRV are actually simple programs running inside a terminal  emu-
       lator.   You  may use any terminal emulator that you would normally use on the
       machine on which you are running AIPS for the MSGSRV window.  Examples include
       xterm  (the  sample  vt100/Tektronix emulator that comes with the MIT X Window
       System code); cmdtool and shelltool (the standard terminal emulators for Open-
       Windows) and AIXterm (the standard terminal emulator on RS/6000s).  You can
       choose which one to use by setting the environment variable AIPS_MSG_EMULATOR
       to the name of the terminal emulator you wish to use.  For example, if you
       want to use cmdtool you would type

       setenv AIPS_MSG_EMULATOR cmdtool

       if you use the C or TC Shell, or

       AIPS_MSG_EMULATOR=cmdtool; export AIPS_MSG_EMULATOR

       if you use Korn, BASH, or Bourne shells before you start up AIPS.   You  could
       also add these  commands to your .login file (C Shell) or .profile
       (Korn/BASH/Bourne Shells) to make the assignment more permanent.  You can also
       give AIPS_MSG_EMULATOR the special value of "none" which will disable the mes-
       sage window without affecting the Tektronix window or the TV.  If
       AIPS_MSG_EMULATOR is not set, the default is xterm.

       You may choose the terminal emulator used for the Tektronix window using the
       environment variable AIPS_TEK_EMULATOR in the same way that you use
       AIPS_MSG_EMULATOR to choose the terminal emulator, but it must support Tek-
       tronix graphics codes.  On most machines the only values of AIPS_TEK_EMULATOR
       that  make any sense are xterm and none.  If AIPS_TEK_EMULATOR is not set AIPS
       will behave as if it were set to xterm.  (Note: dxterm, aixterm, and cmdtool
       are not "xterm"; they cannot display Tek graphics).

       You can set preferences for positions and colors for all three servers using
       the standard X Window System mechanisms.   Further information is available
       through the AIPS HELP system (subjects MSGSRV, TEKSRV, XAS and XVSS).

       Note that AIPS expects that a terminal emulator can start a program that is
       specified using a -e flag on the command line.  This is true of all of the
       terminal emulators we know about but if you find one that requires a different
       flag you can specify the flag as AIPS_TEK_EXE_FLAG or AIPS_MSG_EXE_FLAG.

ENVIRONMENT VARIABLES
       In addition to the Message and Tek server customizations, you may choose to
       set a variable AIPSREMOTE to indicate your choice of remote shell command.  It
       is strongly recommended that the secure shell (ssh) be used in place of the
       traditional Berkeley rsh or remsh command:
              setenv AIPSREMOTE "ssh -n"
       for csh or tcsh shells, or
              export AIPSREMOTE="ssh -n"
       for bash, korn, zsh and other bourne-like shells.
\end{verbatim}\eve

     If you do not specify a printer (by number) on the command line
when starting {\tt AIPS}, you will get a menu showing you all the
alternative printers available.  You should omit the {\tt PR} option
until you are familiar with the choices.  The OLD version of \AIPS\ is
likely to be relatively free of bugs (provided the \AIPS\ version in
NEW does not prescribe format changes which prevent OLD from working),
but the NEW version will contain improvements and will be mostly
debugged.  The TST version is a debugging area recommended for NRAO
staff and those few users who may require the most recent software.
(Note that this choice affects only the version of the {\tt AIPS}
program itself.  You may choose TST, NEW or OLD versions of the \AIPS\
reduction programs at a later time --- see \Sec{inputs}.)

\subsections{Typing commands to the {\tt AIPS} program}

     As of the {\tt 15JUL95} release, \AIPS\ is available to users
under a GNU-style license.  This has numerous benefits, one of which
is that it allows us to incorporate other GNU-style code within our
system.  The first of these is the \indx{GNU} {\tt \Tndx{readline}}
library which provides the user-input interface for {\tt AIPS} under
Unix beginning with the {\tt 15JAN96} release. The GNU readline
library gives the user the ability to use the cursor-arrow keys, as
well as various ``control'' and ``escape'' key sequences, to recall
previously-entered commands, to edit the current command line (without
having to back-space and re-type the entire line), to search the
command history for previously-executed commands, to define customized
key bindings for executing commands and macros, and much more.  The
full information may be obtained with the command {\tt \tndx{man
readline}} from the system command line (not inside {\tt AIPS})\@.
There is even ``tab completion'' based on the list of \AIPS\ help
files and on context.  At any point, when typing a symbol, you may hit
the {\tt \tndx{TAB}} key.  The symbol name will be completed if it is
unique or the screen will flash (or the bell sound) is it is not.  A
second hit on the {\tt TAB} key will produce a list of the possible
completions.  Since a task name cannot be the first symbol on a line,
tasks are included in the possible completions only after some other
symbol appears on the line.

     The default key bindings should be very familiar to users of
{\tt \tndx{emacs}} and/or the bash shell; many of them should also be
recognizable to users of the Korn and tcsh shells.  Hard-core {\tt vi}
users can put {\tt AIPS} into ``{\tt vi}-mode'' and use {\tt vi}-like
key bindings instead.  (The basic {\tt emacs}-like key bindings will
be outlined below; it will be assumed that those who are using the
non-default {\tt vi}-like key bindings already know what they are
doing.)

     Your command-line history is automatically saved between
sessions, unique to both the user number and the ``\AIPS\ number'' of
the session, and then recovered at the next {\tt AIPS} startup.

     Use of the GNU readline library for input can be disabled on a
per-session basis by starting {\tt AIPS} with the ``{\tt norl}''
option.  This can prevent problems under some operating systems (most
notably HP/UX) with putting {\tt AIPS} into the background, when
running with input ``fed'' from a script, or when debugging {\tt AIPS}
itself.

     The key bindings are given below.  Key sequences/bindings using
the {\tt CONTROL} key will be prefixed below with ``{\tt C-}.''
Those using the {\tt ESCAPE} key (or ``{\tt META}'' key --- often
available as the {\tt ALT} key on PC keyboards and as the ``diamond''
key on Sun keyboards) will be prefixed with ``{\tt M-}.''   The basic
cursor-movement key bindings are:\Todx{readline}\todx{emacs}
\bve
       C-b      backward-character      [also: left-arrow]
       C-f      forward-character       [also: right-arrow]
       C-p      previous-command        [also: up-arrow]
       C-n      next-command            [also: down-arrow]
       M-b      backward-word
       M-f      forward-word
       C-a      beginning-of-line
       C-e      end-of-line
       C-r      incremental-search backward
       C-p      previous-history (move backward in history list)
       C-n      next-history (move forward in history list)
\end{verbatim}\eve
\vspace{-10pt}
\noindent The basic editing key bindings are:
\bve
       C-d      delete-character (under cursor)
       M-d      delete-word (to right of cursor)
       M-DEL    delete-word (to left of cursor)
       C-t      transpose-characters (left with under cursor)
\end{verbatim}\eve
\vspace{-10pt}
\noindent {\tt DELETE} and {\tt BACKSPACE} work as expected.
\pd

\sects{Managing windows}

     Unfortunately, the management of windows on a workstation screen
depends heavily on the type of window manager and on the setup files
defined for your login.  At best, we can only be approximate here and
try to describe general characteristics of normal setups.

\subsections{General window management}

     Most window managers allow multiple windows to be created on the
screen at the same time.  These windows can either be closed in a small
``iconified'' form or opened in a larger and more usable form.
Windows are normally opened by positioning the cursor on the icon with
the \indx{mouse} and clicking either once or twice with the left
button.  You can type only into open windows.  An open window can be
re-sized usually by ``grabbing'' (position the cursor with the mouse
and then hold down the mouse button) one of its corners with the left
mouse button.  Windows under {\tt twm} have a widget in the upper
right corner which must be grabbed with any of the buttons.
Positioning the cursor in the top bar of a window border and holding
down a mouse button will do something.  Usually, the left button moves
the window, the middle button puts the window above or below other
windows, and the right button gets you a pull-down menu of all the
window manipulation options.  Under {\tt \tndx{Motif}} the middle and
right buttons are switched.  In the upper left corner of the top bar
is a special button widget.  Under {\tt Openlook} and {\tt
\tndx{twm}}, clicking on this widget iconifies the window.  Under {\tt
Motif} the iconify widget is shown as a dot and is usually in the
upper right corner.  The widget in the upper left corner under {\tt
Motif} offers a pull-down menu of window options, but is dangerous
since a double click on that widget with the left button destroys the
window (and any programs running in it).\Iodx{window management}

     Positioning the cursor in the root window (the background) and
holding down a mouse button usually gets a pull-down menu with
programs that can be run and various other options including exiting
from the system.  Well-configured systems offer a separate menu with
each button.  This is usually the way to get more windows if you need
them.

     When encountering a system for the first time, you should explore
what the various controls have to offer.  Position in the background,
press each button in turn, and follow up what is offered by the
pull-down menus which appear.  Many menu items may themselves have a
menu which you get by dragging the cursor to the right.  Usually there
is an arrow at the right of the menu item to indicate this.  Then, try
to open some icons with a single click or a quick double click.  Then
try the various mouse buttons in the top bar, the corners, and any
special widgets visible in the window.  Some windows also have scroll
bars along the left or right side.  Experiment with the various mouse
buttons, clicking or dragging, in the scroll-bar region to see how to
scroll back to previous text or forward to the last line.  It pays to
master all this slight of hand to allow you rapid access to multiple
windows, previous text, and the like.  It is very painful to click the
wrong button and destroy a program that has been running for a few
hours already!

\Subsections{Managing the \AIPS\ TV window called XAS}{xas}

     On workstations, \AIPS\ simulates a real TV display with a
program called {\tt \Tndx{XAS}}\@.  The program starts when you start
{\tt AIPS} and comes up in an open form.  Its icon shows a cute
drawing of an ape along with words like {\tt AIPSTV UNIX} for local
display and {\tt AIPSTV INET} for Internet-connectivity.  In many
ways, this is a normal window which can be re-sized, moved, iconified,
and destroyed like any other.  However, when the window is open and
the cursor positioned inside the window, {\tt XAS} offers some
additional features.  The cursor changes shape and color in the window
to indicate this fact.  To get {\tt XAS} to treat the \indx{cursor}
position as a ``\indx{TV cursor}'' position, you must hold down the
left \indx{mouse} button.  This allows the cursor to fill two r\^oles
at nearly the same time, that of a workstation cursor and of a TV
cursor.  You do not have to hold the button down for long to register
a TV position and, in fact, it is more efficient in interactive TV
operations simply to click the left button at the desired locations.
When you drag the cursor, numerous intermediate values are read with
consequent extra computation.  Note that the TV cursor position is
read by {\tt XAS} whenever the cursor is in the {\tt XAS} window with
the left button down.  However, that position is only used when some
verb or task reads it from {\tt XAS} and uses it for some purpose,
\eg\ to select image coordinates or to control image enhancement.

     \AIPS\ TV functions refer to ``buttons'' {\tt A}, {\tt B}, {\tt
C}, and {\tt D} for the purpose of signaling conditions to the
software.  In the {\tt XAS} simulation, these buttons are the keys a,
A, or F3 for {\tt \tndx{button A}}, keys b, B, or F4 for {\tt
\tndx{button B}}, keys c, C, or F5 for {\tt \tndx{button C}}, and keys
d, D, or F6 for {\tt \tndx{button D}}\@.  The F2 and F7 buttons toggle
the size of the display from full screen to whatever size you set the
window. {\tt XAS} simulates a TV with a number, usually sixteen, of
grey-scale memories and eight one-bit graphics overlays.  The x and y
dimensions of the memories adapt to the display area of your
workstation less some room for window borders and, sometimes, for a
few lines of a type-in window as well.  {\tt XAS} has the ability to
display full-color (256 levels for each of red, green, and blue) on
terminals capable of supporting full ``TrueColor visuals.''  The
internal dynamic range of images in {\tt XAS} is actually 0:8191,
but displays are limited to 0:255.  You pay for this capability with a
small reduction in speed for ordinary enhancements, blinks, and the
like.  You may select to limit your {\tt XAS} to a ``PseudoColor
visual'' which is all that is available on some older workstations.
In that mode, the higher the number of grey levels the greater the
dynamic range is available in the display of images.  The maximum
allowed maximum grey level is 235, but this will use all 256 levels of
a ``colormap'' and therefore force {\tt XAS} to use its own colormap.
When the cursor enters the {\tt XAS} window, the computer switches to
that special colormap changing all of the other colors in the other
windows (often in ways that are very undesirable).  The default number
of grey levels is 199 which may be small enough to avoid this effect
or to manage to leave the colors of your most basic windows
unaffected.  Type {\us HELP XAS \CR} when in {\tt AIPS} to see how to
control the number of levels, the colors of the graphics overlay
planes, and numerous other parameters.

If the {\tt XAS} window has closed for any reason, you may restart it
without exiting {\tt AIPS} with the verb {\tt \Tndx{STARTTV}} or
{\tt \Tndx{TVRESTOR}}\@.  If these do not work, exit {\tt AIPS} and
look for (and delete) left over {\tt LOK*}, {\tt MSS*}, {\tt TKS*}, and
{\tt XAS*} files in {\tt /tmp}.  The TV server process named {\tt
TVSRV{\it n}} may also still be running and need to be {\tt kill}ed.

\sects{Additional recipes}

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

\bre
\Item {Combine in an electric blender: 2 ounce {\bf light rum}, 0.5
     ounce {\bf banana liqueur}, 0.5 ounce {\bf lime juice}, 1/2 small
     {\bf banana} peeled and coarsely chopped, and 1/2 cup crushed
     {\bf ice}.}
\Item {Blend at high speed until smooth.}
\Item {Pour into large saucer champagne (or similar) glass.
           Serves one.}
\ere
\eject
