\input COOK82.MAC
\def\titlea{15-Jul-1994}
\def\chapt{2}
\tsect{2.  STARTING UP \AIPS}

     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 Appendix Z.

\subsect{2.1.  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 and tape resources.  Most such computers
cannot support more than a few simultaneous users (or simultaneous
incarnations of the same user) of \hbox{\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 rlogin}) 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.

\subsect{2.2.  Using the workstation}

     The way that a 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.

\subsubsect{2.2.1.  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 log in (\eg\ {\tt Console login:} on an IBM workstation, or {\tt
Gibbon login:} on the Sun workstation named {\tt gibbon}), 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\ and then type the
password (it will not be visible on the screen) followed by another
\hbox{\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 \hbox{{\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 \hbox{{\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 >} EXIT \CR}
\dispe{which will get out of \hbox{{\tt AIPS}}.  Then once at the
system prompt (Unix), you can type {\us exit \CR} (lowercase!) to make
the window go away.  For the {\tt XAS} \AIPS\ TV, 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 \hbox{{\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 window manager you use.  In Charlottesville, the aips account
uses the {\tt twm} or {\tt tvtwm} window managers on all systems (Sun,
IBM, DEC Alpha, Ultrix); on these, pressing the left mouse button on
the root window (the background) will reveal an {\tt EXIT X11} option.
At the AOC, the IBM systems use the Motif window manager ({\tt mwm})
and the left mouse button will get you the menu with the {\tt Exit
Windows} option. Logout, if necessary, by typing \hbox{{\us exit
\CR}}.  Log back in using the procedure given above.

\subsubsect{2.2.2.  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 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 \hbox{VMS}.  {\tt 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} has no
definition and is harmless, while {\tt CTRL Y} does not do anything
useful.  {\tt 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 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 3.1.2)
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 CTRL S} and resumed by typing \hbox{{\tt
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 .Xdefaults} file).

\subsubsect{2.2.3.  Starting the {\tt AIPS} program}

     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
\dispx{{\tt \%\qs} aips \CR}{with no options initially}
\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, data disks, and tape devices.  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 15JAN94 AIPS with normal priority}}
\disps{{\tt BEGIN THE ONE TRUE AIPS NUMBER }{\it n} (release of
               15JAN94) at priority 0}
\dispe{where {\tt 15JAN94} identifies the release of \AIPS\ and
{\it n} is a number between 1 and 5 (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 $nn$ and $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: Starting TEKSRV on monkey, DISPLAY :0}}
\disps{{\tt XASERVERS: Starting MSGSRV on monkey, DISPLAY :0}}
\disps{{\tt XASERVERS: Starting XAS on monkey, DISPLAY :0}}
\disps{{\tt XAS: ***  Using shared memory option for speed ***}}
\disps{{\tt XAS: Using screen width height 1142 800, max grey level 189}}
\dispe{Each of the first three 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 XAS} TV server
appears in iconified form.  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: 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 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 .Xdefaults} file for these three
windows.  After {\tt AIPS} begins, type {\us HELP XAS \CR}, {\us HELP
MSGSRV \CR}, and {\us HELP TEKSRV \CR} for details.  Among these is a
parameter controlling how many colors {\tt XAS} tries to use.  See
\Sec 2.3.2 for more information about \hbox{{\tt XAS}}.}

     There are several options you can use in starting up \hbox{{\tt
AIPS}}.  To see them, just enter {\tt man aips} at the Unix command
prompt, or if you are already in {\tt AIPS}, type {\us HELP
\hbox{AIPS \CR}}.  This information is reproduced in part below:
\vskip 3pt
\verbatim{50pt}
Use:  Start AIPS itself from the command line.  For Unix systems, the
      following usage applies:

         aips [old, new, or tst]
              [da=host[,host,...]]
              [pr=lpdev]
              [tp=tphost[,tphost,...]]
              [tv=[tvdisp][:][tvhost]  or  notv]
              [remote] [debug] [local]

      For VMS systems, the "=" options are not available.  The last
      release to support VMS was 15APR91.  Note that most of the
      information here is also available in the Unix MAN page for AIPS
      which in turn is found in the SYSUNIX area as "AIPS.L".

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

Options: All command line options are case insensitive.

     The DA=, PR=, TP=, TV=, and NOTV options are new to the 15APR92
     release of AIPS.  They will not be recognized properly by older
     versions.

     AIPS allows up to three versions to co-exist (disk space
     permitting) in one installation.  They are identified either by
     date (e.g. 15JUL93) 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 is distributed worldwide.

     new     Start the NEW version of AIPS.  For NRAO this is the
             most recently released version and is frozen right at the
             time of initial public release.

     tst     Start the TST version of AIPS.  For NRAO this is the
             unreleased, development version.  This is the default.

     local   Start a local copy of AIPS.EXE residing in the current
             directory.

     debug   Start AIPS in debug mode.  The user will be prompted for
             the name of the debugger (e.g. dbx, adb, csd, xde, dbxtool,
             debugger), and whether to run AIPS itself in debug; if you
             answer no, only AIPS tasks will be run in debug mode.

     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, no menu will be presented.

     da=host[,host,...]

             Use disks from the comma separated list of machines, which
             have AIPS data areas.  Data areas from "required" hosts and
             any disks on the local machine are always added, regardless
             of the list of hosts.

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

             AIPS has a limit of 15 disks in any one session.  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 be assigned as disk 1.

             There is a hierarchy of disk "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.  If it
                                 doesn't exist, AIPS finally looks for:
             $NET0/DADEVS.LIST   which is the site-wide disk
                                 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 version, YOU
             have to keep track of your site's disk configuration!

             The format for these files is all the same: a list of disk
             (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.
             There is usually one site-wide required disk specified in
             $NET0/NETSP.

             There is also a $NET0/NETSP file that is maintained by the
             AIPS manager and controls TIMDEST and aips user-number
             access to the disks.  You will get error messages if your
             private .dadevs file includes AIPS data areas ("disks")
             that are not in the NETSP file.

             The order of data areas, i.e. which is disk 1, etc., is
             determined by the order in the DADEVS.LIST or .dadevs 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
             man pages on rsh, rhosts, and hosts.equiv.  The tp= option
             uses rsh to issue commands to remote hosts.

     tv=[tvdisp][:][tvhost]

             TV display server to use instead of the default.  The AIPS
             startup script attempts to deduce which workstation the
             user is sitting in front of.  This may not be the same as
             the machine on which AIPS is to be run if, for example, the
             user has done an rlogin to another machine within a
             terminal window.

             The full syntax of this option is TV=tvdisp:tvhost, where
             tvhost is the name of the machine on which the TV display
             server (XAS, XVSS, or SSS), Tektronix graphics server
             (TEKSRV), and text message server (MSGSRV) are to run, and
             tvdisp indicates the machine to which the DISPLAY environ-
             ment variable should point for XAS.

             The default behaviour of this option if only one of tvdisp
             and tvhost is specified is:
                tv=tvhost   tvdisp defaults to tvhost.
                tv=tvdisp:  tvhost defaults to where AIPS is running.
                tv=:tvhost  tvdisp defaults to where AIPS is running.
             For the remote TV options to work, you must be able to use
             the rsh command; see the notes on it under the tp= heading
             above.

     notv    Prevents automatic activation of the TV servers if no
             display is wanted.

     remote  Indicates that the user is running from a terminal with
             Tektronix display capability.  Graphics output will be sent
             directly to this terminal.
|endverbatim

     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 3.5.)

\subsect{2.3.  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 aand
try to describe general characteristics of normal setups.

\subsubsect{2.3.1.  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 mouse and clicking either once or twice with the left button.  You
can type only into open windows.  An open window can be resized
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 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 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).
\eject

     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 offerred 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!

\subsubsect{2.3.2.  Managing the \AIPS\ TV window called XAS}

     On workstations, \AIPS\ simulates a real TV display with a
program called \hbox{{\tt XAS}}.  The program starts when you start
{\tt AIPS} and comes up in an iconified form.  Its icon shows a cute
drawing of an ape along with words like {\tt New Xas} and \hbox{{\tt
AIPS TV}}.  In many ways, this is a normal window which can be
resized, 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 cursor position as a ``TV cursor'' position, you must hold
down the left 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 button {\tt A}, keys b, B, or F4 for button {\tt B}, keys
c, C, or F5 for button {\tt C}, and keys d, D, or F6 for button
\hbox{{\tt 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 two, of grey-scale memories and
four 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.  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 239, 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.
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.

\vfill\eject
\end
