%-----------------------------------------------------------------------
%;  Copyright (C) 1995-1996, 1998, 2000-2002, 2004-2014, 2016, 2018,
%;  Copyright (C) 2020-2021, 2023-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{\AIPS\ for the More Sophisticated User}{pops}

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

     The program {\tt \tndx{AIPS}} uses the \Iodx{POPS}\POPS\ language
to communicate with you. \POPS\ has many capabilities that have been
hidden or taken for granted in the previous sections. Once you start
to become familiar with \AIPS, you will need to know more about \POPS\
to take full advantage of the powerful features which are available.
The first section below describes some of the shortcuts and
conventions of \AIPS\ while the second section describes program flow
control options.. The third section describes multiple features of the
\POPS\ language including the constructions of procedures.  The fourth
section addresses the needs of ``remote'' users of \AIPS, while the
last section discusses how to begin writing your own \AIPS\ tasks.

\sects{\AIPS\ conventions}

\subsections{{\tt AIPS} shortcuts}

     Some niceties of using \POPS\ syntax in \AIPS\ are:
\xben
\Item More than one expression can be put on a line.  These
   \indx{expressions} must be separated by a semicolon ( {\tt ;} ).
   Exceptions are {\tt RESTORE}, {\tt GET}, {\tt RUN} and a few other
   ``\indx{pseudo-verb}s'' which, with their arguments, must stand
   alone.  For example, {\us GET\qs MYIMAGE ; INDISK = 1 \CR} will
   ignore the {\us INDISK = 1}. When in doubt, see the {\tt HELP}
   files for the pseudo-verb to find the restrictions on its use.
\Item As in many other systems, recognized keywords in {\tt AIPS}
   do not need to be typed in full.  You must type only enough of the
   leading characters to get a unique match.  This
   ``\indx{minimum-match}ing'' has been exploited throughout this
   \Cookbook.  If in doubt, hit the {\tt Tab} key.  The keyword will
   be completed if it is unique or the screen will blink.  Hit the
   {\tt Tab} key a second time to see your choices.
\Item The parameter variables in {\tt AIPS} are called
   ``\indx{adverb}s.''  They are assigned values by the equals verb (
    {\us =} ), \eg\ {\us INDISK = 2 \hbox{\CR}}.  The equals sign may
    usually be replaced by a space.  The exception arises when the
    variable on the left is a sub-scripted array element and the
    expression on the right involves a unary minus or other function
    reference (\eg\ {\us APARM(3) = -1 ; APARM(4) = SIN(X) \CR}).
\Item Array adverbs are set to a constant value by putting a single
   value on the right hand side of the equals sign, \eg\ {\us CELLSIZE =
   1.5 \hbox{\CR}}.  A list of values may be put in the array by
   putting the list on the right hand side of the {\us =} sign
   separated by commas ( {\us ,} ), \eg\ {\us LEVS = -1, 1, 2, 3, 6, 9
   \hbox{\CR}}.  The commas may be replaced by spaces in most cases.
   An exception occurs if an element is negative or some other
   arithmetic expression.  Thus, {\us SHIFT = -19\qs -2 \CR} will
   produce {\tt SHIFT = -21,\qs -21}.
\Item A list of values may also be put in a sequence of scalar adverbs
   with the $\sim$ (tilde sign) adverb.  The main use of this is to
   overcome the 128-character limit for input lines to \POPS\ in
   assigning values to an array.  Thus, for example,\\
   {\us RASHIFT = -3000, -2500, -2000, -1500, -1000, -500, 0, 500,
        1000 \CR}\\
   {\us RASHIFT(10) $\sim$ 1500, 2000, 2500, 3000 \CR}
\Item Adverbs can be used in arithmetical expressions or set equal to
   other adverbs, \eg\ {\us OUTNAME = INNAME ; OUTSEQ = 2.5 * INSEQ + 3}.
\Item Both upper and lower case letters may be entered by the user;
   with one exception, \AIPS\ is case insensitive.  That exception is
   in adverb character string values, which are converted to upper
   case by the trailing quote sign.  If you omit the trailing quote
   --- and make that the last command on the input line --- then case
   is preserved (and used) in the string.
\xeen

     As an example, these shortcuts allow the following {\tt AIPS} command
sequence:
\dispt{INNAME = '3C138' \CR}{ }
\dispt{INCLASS = 'IMAGE' \CR}{ }
\dispt{INSEQ = 0 \CR}{ }
\dispt{BLC = 200 , 200 \CR}{ }
\dispt{TRC = 300 , 300 \CR}{ }
\dispt{OUTNAME = '3C138' \CR}{ }
\dispt{OUTSEQ = 5 \CR}{ }
\dispt{GO PRTIM \CR}{ }
\dispe{to be shortened to:}
\displ{Inn\qs '3c138' ; INC\qs 'image' ; blc\qs 200 ; Trc\qs 300
             \CR}{(Note use of upper and lower case.)}
\displ{OUTN\qs INN ; OUTS\qs INS + 5 \CR}{ }
\displ{go\qs prti \CR}{(Task name can be in either case, too.)}
\pd\Iodx{POPS}

\subsections{Data-file names and formats}

     The physical name of the data file is generated internally,
depends on the type of computer, and will not often concern you as a
user. You will refer to an image by specifying its disk number, the
type of image ({\tt 'MA'} for images, {\tt 'UV'} for \uv\ data), and
the following three parts of the image designation:
\xben
\Item Name --- A string of up to 12 legal characters.
\Item Class --- A string of up to 6 legal characters.
\Item Seq --- A number between 0 and 46655.
\xeen
\dispe{Each of these parts corresponds to separate input adverbs
called {\tt \tndx{INNAME}}, {\tt \tndx{INCLASS}}, and {\tt
\tndx{INSEQ}} (and their variations).  You can choose the image name
arbitrarily and sensible choices will reduce other book-keeping.  Many
programs will choose a reasonable image name if you do not specify
one.}

     A common set of conventions for the name adverbs is used
throughout \AIPS\@. {\us INNAME\qs '\qs' \CR} means ``accept any
image name with the specified class and sequence.''  {\us INSEQ\qs 0
\CR} means ``accept any image with the specified name and class'' or,
if only one image is to be used, ``accept the image with the specified
name and class having the highest sequence number.''  {\us
\tndx{OUTNAME}\qs '\qs' \CR} means ``use the actual {\tt INNAME}.''
{\us \tndx{OUTCLASS}\qs '\qs' \CR} means ``use the task name,'' except
for tasks that write more than one output image, in which case
task-based defaults will be used.  {\us \tndx{OUTSEQ}\qs 0 \CR} means
``use a sequence number that is one higher than that of any files
currently on disk with the same name and class as the requested output
file.'' The name and class strings also support ``\indx{wild-card}''
characters for input and output.  This feature is especially powerful
in tasks, such as {\tt FITTP}, that can be told to operate on {\it
all\/} images that match the specified name parameters.  Type {\us
HELP INNAME \CR} and {\us HELP OUTNAME \CR} for details.  The verb
{\tt \tndx{NAMEGET}} will convert the {\tt INNAME} set of adverbs to the
values that would be used by a task.  This is especially useful in
complicated procedures.

     Only the array data, in the form of 4-byte floating-point
numbers, are stored in the image or \uv\ data file.  The header
information is stored separately for each image or \uv\ data set.
Directory information is stored in a special file, called the Catalog
File.  Each disk has one such  file for each user and it contains
directory information for all images and \uv\ data sets belonging to
that user.

     Extension files may be associated with any image data file.  Each
image can have (in principle) up to fifty types of \indx{extension
files} and up to 46655 ``versions'' of each type.  These subordinate
files contain additional information associated with the image and are
designated by a two-letter type code.  {\tt `HI'} is a history file,
{\tt `CC'} is a Clean components file, {\tt `PL'} is a plot file, {\tt
`AN'} is an antennas file, {\tt `SL'} is a slice file.  In \AIPS, an
extension file associated with an image is uniquely specified by the
usual file-naming adverbs plus the extension file type (adverb {\tt
INEXT}) and the version number (adverb {\tt \hbox{INVERS}}).  The
default convention for {\tt INVERS} is reasonable --- on input, zero
means the highest (\ie\ most recent) version and, on output, the
highest plus one.

     Array elements in an image are designated by their pixel
\indx{coordinates} (counts).  If $M(i,j,k,l,m,n,o)$ is a
seven-dimensional array, the (1,1,1,1,1,1,1) pixel will be associated
with the lower left hand corner of the image.  The $i^{\uth}$ (first)
coordinate increments fastest and is associated with a column in each
plane of the image.  The $j^{\uth}$ (second) coordinate is associated
with a row in each plane.  The other coordinates allow the image to be
generalized to cover up to seven dimensions, \ie\ ``cubes'' and the
like.  The two adverbs {\tt BLC} for bottom left corner and {\tt TRC}
for top right corner let you specify the desired sub-array in up to
seven dimensions.  When a sub-image is taken from an image, the
pixel designation of any image element will usually change.

\sects{Process control features of \AIPS}

     There are a number of tools available to assist you in scheduling
and controlling the execution of \AIPS\ tasks.  They include taking
the input from a text file rather than an interactive terminal,
special adverbs to the verb {\tt GO}, and even one or more detached,
batch processing queues.

\Subsections{{\tt RUN} files}{RUNfile}

     If you have some lengthy sequence of commands to give to {\tt
AIPS}, especially if you will have to give essentially the same
sequence more than once, you may find it helpful to prepare the
sequence in a text file using your favorite and flexible text editor.
In particular, it is cumbersome to write and edit procedures more than
about five lines long in \AIPS\ because of its primitive internal
editor.  Long procedures are best written as text files at your
computer's monitor level, where the editing facilities will usually be
much better.  These text files can be transferred to {\tt AIPS} easily
using the {\tt \tndx{RUN}} file facility.

      Any commands that can be typed on the terminal to {\tt AIPS} can
be stored in your text file.  The text files may be stored in a disk
area of your choosing or in a public area identified by the logical
name \hbox{{\tt \$RUNFIL}}.  The name of the file must be all upper
case letters, followed by a period, followed by your user number as a
three-digit ``extended-hexadecimal'' number with leading zeros.  (To
translate between decimal and \indx{extended hexadecimal}, use the
\AIPS\ procedures or the {\tt AIPS} verbs called {\tt \tndx{EHEX}} and
\hbox{{\tt \tndx{REHEX}}}.)  To use the {\tt RUN} file from your own
disk area, define a logical name before starting {\tt AIPS} to point
to the area (see \Sec{textfile}).  Then start up {\tt AIPS} under your
user number and enter
\dispt{VERSION \qs = 'MYAREA' \CR}{where {\us MYAREA} is your disk
                area, or}
\dispt{VERSION \qs = '\ \qs' \CR}{if {\tt \$RUNFIL} is to be used}
\dispt{RUN \qs {\it FILE\/} \CR}{to execute the file named {\it
                FILE.uuu\/}}
\dispe{where {\it uuu\/} is your user number in extended hexadecimal
with leading zeros to make three digits. The file {\it FILE.uuu\/} or,
if it does not exist, {\it FILE.001\/} will be executed by the above
command.  Note that minimum match also applies to {\tt RUN} file
names.}

     The first line of a {\tt RUN} file is ignored by \hbox{{\tt
AIPS}}.  You should type comments into your {\tt RUN} files to remind
you what they are doing.  The first line, any line which begins with
an {\tt *} in column one, and all text following a \dol\ sign (in any
line) are treated as comments which will not be compiled or executed
by \hbox{{\tt AIPS}}.  All facilities in {\tt AIPS} such as {\tt GET},
{\tt SAVE}, {\tt TGET} and {\tt TUGET} can be used in {\tt RUN} files.
You may even nest {\tt RUN} files within {\tt RUN} files up to 20 deep,
but remember that the pseudo-verb {\tt COMPRESS} makes use of the {\tt
RUN} process.  The full contents of a {\tt SAVE} area may be put in a
{\tt RUN} file using {\tt \tndx{SG2RUN}}\@.

     \AIPS\ programmers also provide a few {\tt RUN} files for general
use in each release \eg\ {\tt VLACALIB}, {\tt VLACLCAL} and \hbox{{\tt
VLARESET}}.  They are normally used to create procedures helpful to
some, but not all, \AIPS\ users.  These are stored under user number
1, but are available automatically to everyone.  To use a procedure
from one of them, type, for example:
\dispt{RUN\qs VLAPROCS \CR}{to read and execute file {\tt VLAPROCS}
           in \hbox{{\tt AIPS}}.  The text will be listed as it is
           read.}
\dispe{This file contains a number of procedure definitions including
those named above.  To execute the procedure, prepare the input
adverbs as needed, and then type}
\dispt{VLACALIB \CR}{to execute the calibration sequence of the
           simplified procedure.}
\dispe{\AIPS\ programmers will provide a file with the inputs and help
information for all canned procedures.  Thus you can do}
\dispt{HELP\qs VLACAL \CR}{to see help information on the procedure.}
\dispt{INP\qs VLACAL \CR}{to see the current inputs to the procedure.}
\dispe{The help and inputs functions may require the {\tt RUN} if
special adverbs are used by the procedure, but you must do the {\tt
\tndx{RUN}} to compile the procedure before you can use it.}

\Subsections{More about {\tt GO}}{moreGO}

     The verb {\tt \tndx{GO}} is shown in examples throughout this
\Cookbook.  Don't overlook the fact that {\tt GO}, like all other
\AIPS\ verbs, has its own inputs.  You will be familiar with the
ability to specify which task you want to execute either by an
immediate argument, \eg\ {\us GO\qs UVSRT \CR}, or by the parameter
{\tt TASK}, \eg\ {\us TASK\qs 'UVSRT' ; GO \hbox{\CR}}.  {\tt GO} has
three further parameters, {\tt \tndx{DOWAIT}},{\tt \tndx{VERSION}},
and {\tt \tndx{QCREATE}}\@.  The value of {\tt DOWAIT} is passed to
the task and instructs it to resume {\tt AIPS} as soon as possible
({\us DOWAIT\qs FALSE \CR}) or to resume {\tt AIPS} only after
completing its operations ({\us DOWAIT\qs TRUE \hbox{\CR}}).  The
latter option lets the task return a meaningful error code to which
{\tt AIPS} may respond by aborting the current input line, procedure,
{\tt FOR} loop, etc.  Note that the verb {\us WAIT\qs '{\it
taskname\/}'} also forces {\tt AIPS} to wait for a task to complete,
but it cannot respond to some failure in that task. For example, the
line:
\displ{GO\qs UVSRT ; WAIT\qs UVSRT ; GO\qs UVMAP \CR}{ }
\dispe{may cause unwanted images to be generated by {\tt UVMAP} if
{\tt UVSRT} fails for lack of disk space or some other reason.
However, the line:}
\displ{DOWAIT\qs TRUE ; GO\qs UVSRT ; GO\qs UVMAP \CR}{ }
\dispe{will not attempt to execute {\tt UVMAP} if {\tt UVSRT} fails.
Note that {\tt AIPS} will not get hung up when a task aborts even if
{\tt DOWAIT} is true.  {\it This consideration is particularly
important when you do multiple runs of {\tt FITTP} to write your
output tape.  If one fails, the tape may even be rewound.  If the next
scheduled {\tt \tndx{FITTP}} actually runs, it may write at the
beginning of tape, destroying all previous data on the tape!}}

     {\tt \tndx{VERSION}} is used to specify which version of the
program you wish to execute.  You might use this to select the {\tt
TST} or {\tt OLD} versions of a task from the {\tt NEW} version of
{\tt AIPS}, for example. {\tt VERSION} also allows you to execute
private versions of programs and even to check a list of areas for
versions of your program.  Type {\us HELP\qs VERSION \CR} for details.
The last adverb, {\tt QCREATE = 1}, instructs tasks to create files
quickly.  This can save a lot of time, but does not guarantee that the
disk space will be available when the task gets around to needing it.

     {\tt \tndx{GO}} has another useful capability.  Normally, in
order to invoke a verb, you simply type its name, \eg:
\dispt{PRTMSG \CR}{to print the message file contents.}
\dispe{However, if you type, instead:}
\dispt{GO\qs PRTMSG \CR}{ }
\dispe{having forgotten that {\tt PRTMSG} is a verb, then {\tt AIPS}
will actually execute:}
\dispt{\tndx{TPUT}\qs PRTMSG ; PRTMSG \CR}{to save the current {\tt
           PRTMSG} inputs and then print the contents of the message
           file.}
\dispe{You can recover those inputs at a later time with {\us
\tndx{TGET}\qs PRTMSG \hbox{\CR}}.}

\subsections{Batch jobs}

     The \AIPS\ \Indx{batch} processor can be used to run jobs outside
interactive \AIPS\@.  The job consists of a set of \AIPS\ instructions
which do not need user interaction.  This excludes the TV, the
Tektronix, and the tape-drive oriented tasks and verbs.  {\tt RUN}
files may be used in batch jobs --- as the batch editor facility
is also primitive, they are particularly attractive to batch users.
Older restrictions on which tasks may be run in queue 1 have been
removed in the {\tt 15JAN96} release.

     The instructions to be executed in the batch processor are
prepared in a ``workfile.''  The workfile can be made while in {\tt
AIPS} and detailed instructions are given by typing:
\dispt{HELP BATCHJOB \CR}{ }
\dispe{A simple example is given here:}
\dispt{\tndx{BATQUE} = 2 ; \tndx{BATCLEAR} \CR}{to select queue 2 and
        clear its workfile.}
\dispt{BATCH \CR}{to enter batch preparation mode.}
\dispx{{\tt < }TASK = 'UVSRT' \CR}{(Notice {\tt <} prompt.  Begin
        typing as in \hbox{{\tt AIPS}}.)}
\dispx{{\tt < }INN = '3C16' ; INCL = 'UVDATA' \CR}{ }
\dispx{{\tt < }INSEQ\qs 1 ; OUTN\qs INN ; OUTCL\qs INCL \CR}{ }
\dispx{{\tt < }OUTSEQ = 0 ; SORT = 'XY' \CR}{ }
\dispx{{\tt < }GO \CR}{(Batch {\tt AIPS} always waits for a task to
        finish before continuing.)}
\dispx{{\tt < }RUN\qs XXXXX \CR}{({\tt RUN} files are good to use in a
        batch job.)}
\dispx{{\tt < }GO \CR}{ }
\dispx{{\tt < }\tndx{ENDBATCH} \CR}{to leave batch preparation mode
        type in {\us ENDBATCH} spelled out in full.}
\dispt{ }{(Resume normal interactive processing.)}
\pd

     To list a batch file, type:
\dispt{BATFLINE = 0 ; \tndx{BATLIST} \CR}{ }
\dispe{To edit line {\it n\/} in a batch file, type:}
\dispt{\tndx{BATEDIT}\qs{\it n\/} \CR}{ }
\dispx{{\tt < }{\it put text here\/} \CR}{to replace old line {\it
          n\/}.}
\dispx{{\tt < }{\it some more text\/} \CR}{to insert more commands
          between old lines {\it n\/} and {\it n\/}+1.}
\dispx{{\tt < }ENDBATCH \CR}{(spelled out in full.)}
\dispt{ }{(Resume normal interactive processing.)}
\dispe{As with procedures (\Sec{popsproc}), if {\it n\/} is an
integer, the existing line {\it n\/} is overwritten with the line or
lines typed before \hbox{{\tt ENDBATCH}}.  If {\it n\/} is not an
integer, the new lines are simply inserted between lines {\it n\/} and
{\it n\/}+1.  {\tt \tndx{BAMODIFY}} provides, for workfiles, the same
functions as {\tt MODIFY} does for procedures.}

     Finally, the workfile can be submitted to the batch processor
by typing:
\dispt{\tndx{SUBMIT} \CR}{ }
\dispe{The instructions are sent to a checking program which checks
that the input is free of obvious errors.  All {\tt RUN} files are
expanded and checked.  If Checker (the task {\tt AIPSC}{\it m\/} where
{\it m\/} is some extended hexadecimal number $<$ Z) approves, the job
goes into the \AIPS\ job queue, which is managed by {\tt QMNGR}{\it
n\/}.  If you change your mind, the job can be removed from the queue
and returned to the workfile with the verb {\tt \tndx{UNQUE}}.
The batch job may be submitted to any local computer, not just the one
on which the current \AIPS\ session is running.  Adverbs {\tt REMHOST}
and {\tt REMQUE} control this option.  The remote host must be one
sharing the same \AIPS\ installation as the current session.  Note
that the data must also be available to the remote host, but verb {\tt
\tndx{ADDDISK}} may be useful either within the batch job or in
preparing the data files for the job.  {\tt REMOST} is supported by
all relevant batch-related verbs.}

     Batch has several limitations.  First, devices which require
interactive use (TV device, Tektronix device, and the tape drives)
cannot be used in \Indx{batch}.  Also, batch uses a different set of
{\tt \tndx{TPUT}} and {\tt TGET} files.  Thus, a {\tt \tndx{TGET}} in
batch does not get the adverbs from your last interactive use of the
specified task. However, the {\tt AIPS} facilities {\tt \tndx{GET}}
and {\tt \tndx{SAVE}} are particularly useful for batch.  You can use
interactive {\tt AIPS} to set up and test set(s) of procedures and
adverb values and {\tt SAVE} them in named files. These files may then
be recovered by batch for the routine processing of large sets of
data.  This is considerably more convenient than using the batch
editor.  Note that {\tt SAVE} / {\tt GET} files may become obsolete
with new \AIPS\ releases, but that improvements to the \POPS\ language
have made this quite unlikely.

     At present, \indx{batch} jobs are run after a short delay, on a
first-come, first-served basis.  After your job has been submitted
successfully, type:
\dispt{\tndx{QUEUES} \CR}{to list jobs in the queue.}
\dispe{Note the {\tt SUBMIT} {\tt TIME} for your job.  It will not start
before that time.  The messages generated by your batch job will be
printed automatically into a text file.  They are kept in your message
file, however, and can be reprinted or examined later via {\tt PRTMSG}
with {\tt PRNUMB} set to the \AIPS\ number of the batch queue.
Printer output for batch jobs is concatenated into a file either
specified by the user with {\tt \tndx{OUTPRINT}} or a file named {\tt
PRTFIL:BATCH{\it jjj\/}.{\it nnn\/}}, where {\it jjj\/} is the job
number and {\it nnn\/} the user number both in extended hexadecimal.
Note, this means batch job printouts are concatenated in (normally)
one file and are not automatically printed. An interactive {\tt AIPS}
can interact with a batch job via {\tt \tndx{TELL}}; see
\Sec{cleanbasic}.}

\Sects{{\tt AIPS} language}{POPsym}

     {\tt AIPS} contains a basic set of symbols and keywords which are
needed to construct a computer language, as well as the symbols needed
by the application code.  A list of the basic symbols is given in the
help file called {\tt POPSYM}, reproduced below:\Iodx{POPS}
\bve
Type:  Symbols used in the POPS interpretive language

    VERB      USE        COMMENTS

                   ----Arithmetic expressions

     +       A + B       Add the expression A to B
     -       A - B       Subtract the expression B from A
     *       A * B       Multiply the expression A with B
     /       A / B       Divide the expression A by B
     **      A ** B      Calculate A to the power B
     ( )     (A+B)*C     Grouping expressions as desired
     =       A = B       Store the value of B into A
     ,       A = 3,5,4   Separator of elements in an array
     ~       A(i) ~ 1,2,3  Store values in A(i),A(i+1)...
                         (change only as many as on RHS)
     :       TO          Equivalent to the verb TO
     ;                   Separator between AIPS statements

                   ----Logical expressions

     >       A > B       A greater than B
     <       A < B       A less than B
     =       A = B       A equal B (numeric or string)
     >=      A >= B      A equal to or greater than B
     <=      A <= B      A equal to or less than B
     <>      A <> B      A not equal to B (numeric or string)
     !       A ! B       A or B
     &       A & B       A and B
     ^       ^ A         not A

                   ----String expressions

  !!       A !! B        string = string A followed by string B
  SUBSTR   SUBSTR(A,i,j) string = chars i through j of string A
  LENGTH   LENGTH(A)     position last non-blank in A
  CHAR     CHAR(A)       convert number A to string
  VALUE    VALUE(A)      convert string A to number


                   ----Looping constructions

  (FOR-TO-BY-END)        FOR I=1 TO 7 BY 2
                         <any valid set of AIPS syntax>
                         END

  (WHILE-END)            WHILE <any logical expression>
                         <any valid set of AIPS syntax>
                         END

  (IF-THEN-ELSE-END)     IF <any logical expression>
                         THEN <any valid set of AIPS syntax>
                         ELSE <any valid set of AIPS syntax>
                         END

                   ----Built-in functions

  ACOS          Arc-cosine - output in degrees
  ASIN          Arc-sine - output in degrees
  ATAN          Arc-tangent (one argument) - output in degrees
  ATAN2         Arc-tangent (two arguments) - output in degrees
  COS           Cosine (degrees)
  SIN           Sine (degrees)
  TAN           Tangent (degrees)
  EXP           Exponential
  LN            Log base e
  LOG           Log base 10
  SQRT          Square-root
  MAX           Maximum i.e. X = MAX (A, B)
  MIN           Minimum i.e. X = MIN (A, B)
  MODULUS       Root-square sum of two arguments
  MOD(A,B)      A - (A/B) * B  i.e. remainder of A/B
  CEIL(A)       Lowest integer >= A
  FLOOR(A)      Highest integer <= A

                   ----Procedure building verbs

  PROC      PV  Begin building a procedure
  PROCEDUR  PV  Begin building a procedure
  LIST      pV  List a procedure
  EDIT      PV  Edit a procedure
  ENDEDIT   PV  End editing a procedure
  ERASE     PV  Delete line(s) of a procedure
  MODIFY    PV  Modify a line in a procedure
  RETURN    V   Last statement in a procedure
  FINISH    PV  End procedure building

                   ----Variable declarations

  SCALAR    pV  Declare scalars
  ARRAY     pV  Declare arrays
  STRING    pV  Declare strings

                   ----Input/Output functions

  PRINT     V   Print the following keyword value(s)
  TYPE      V   Print the following keyword value(s)
  READ      V   Read value(s) from terminal after # prompt

                   ----Other information

  CORE      pV  Amount of core left in POPS
  COMPRESS  PV  Compress the core area, recovering lost space
                and acquiring any new vocabulary
  CLRTEMP   V   Clear the temp data array
  DEBUG     pV  Debug: turns on compiler debug information
  DUMP      V   Dump K array on terminal screen
  SCRATCH   PV  Remove procedures in POPS
  $         PV  Makes rest of input line a comment
\end{verbatim}
\eve%$

\subsections{Using \POPS\ outside of procedures}

     \POPS\ variables are either numeric or character valued and may
be multi-dimensional arrays.  Once created, all variables are
available everywhere, \ie\ they are global.  You may manipulate these
variables on the command line using most of the symbols listed above.
In fact, you have been doing this while setting the adverbs for all
the tasks and verbs described in preceding chapters.  The more
advanced user may wish to use some of the language features in order
to simplify repetitive data processing.  Here are some simple examples
of uses of the {\tt AIPS} language:\iodx{adverb}\iodx{expressions}
\displ{TYPE (2 + 5 * 6) \CR}{32 is written on the terminal.}
\displ{TYPE 'X =', ATAN (1.0) \CR}{{\tt X = 45} is written on the
          terminal.}
\displ{TYPE 'MAPNAME ', INNAME, INCLASS, INSEQ \CR}{{\tt MAPNAME \qs
          3C138 \qs IMAGE \qs 1} is written on the terminal.}
\pd

     The simplest loop capability in {\tt AIPS} uses the pseudo-verbs
{\tt \tndx{FOR}}, {\tt TO}, and {\tt BY} for repetitive operations.
Such loops are primarily intended for use in ``procedures'' (see
\Sec{popsproc}).  If a {\tt FOR} loop can be typed fully on one input
line, it will also work outside the procedure mode.  The following
example shows how to delete a series of images with the same name and
class and with consecutive sequence numbers 1 through 10:
\displ{INNA\qs 'TEST' ; INCL\qs 'IMAGE' \CR}{to set (fixed) name
          parts.}
\displ{INDI\qs 1 \CR}{to set (fixed) disk number.}
\displ{FOR\qs INSEQ =  1\qs TO\qs 10 ; ZAP ; END \CR}{to delete the
          files.}
\dispe{{\tt FOR} loops must be terminated with an \hbox{{\tt END}}.
The following example shows how to delete every other file in a
catalog with 20 entries:}
\displ{FOR\qs INSEQ =  1\qs TO\qs 20\qs BY\qs 2 ; GETN(I) ; ZAP ; END
          \CR}{ }
\dispe{More extensive examples are shown in the sections below on
procedures.\Iodx{POPS}}

    In some cases, you may wish to manipulate \indx{character strings}
to give your files meaningful names --- particularly if your {\tt RUN}
file or procedure operates repetitively on many similar files.  The
verbs for character manipulation are listed above.  As an example,
\displ{OUTNAME = 'CLEAN' !! CHAR(BLC(3)) \CR}{to name each output file
                after the input image plane.}
\dispe{Note that trailing blanks are ignored.  If you wanted a space
after {\tt CLEAN} before the plane number, use}
\displ{OUTNAME = 'CLEAN' \CR}{to set the basic form.}
\displ{SUBSTR (OUTNAME , 7 , 12) = CHAR (BLC(3)) \CR}{to alter only
                the last six characters of {\tt OUTNAME}.}
\pd

\Subsections{Procedures}{popsproc}

     Procedure building is a way to combine keywords in {\tt AIPS} in
any convenient way to obtain useful constructs.  For complicated
sequences, it is easier to prepare and debug procedures in {\tt RUN}
files (\Sec{RUNfile}) than to prepare them in interactive
\hbox{\AIPS}.  A \Indx{procedure} is given a name, with or without
arguments, and then can be treated as an \AIPS\ verb.  As an example,
consider a procedure to load an image  on the TV, set the cursor, and
fit for the maximum intensity.  You could type the following on your
terminal:

\dispt{\tndx{PROC}\qs MFIT (I) \CR}{to define procedure {\tt MFIT}
          with one argument \hbox{{\tt I}}.  ({\tt I} and {\tt J} are
          two dummy adverbs which are already defined in \hbox{{\tt
          AIPS}}.)}
\dispx{{\tt : }GETNAME(I) \CR}{(Notice the prompt symbol {\tt :} .
          This means that we are in the procedure-building mode.)}
\dispx{{\tt : }TVLOD ; IMXY ; MAXFIT \CR}{to load the image, produce
          and read the cursor, and fit the maximum near the cursor
          position when a TV button is pressed}
\dispx{{\tt : }\tndx{RETURN} \CR}{to designate a return point in the
          procedure --- normally not required at the end of a
          procedure unless a value is to be left on the stack, \ie\ a
          function.}
\dispx{{\tt : }\tndx{FINISH} \CR}{to designate the end of the
          procedure-building mode and to get back into the normal
          (prompt {\tt >}) mode.}
\dispt{ }{Notice the prompt symbol, you are back to interactive input
          mode.}
\dispe{When you type such a procedure into {\tt AIPS}, the code is
compiled as you type.  Most syntax errors are spotted immediately and
will unceremoniously dump you out of \Indx{procedure} mode.  However, all
lines written before the detected error are kept and the procedure editor
can be used to continue.}

     The \AIPS\ procedure editing capabilities are quite primitive.
If you want to build procedures longer than about five lines, we therefore
recommend using permanent storage files in the ``{\tt RUN}'' area,
as discussed in \Sec{RUNfile} above.\Iodx{POPS}

     To list the procedure {\tt MFIT}, type:
\dispt{\tndx{LIST}\qs MFIT \CR}{ }
\dispe{This will produce the following:}
\begin{center}
\begin{tabular}{ll}
        1 & PROC MFIT(I) \\
        2 & GETNAME(I) \\
        3 & TVLOD ; IMXY ; MAXFIT \\
        4 & RETURN \\
        5 & FINISH
\end{tabular}
\end{center}
\dispe{The \indx{procedure} is identical to what you typed, with line
numbers added.}

     Procedures are edited line by line. To edit line 2 in the above
procedure, type:
\dispt{\tndx{EDIT}\qs MFIT\qs 2 \CR}{to enter Procedure editing mode.}
\dispx{{\tt ; }GETNAME(I) ; TVLOD \CR}{(Notice prompt symbol {\tt ; }
        for procedure-editing mode.)  This change replaces the old
        line 2 adding a \hbox{{\tt TVLOD}}.}
\dispx{{\tt ; }IMXY ; MAXFIT \CR}{to add a line between the changed
        line 2 and old line 3.}
\dispx{{\tt ; }GETNAME(I+1) \CR}{to add yet another line after 2.}
\dispx{{\tt ; }\tndx{ENDEDIT} \CR}{to terminate procedure editing.}
\dispt{LIST\qs MFIT \CR}{ }
\dispe{Listing the modified procedure will give:}
\begin{center}
\begin{tabular}{ll}
        1 & PROC MFIT(I)\\
        2 & GETNAME(I) ; TVLOD\\
        3 & IMXY ; MAXFIT\\
        4 & GETNAME(I+1)\\
        5 & TVLOD ; IMXY; MAXFIT\\
        6 & RETURN\\
        7 & FINISH
\end{tabular}
\end{center}

     To delete lines {\it n\/}  through {\it m\/} from a procedure,
type:
\dispt{\tndx{ERASE}\qs {\it xxxxxxxx\/\qs n} : {\it m\/} \CR}{where
       {\it xxxxxxxx\/} is the name of the procedure.}
\dispe{To insert one or more lines between lines 3 and 4 of a
procedure, type:}
\dispt{EDIT {\it xxxxxxxx\/} 3.5 \CR}{ }
\dispx{{\tt ; }{\it (Type additional lines as needed.\/)}}{ }
\dispx{{\tt ; }ENDEDIT \CR}{ }
\dispe{Notice that the lines are renumbered after any {\tt EDIT} or
\hbox{{\tt ERASE}}.  Use {\tt LIST} to determine the new line
numbers.\Iodx{POPS}}

     The pseudo-verb {\tt MODIFY} lets you modify characters within
a line of a procedure to correct the line or change its meaning.
The grammar is:
\dispt{\tndx{MODIFY}\qs{\it proc-name\/}\qs{\it line-number\/}}{where
         {\it proc-name\/} is the name of the procedure and {\it
         line-number\/} is the line number in the procedure as shown
         by \hbox{{\tt LIST}}.}
\dispe{{\tt MODIFY} begins by showing the existing line with a {\tt ?}
as a prefix.  Then it prompts for input with a {\tt ?}  To keep the
character of the original line immediately above the cursor, type a
blank (space-bar). To delete that character, type a \dol\
(dollar-sign).  To replace that character, type the new character (to
get a new blank character, type an {\tt @} sign).  Insertions
complicate things.  To insert text prior to the character immediately
above the cursor, type a {\tt\char'134} followed by the desired text
followed by another {\tt\char'134}.  You may continue to {\tt MODIFY}
the remainder of the line, but you must remember that the current
character position in the old line is to the left of the current
cursor position by the number of inserted characters (including the 2
{\tt\char'134}'s).  {\tt MODIFY} will display the resulting line of
code after you hit a carriage return (\CR) and does not change the
line number.  Example:}
\bve
> MODIFY  ED  2 |CR
?TYPE 'THIS IS EDS PROC'
?              MY@\NEW\     @FOR@EXAMPLE' |CR
TYPE 'THIS IS MY NEW PROC FOR EXAMPLE'
> MODIFY  ED  2 |CR
?TYPE 'THIS IS MY NEW PROC FOR EXAMPLE'
?                 $$$$    \EDURE,\ |CR
TYPE 'THIS IS MY PROCEDURE, FOR EXAMPLE'
\end{verbatim}
\eve
\Iodx{POPS}\todx{MODIFY}

     More information about \Indx{procedure} building and editing can
be found by typing:
\dispt{HELP\qs PROCEDUR \CR}{ }
\dispe{Procedure creation and editing uses up the limited memory of the
\POPS\ processor.  When the memory is gone, the message {\tt BLEW
CORE!} will appear and you can do no more procedure writing without
starting over (\ie\ {\us RESTORE\qs 0 \CR}).  {\us CORE \CR} will tell
you how much memory is left.  If the memory remaining appears small,
try {\tt \tndx{COMPRESS}} to recover the lost memory (in {\tt 15JAN96}
and later releases).  {\tt COMPRESS} might even work after a {\tt
\tndx{BLEW CORE!}} if you are lucky.}

     The procedure {\tt MFIT} can be executed by:
\dispt{MFIT({\it n\/}) \CR}{where {\it n\/} is the slot number of the
                appropriate image.}
\dispe{(It is assumed that the correct disk unit number has already
been set.)  This procedure can also be part of another procedure or
put in a loop.  For example:}
\displ{FOR I= 1 TO 10 BY 2; MFIT(I) ; END \CR}{ }
\dispe{will load the TV and fit the maximum for the first ten
images on the appropriate disk.}

     All the syntax available in {\tt AIPS} is available for use
inside procedures {\it except for certain pseudo-verbs}.  The
``prohibited'' pseudo-verbs include {\tt SAVE}, {\tt GET}, {\tt STORE},
{\tt RESTORE}, {\tt PROCEDURE}, {\tt EDIT}, {\tt ENDEDIT}, {\tt MODIFY},
{\tt LIST}, {\tt CORE}, {\tt SCRATCH} and \hbox{{\tt COMPRESS}}.
Others do not make much sense in procedures, including {\tt MSGKILL},
{\tt DEBUG}, and \hbox{{\tt ABORTASK}}.  Other pseudo-verbs are,
however, particularly useful in procedures.  These include {\tt TGET},
{\tt TPUT}, {\tt TUGET}, and \hbox{{\tt GO}}.

     Several verbs are extremely useful in procedures.  To set the
image name adverbs to those visible on the TV, use \hbox{{\tt
TVNAME}}.  When {\tt GETN} accesses an empty slot, an error condition
is raised and the procedure dies.  To handle this error condition in
your procedure, use {\tt EGETN} {\it n\/} instead and test the adverb
{\tt ERROR} which will be ``true'' if the slot is empty.  {\tt
\tndx{CHKNAME}} may be used similarly to check on the existence of
files with computed names.  Some tasks require image-data dependent
inputs.  To help handle this in general procedures, the verb {\tt
GETHEAD} allows all header parameters to be fetched into adverbs. Type
{\us EXPLAIN GETHEAD \CR} for details.  Verbs {\tt \tndx{GETTHEAD}}
and {\tt \tndx{TABGET}} perform similar functions for data in table
extension files.  The verb {\tt \Tndx{GETPOPSN}} fetches the current
\POPS\ number for use in procedures, for example, to allow the same
procedure to run concurrently in multiple \AIPS\ sessions.   The verb
{\tt \tndx{DELAY}} will cause {\tt AIPS} to pause for a specified
period of time --- {\tt MFIT} above would benefit by pausing to allow
the user to see his images.  There are numerous arithmetic functions,
useful looping constructions, and powerful methods of building
arithmetic, logical, and string expressions in \hbox{\POPS}.  See
\Sec{POPsym} above for a list of these. {\tt CLRTEMP} may be used in
procedures which do a lot of looping.  It clears the temporary space
used to hold sub-strings and other temporary constants. A procedure
that does much string manipulation is likely to overflow this area
after a number of iterations.  The message {\tt BLEW TEMP C!} usually
accompanies the overflow.

     Once a \Indx{procedure} is written and edited, it can be stored
in a {\tt \tndx{SAVE}} file for later use.  Procedures are lost when
another {\tt \tndx{GET}} file is obtained.  Procedures can be stored
more permanently in {\tt RUN} files which are described in
\Sec{RUNfile} above.  To list the names of all procedures currently in
your {\tt AIPS} environment, type:
\dispt{\tndx{HELP PROCS} \CR}{ }
\dispe{This will list internal \AIPS\ procedures as well as your own.}

      Several procedures have been built into \hbox{\AIPS}.  In
particular, some procedures are defined in the system {\tt RUN} file
{\tt VLAPROCS} to aid {\it routine\/} calibration of VLA data.
Currently, these are {\tt VLACALIB}, {\tt VLACLCAL} and \hbox{{\tt
VLARESET}}.  Similarly, VLBA reductions are aided by the procedures in
the file named {\tt VLBAUTIL}\@.  They may be useful templates for
your own procedures.  If you are unfamiliar with the use of \AIPS\
procedures, looking at these system-supplied ones will help you to
understand, and see the power of, this feature of
\hbox{\AIPS}.\Iodx{POPS}

\subsections{Writing your own programs with \POPS}

     You may want to add your own programs to \hbox{\AIPS}.  It is not
a trivial matter to generate an \AIPS-standard FORTRAN program (see
{\us \tndx{HELP NEWTASK} \CR}, the {\it Going\/} \AIPS\ manuals, and
\Sec{owntask} below).  Simple but powerful programs may however be
built as \Indx{procedure}s that use existing verbs and tasks.
\Iodx{POPS}\iodx{Going AIPS}

     Consider a the following example.  (This example is presented as
if it were typed into an interactive \hbox{{\tt AIPS}}.  In practice,
you will probably prefer to prepare such a complicated procedure as a
{\tt RUN} file.)  We wish to determine the average value and rms
scatter at any pixel location in a set of {\it n\/} images.  We shall
demand that the {\it n\/} images all have the same {\tt INNAME} and
{\tt INCLASS} with sequence numbers between 1 and {\it n\/}.  The {\tt
RENAME} verb can be used to name the images appropriately.  We could
call this procedure:
\par\centerline{{\tt AVGRMS (PIXXY, N, AVG, RMS)}\hskip 100pt}
\dispe{where}
\begin{center}
\begin{tabular}{ll}
   {\tt PIXXY } & is the pixel location in the images,\\
   {\tt N}      & is the number of images,\\
   {\tt AVG}    & is the average value at the pixel location, and\\
   {\tt RMS}    & is the rms value at the pixel location.
\end{tabular}
\end{center}
\dispe{The array adverb {\tt PIXXY} is a standard {\tt AIPS} adverb,
but the variables {\tt N}, {\tt AVG}, and {\tt RMS} are unknown to
\hbox{{\tt AIPS}}.  These must be defined before we can write the
procedure \hbox{{\tt AVGRMS}}.  This is done by a short dummy
procedure which we will call {\tt DAVGRMS}:}
\displ{PROC\qs DAVGRMS \CR}{to define dummy procedure.}
\displx{{\tt : }SCALAR\qs N, AVG, RMS \CR}{to define scalar adverbs.}
\displx{{\tt : }FINISH \CR}{to exit from dummy procedure.}
\dispe{Now begin the procedure {\tt AVGRMS}:}
\par
\displ{PROC\qs AVGRMS\qs (PIXXY, N, AVG, RMS) \CR}{to enter procedure
                 building mode.}
\displx{{\tt : }SCALAR\qs SUM, SUM2 \CR}{to define more variables.}
\displx{{\tt : }ARRAY VAL(20) \CR}{to define an array.}
\displx{{\tt : }RMS = 0 ; SUM = 0 ; SUM2 = 0 \CR}{to zero some
                 variables.}
\displx{{\tt : }FOR\qs INSEQ =1 TO\qs N \CR}{to begin summing loop.}
\displx{{\tt : }\ind QIMVAL \CR}{to get pixel value at {\tt PIXXY}
                 in image {\tt INNAME} {\tt INCLASS} \hbox{{\tt
                 INSEQ}}.}
\displx{{\tt : }\ind VAL(INSEQ) = PIXVAL \CR}{to save pixel value
                 (placed in {\tt PIXVAL} by {\tt IMVAL}) in our
                 array.}
\displx{{\tt : }\ind SUM = SUM + PIXVAL \CR}{to sum for averaging.}
\displx{{\tt : }\ind SUM2 = SUM2 + PIXVAL * PIXVAL \CR}{to sum for
                 rms.}
\displx{{\tt : }\ind END \CR}{to mark end of {\tt FOR} loop.}
\displx{{\tt : }AVG = SUM / N \CR}{to get average value.}
\displx{{\tt : }IF\qs N\qs$>$\qs1.5 THEN \CR}{to check if {\tt N\ }$ >
                 1$.}
\displx{{\tt : }\ind RMS = SQRT((SUM2 - N*AVG*AVG) / (N * (N-1)))
                       \CR}{to calculate rms if {\tt N\ }$ > 1$.}
\displx{{\tt : }ELSE ; TYPE 'N TOO SMALL', N \CR}{to warn the user.}
\displx{{\tt : }\ind END \CR}{to mark end of {\tt IF} clause.}
\displx{{\tt : }TYPE 'AVG=',AVG,'RMS=',RMS,'AT PIXEL',PIXXY
                    \CR}{ }
\displx{{\tt : }TYPE '  $\#$  ','   VAL   ','   ERROR  '
                    \CR}{to print a heading.}
\displx{{\tt : }FOR INSEQ = 1 TO\qs N \CR}{to begin another loop.}
\displx{{\tt : }\ind SUM = AVG - VAL(INSEQ) \CR}{to get residual.}
\displx{{\tt : }\ind TYPE INSEQ, VAL(INSEQ), SUM \CR}{to print data
                    and residual.}
\displx{{\tt : }\ind END \CR}{to mark end of {\tt FOR} loop.}
\displx{{\tt : }FINISH \CR}{to return to regular {\tt AIPS} mode.}
\dispt{ }{ }
\pd

     The above \Indx{procedure} could be run as follows. First fill in
the adverbs {\tt INNAME}, {\tt INCLASS} and {\tt PIXXY} with the
desired values. Then type:\Iodx{POPS}
\dispt{AVGRMS (PIXXY, {\it n\/}, AVG, RMS) \CR}{ }
\dispe{where {\it n\/} is the number of images to average.  The average
and rms will be calculated and written on the terminal and in the
message file.  This procedure could be used by another procedure.
Suppose we wanted to determine the average and rms of the pixels
within a rectangular area.  If we set {\tt BLC} and {\tt TRC} in the
usual way to define the rectangular boundary, then the procedure:}
\displ{PROC AVGARRAY (BLC, TRC) \CR}{to define new proc.}
\displx{{\tt : }FOR I = BLC(1)\qs TO\qs TRC(1) \CR}{to loop over
                     $x$-coordinate}
\displx{{\tt : }\ind FOR J = BLC(2)\qs TO\qs TRC(2) \CR}{to loop over
                     $y$-coordinate.}
\displx{{\tt : }\ind\ind PIXXY = I , J \CR}{to set pixel coordinates
                     for \hbox{{\tt AVGRMS}}.}
\displx{{\tt : }\ind\ind AVGRMS (PIXXY, N, AVG, RMS) \CR}{ }
\displx{{\tt : }\ind\ind END ; END \CR}{to end $y$ loop, then $x$
                     loop.}
\displx{{\tt : }FINISH \CR}{to end the proc., {\tt RETURN} not
                     needed.}
\dispt{ }{ }
\dispe{will calculate the average value and rms at this array of pixel
locations.  Please note that this is just an example.  The verb {\tt
IMSTAT} performs this function much more efficiently.}

\subsubsections{Special facilities for use in procedures}

When a task or verb encounters an error condition, it sets an error
flag which normally causes \POPS\ to terminate the line or procedure
it was executing.  You can avoid the termination due to task failure
by setting {\tt DOWAIT FALSE} and then doing a {\tt WAIT} on the task.
This does not let your procedure know that an error in the task
occurred, but it does let you ignore any possible error.  Certain
verbs have a second version which sets the {\tt ERROR} adverb, rather
than the automatic termination flag.  These include {\tt CHKNAME}
which checks for the existence of an \AIPS\ file with specified name
parameters, {\tt EGETHEAD} which returns a keyword value from a header
or {\tt ERROR} if the keyword is not present, {\tt EGETNAME} which
returns {\tt ERROR} if the catalog slot is empty, {\tt COPIXEL} which
returns {\tt ERROR} if the coordinate is not in the image, and {\tt
SYSTEM} which returns {\tt ERROR} if the function fails.  Several
fitting verbs, {\tt IMVAL}, {\tt MAXFIT}, {\tt QIMVAL}, {\tt TVFLUX},
and {\tt TVMAXFIT}, return {\tt ERROR} if the fit fails.  Your
procedure can test {\tt ERROR} after these verbs and take appropriate
action.

Numerous verbs return adverb values which may be used in your
procedures.  These include {\tt COPIXEL}, {\tt  COWINDOW}, {\tt
EGETHEAD}, {\tt  EGETNAME}, {\tt EPOCONV}, {\tt  GAMMASET}, the
various {\tt GETNAMEs}, {\tt  GETHEAD}, {\tt  GETTHEAD}, {\tt  GREAD},
{\tt IN2TV}, {\tt  IMDIST}, {\tt  IMPOS}, {\tt  IMSTAT}, {\tt  IMVAL},
{\tt IMMXY}, {\tt  MAXFIT}, {\tt  QIMVAL}, {\tt  REBOX},
{\tt SETSLICE}, {\tt  SETXWIN}, {\tt  TABGET}, {\tt  TK1SET}, {\tt
TKBOX}, {\tt  TKNBOXS}, {\tt  TKSET}, {\tt TKVAL}, {\tt  TKWIN}, {\tt
TV1SET}, {\tt  TVBOX}, {\tt  TVCOLORS}, {\tt  TVDIST}, {\tt  TVFLUX},
{\tt  TVMAXFIT}, {\tt TVNAME}, {\tt  TVPOS}, {\tt  TVSET}, {\tt
TVSTAT}, and {\tt  TVWINDOW}\@.  {\tt GETHEAD} and the table functions
{\tt GETTHEAD} and {\tt TABGET} are particularly useful in
procedures.  The verb {\tt \tndx{NAMEGET}} will convert the {\tt INNAME}
set of adverbs to the values that would be used by a task.

The {\tt RUN} file {\tt VLBAUTIL} provides interesting procedures such
as {\tt MAXTAB} which returns the maximum table number of a specified
table type.  Other procedures in that {\tt RUN} file include ones that
return antenna number corresponding to a specific name and ones that
test whether a data set appears to be new and appears to contain only
VLBA antennas.  {\tt MAXTAB} has been made obsolete by the verbs {\tt
\tndx{GETVERS}} and {\tt \tndx{QGETVERS}} which perform the same
function, returning adverb {\tt MAXVERS} either with or without
messages.

Several tasks now return adverb values.  These values can then be
used for later computation.  These tasks include {\tt CUBIT}, {\tt
GAL}, {\tt FINDR}, {\tt IMEAN}, {\tt IMFIT}, {\tt JMFIT}, {\tt RLDIF},
and {\tt SETFC}.  The first two of these return image fit
parameters, the next two return $uv$ and image statistics, the next
two return the results of Gaussian fitting, {\tt RLDIF} returns the
phase difference between RL and LR polarizations for polarization
calibration, and {\tt SETFC} returns imaging parameters including
number of facets, cell size, and image size.

There is also a verb named {\tt SYSTEM} which allows the \AIPS\ user
to fork a command to the host operating system from within {\tt AIPS}
including from within procedures.  This may be used to delete unwanted
text or FITS files, to run {\tt ftp} to fetch data files from the web,
to run another copy of {\tt AIPS}, or any of a very large number of
other commands.  The verb {\tt \tndx{FILEZAP}} will allow you to
delete non\AIPS\ files without use of the {\tt SYSTEM} verb.

\def\MyH{{\it MyHost\/}}
\def\Ser{{\it Server\/}}
\sects{Remote use of \AIPS}

     \AIPS\ users do not always find themselves seated in front of the
main display screen of the computer which they intend to use for their
data analysis.  \AIPS\ provides facilities for such users which depend
to some extent on the nature and location of the workstation or
terminal at which the user is seated.  Nearly seamless function is
provided to a user seated at a workstation on the local Ethernet well
known to the \AIPS\ installation.  Substantial capabilities are still
available to the user at a more distant workstation capable of
X-Windows display, especially if that workstation can also run \AIPS\
programs such as the TV server and remote tape server.  Even the user
at a simple terminal or workstation, capable of emulating a Tektronix
4010, can still get some interactive displays.  It is only the users
at very simple (and now antique) terminals who will be rather limited
in their interactive use of \AIPS\@.\Iodx{remote user}

\subsections{Connections via X-Windows}

     In the following discussion, we will assume that you need to do
your computing on a computer called \Ser\ and that you are
sitting in front of a workstation called \MyH.

     If \Ser\ and \MyH\ are both on the same local area network and
both have the same byte ordering, then they should have \AIPS\
installed with both of them shown as being at the same \AIPS\
``site.''  In this case, you simply {\tt slogin}, {\tt rlogin}, or
{\tt telnet} into \Ser\ from a window on \MyH\ and issue the {\tt
aips} command as described in \Sec{stAIPS}.  The {\tt aips} command
will recognize that you are coming in from \MyH\ only if the {\tt
\$DISPLAY} environment variable is correct ({\tt \MyH:0})\@.  In that
case, or if you add {\tt tv=\MyH} to the {\tt aips} command line, the
procedure will start the message, graphics, and TV servers on \MyH\ if
needed.  If you want to share data areas between the two computers,
you may add a {\tt da=\MyH} on the command line and {\tt AIPS} will
run with all data areas from both machines. (The disk systems must be
auto-mountable between the two computers.)  There are two verbs
within  {\tt AIPS} which will allow you the equivalent of {\tt da=}.
They are {\tt \tndx{ADDDISK}} which will add the disks of a selected
computer to the current list of data disks and {\tt \tndx{REMDISK}}
which will remove the disks of a selected computer from the current
list.  The {\tt aips} command also lets you select the most convenient
printer within your local area network for use in your \AIPS\ session.
Other forms of data transfer, including magnetic tapes, will be
discussed later.\Iodx{remote user}

     If \Ser\ and \MyH\ have different byte orders or are not both on
the same local area network, then they cannot be at the same \AIPS\
site.  If both machines have \AIPS\ installed and the versions are
compatible, then you may run on \Ser\ with \MyH\ treated as a ``guest.''
Again, {\tt slogin}, {\tt rlogin}, or {\tt telnet} into \Ser\ from a
window on \MyH.  Make sure that the environment variable {\tt
\tndx{DISPLAY}} on \Ser\ is set to {\tt \MyH:0} and that \Ser\ is
mentioned in your {\tt .rhosts} file on \MyH.  Then issue the usual
{\tt aips} command. You do not have to give the {\tt tv=} option, but
you may give {\tt tv=\MyH} if you wish.. This will start the message,
graphics, and TV servers on \MyH\ if needed.  If the servers fail to
start and messages such as ``{\tt Cannot start remote TV
servers}$\ldots$'' appear, then you must start the servers using the
{\tt aips} command on \MyH.  The displays will work without restarting
{\tt AIPS} on \Ser.  Thereafter, give the {\tt aips} option {\tt tvok}
to \Ser\ (rather than {\tt tv=}) to suppress the annoying messages.
There is no drawback to being a guest TV; all catalogs and device
information are now maintained by {\tt XAS} itself.  Since the display
refreshing is handled locally by programs running in \MyH, this level
of connection supports nearly full interactivity including such
demanding displays as {\tt TVBLINK} and {\tt TVMOVIE}\@.

      If \MyH\ does not have \AIPS\ installed, then you may run the
message, graphics, and TV servers on \Ser, with the X-Windows {\tt
\$DISPLAY} set to {\tt \MyH:0}\@.  You may do this with internet
sockets, but this ties up the one instance of the servers allowed to
use such sockets.  The socially acceptable method uses local Unix
sockets so that only current \AIPS\ session(s) on \Ser\ may talk to
the windows in \MyH.  You must ask for this explicitly, setting {\tt
tv=local}.   This mode of operation is not encouraged since the
display refreshing has to be transmitted over the network, making some
of the interactive displays too slow to be useful.  Nonetheless, there
are circumstances in which this mode of operation is the only one
available.  You will have to add \Ser\ as an allowed X host ({\tt
xhost +\Ser}) to use this option.  See {\us HELP AIPS \CR} for more
information on ``local'' TVs which, among other things, allow for
multiple TVs on a single display screen.

\subsections{Connections to a terminal}

     You may do some interactive \Aips ing if your workstation window
is able to emulate a Tektronix 4010 terminal, or you are at a terminal
capable of this emulation.  (Note that most {\tt xterm} displays may be
switched between a ``Tek mode'' and the normal ``VT mode'' by pressing
the {\tt Control} key and the middle mouse button.)  To operate in
this mode, log in to \Ser\ from your terminal or workstation window
and start {\tt AIPS} with the command-line option {\tt REMOTE}\@.
This option will disable all TV functions, will cause all task
messages to come to your terminal or window, and will cause any
graphics (``TK'') displays to be sent to your terminal or window.  You
may display an ``image'' by creating a contour drawing with {\tt CNTR}
and then displaying the plot file with {\tt \tndx{TKPL}}\@
Interactive cursor verbs and procedures such as {\tt TKXY}, {\tt
TKPOS}, and {\tt TKWIN} may then be used.  The old 4010 Tektronix
display mixed plotting and text in a less than elegant fashion which
is slavishly honored by most emulations.  This is unfortunate, but
usually does not prevent the display from being used for simple
position selection and the like.

     The \AIPS\ task {\tt \tndx{TXPL}} is a powerful tool for remote
users without any, or correct, Tektronix 4010 emulation.   It reads an
extension file of type {\tt PL} and translates the graphics commands
in that file to an alphanumeric display for a ``dumb'' terminal.  {\tt
TXPL} may be exactly what you need for \AIPS\ applications that depend
on scanning the {\it shape\/} of a plot rather than its fine detail.
Common examples are viewing the shape of visibility functions produced
by {\tt UVPLT} (to guide self-calibration or to diagnose interference)
or examining calibration solution plots from \hbox{{\tt SNPLT}}. {\tt
TXPL} can also usefully interpret simple contour plots or even grey
scales(!) for a remote user.  It is often much faster to use {\tt
TXPL} to diagnose the state of your \AIPS\ data processing over a
low-bandwidth link than to use {\tt TKPL} to execute a stream of
Tektronix graphics instructions (even if you have full Tektronix 4010
emulation).\Iodx{remote user}

%\subsections{Remote data connections}

%     Like the message, graphics, and TV servers, there is also a
%remote data server in \AIPS\ in the form of a remote ``tape'' d\ae mon
%called \hbox{{\tt \tndx{TPMON}}}.  All computers that run \AIPS\ run a
%copy of {\tt TPMON} to serve FITS-disk files plus a copy of {\tt
%TPMON} for each real \AIPS\ tape device on the computer.  Some
%computers start these {\tt TPMON}s when the are booted while others
%wait until someone runs {\tt AIPS} on them or orders the tape servers
%to run by using the {\tt tp=} option for the computer from some other
%computer (\Sec{stAIPS}).  If you are computing on the remote \Ser\ and
%wish to use an \AIPS\ tape drive on your computer, type on \Ser:
%\dispx{{\tt \%\qs} aips tp=\MyH\CR}{to start {\tt AIPS} on
%            \Ser\ and to start the {\tt TPMON}s on \MyH.}
%\dispe{Then, within {\tt AIPS}, enter:}
%\dispt{\tndx{REMHOST}\qs '\MyH' \CR}{to specify your computer as the
%           tape server.}
%\dispt{\tndx{REMTAPE}\qs $n$ \CR}{to specify the $n^{\uth}$ \AIPS\
%      tape device on \MyH.}
%\dispt{INTAPE\qs $m$ \CR}{to specify a \Ser\ tape number one or two
%           higher than the number of real tape devices on \Ser.  These
%           match those shown for {\tt REMOTE} as you started {\tt
%           AIPS}; see \Sec{magtape} for an example.}
%\dispt{\tndx{MOUNT} \CR}{to mount the remote tape.}
%\dispe{You may then use the remote tape as you would any other tape in
%\hbox{\AIPS}.  See \Sec{magtape}, \Sec{uvtape}, \Sec{imagtape}, and
%\Sec{displtape} for examples of normal tape usage.\iodx{REMOTE tapes}
%The verb {\tt \tndx{TAPES}} is even able to use {\tt TPMON} to tell
%you what tape devices are available on the remote host.}
%
%     If you have a \indx{FITS-disk} file (\Sec{fitsdisk}) on \MyH\
%which you wish to read into \Ser, then you may set {\tt DATAIN} to
%{\tt \MyH::{\it logical\/}:{\it filename\/}}.  Note that double colons
%connect the host name to the logical name for the disk area and a
%single colon connects the logical name to the name of the file within
%that disk area.  Note also that the logical name must be one known to
%{\tt TPMON} when it is started.  Put your file in a standard area such
%as {\tt FITS}, which is known to all of \AIPS, or create the logical
%variable in a window on \MyH\ (\eg\ with {\tt setenv} or {\tt export}
%--- see \Sec{textfile})and then start the {\tt TPMON}s from that
%window with the {\tt aips} command.  Similarly, you may use {\tt
%FITTP} to write a FITS-disk file onto \MyH\ of an \AIPS\ image or \uv\
%data set. Enter {\tt DATAOUT} with the form shown above for \hbox{{\tt
%DATAIN}}.
%
%     Unlike the display servers, {\tt TPMON} can read and write disk
%files and magnetic tape devices.  Given the hostile environment now
%found on the Internet, this poses a security problem.  Therefore,
%{\tt TPMON} checks every connection request to see if the remote
%computer has permission to use its services.  To do the remote tape
%operations described above, you must have the \AIPS\ Manager for \MyH\
%alter the appropriate files to give \Ser\ permission to use the {\tt
%\tndx{TPMON}}s on \MyH.  This should have been done already if \Ser\
%and \MyH\ are on the same \AIPS\ ``site'' or are routinely used
%together.
%
%\vfill\eject
\subsections{File transfer connections}

     The techniques discussed above apply to many computer
configurations and to most tools within \hbox{\AIPS}.  They do not,
however, handle the outputs of printing and plotting tasks.  Nor do
they provide much support for small computer systems that have no
\AIPS\ capability of their own.  In such cases, the results of
your computations will need to be written onto disk on \Ser\ and then
transferred over the network to \MyH.

     \AIPS\ does not support remote printers explicitly.  However, all
\AIPS\ tasks and verbs which generate printer output support the {\tt
\tndx{OUTPRINT}} adverb.  With this adverb, you may specify a disk
text file to receive the printer text.  If you specify the same file
for successive printer verbs or tasks, the outputs will be
concatenated. (\AIPS\ batch jobs do this automatically to concatenate
all printer displays for the job.)  You may then copy the text file to
\MyH\ for editing, printing, or whatever.  If you wish to print the
whole file on a \indx{PostScript} printer on \MyH, you may wish to run
{\tt F2PS} on the text file on \Ser\ and copy the result to \MyH.
\AIPS\ provides a ``filter'' program to convert plain (or Fortran)
text files to PostScript for printing on PostScript printers.  The
command
\dispx{{\tt \$\qs} \tndx{F2PS}\qs -{\it nn\/}\qs {\tt <}\qs {\it
        file\/}\qs {\tt >} \qs {\it outfile\/}}{ }
\dispe{will convert text file {\it file\/} to PostScript format file
{\it outfile\/}.  The parameter {\it nn} is the number of lines per
page used inside \AIPS; use 97 for a small font in ``portrait'' form
or 61 for a larger font in ``landscape'' form.}

     The \AIPS\ task {\tt LWPLA} also has an option to write its
output to a disk file in encapsulated PostScript form using the {\tt
OUTFILE} parameter.  Similarly, {\tt TVRGB} and {\tt TVCPS} use the
same adverb to write PostScript text files containing their
three-color displays.  Numerous other \AIPS\ tasks offer the option to
write details of the operation to a text file specified with
\hbox{{\tt OUTTEXT}}.  These include {\tt SLICE} (slice), {\tt IMEAN}
(histogram), {\tt GAL} (fit results), {\tt POSSM} (spectrum), {\tt
FRPLT} (spectrum), {\tt HITEXT} (history), {\tt UVCRS} (\uv-plane
crossings), {\tt CONPL} (convolving functions), etc.

     \indx{FITS-disk} files may be written with {\tt FITTP} and {\tt
FITAB} and read with {\tt FITLD}, {\tt UVLOD} and \hbox{{\tt IMLOD}}.
For efficiency reasons, these are binary files rather than the text
files produced by everything else.  \AIPS\ table (and optionally plot)
files will have their contents transferred by these tasks along with the
main data files.  To put an \AIPS\ table in a disk file in text form,
use {\tt \tndx{TBOUT}} to write a simple text file or {\tt \tndx{EXTAB}}
to write a file suitable for database and spreadsheet programs.  Files
in the form written by {\tt TBOUT} may be read back into \AIPS\ with
{\tt \tndx{TBIN}}\@.\Iodx{remote user}

     To transfer the FITS-disk files and text files between \MyH\ and
\Ser, some standard network file transfer must be used.  For
example, use {\tt \tndx{ftp}} on \MyH\ with
\dispx{{\tt \%\qs} cd {\it MyArea\/} \CR}{to switch to the disk area
               on \MyH\ used for your files.}
\dispx{{\tt \%\qs} ftp \Ser\ \CR}{to start {\tt ftp} to the
               remote system.}
\dispx{{\tt Name (\Ser :$\ldots$):\qs} {\it loginame\/} \CR}{to
               log in to account {\it loginame\/}.}
\dispx{{\tt Password:\qs} {\it password\/} \CR}{to give the account's
               password.}
\dispx{{\tt ftp>\qs} cd \qs {\it directory\/} \CR}{to change to the
               {\it directory\/} name containing the file on \Ser.}
\dispx{{\tt ftp>\qs} binary \CR}{to allow reading of a binary file ---
               required for FITS-disk files, okay for text files.}
\dispx{{\tt ftp>\qs} hash \CR}{to get progress symbols as the copy
               proceeds --- a good idea for large files.}
\dispx{{\tt ftp>\qs} put \qs {\it filename\/} \CR}{to send {\it
               filename\/} from \MyH\ to \Ser.}
\dispx{{\tt ftp>\qs} get \qs {\it anothername\/} \CR}{to send {\it
               anothername\/} from \Ser\ to \MyH.}
\dispx{{\tt \tndx{ftp}>\qs} quit \CR}{to exit from {\tt ftp}.}
\dispe{The files should then be in the desired directories.  You may
have to rename them, however, to a name in all upper-case letters
unless you use the ``trick'' mentioned in \Sec{textfile}.
\Iodx{remote user}  The secure copy ({\tt scp}) is preferable if you
have a secure connection set up.  The files may be compressed with
{\tt gzip} before copying and then uncompressed with {\tt gunzip} at
the other end.  This is particularly effective on text files and
images written by {\tt FITAB} with quantization.}

\sects{Moving data to a new computer}

Lucky users who get a new computer frequently ask ``how do I move my
data to my new, better machine?''  The easiest thing to do is first to
install \AIPS\ on the new computer.  Create at least as many data
areas on the new machine as there were on the old.  If you are moving
between machines of the same byte order (same architecture or Solaris
to Mac PPC, Linux to Mac Intel, or vice versa), then do a network {\tt
scp} copy (or easier yet a cp from cross-mounted disks) to move all
data files from \AIPS\ disk 1 on the old machine to \AIPS\ disk 1 on
the new machine.  Repeat for the other \AIPS\ disks.  Note that \AIPS\
disk 1 is different; it contains message, {\tt SAVE}/{\tt GET}, and
other special files as well as normal data files.  The other data
areas may be rearranged if you want, but do not copy two old data
areas to one new data area.  That will cause extreme confusion and
loss of data.  Now you are ready to resume {\AIPS}ing.

But if you are moving from Solaris or Mac PPC to Linux or Mac Intel,
or vice versa, then you have more to do.  Mount the \AIPS\ disks of
the old machine from the new machine if possible.  Otherwise copy the
data from the old machine to new, temporary data areas on the new
machine (not the new \AIPS\ data areas) being careful to keep each
data area separate.  Outside of {\tt AIPS}, setup the \AIPS\
environment:
\dispx{{\tt \%\qs} cd \$AIPS\_ROOT \CR}{to move to the root of all
                 \AIPS\@.}
\dispx{{\tt \%\qs} source LOGIN.CSH \CR}{to set the basic environment
                 under C-shell, or}
\dispx{{\tt \%\qs} . LOGIN.SH \CR}{to set the basic environment
                 under bash --- note the dot.}
\dispx{{\tt \%\qs} \$CDTST \CR}{to set the full environment.}
\dispx{{\tt \%\qs} RUN \Tndx{REBYTE} \CR}{to run a format converter
                 once for each \AIPS\ data area.}
\dispe{Answer the question about range of user number ({\tt 0 0 \CR}
will get you all possible numbers) and then enter the full pathname of
the input (old) data area and the corresponding new \AIPS\ data area.
The program will convert the format of all files.  The program ---
barring software error --- will produce correct output for almost all
files.  There is a small danger that the {\tt SAVE}/{\tt GET} and
{\tt TPUT}/{\tt TGET} files may have some errors since it is way
beyond the scope of {\tt REBYTE} to understand the format of these
files.}

The traditional way to move between computer architectures is more
time consuming.  On the old computer, use procedure {\tt
\tndx{WRTDISK}} to write a data area out as FITS files.  The FITS file
names encode the old \AIPS\ disk and catalog numbers so that more than
one disk can be written into the same FITS area.  Copy the files to
the new computer (or better yet, cross mount the disks) and then use
procedure {\tt \tndx{READISK}} on the new computer to read them into
the new data area(s).  These procedures are obtained via a {\tt RUN
\tndx{WRTPROCS}}\@.  Plot and slice files no longer are lost in this
process if you set {\tt DOPLOT} to true in {\tt FITTP} and {\tt FITAB}
starting in {\tt 31DEC25}\@.  You can move the {\tt SAVE}/{\tt GET}
files with the verb {\tt \tndx{SG2RUN}} which converts an {\tt SG} file
to a text file which can be {\tt RUN} on the new computer and then {\tt
SAVE}d.  This traditional method works fairly well and can deal with the
new computer having fewer \AIPS\ data areas than the old one.  It also
offers the opportunity to do a probably overdue backup of your data.
However, the loss of message files and the added overhead in disk space
may matter to you.

\vfill\eject
\Sects{Adding your own tasks to \AIPS}{owntask}

     This Section is a brief guide for the user who wants to modify an
existing \indx{task} in \AIPS\ or to write a new task.  While it is
difficult to write an \AIPS\ task from scratch, \AIPS\ contains
several template tasks that are designed to hide most of the work from
the ``occasional'' programmer.  Anyone familiar with FORTRAN and a
little of the system services of their local computer should be able
to add convenient tasks to their local version of \AIPS\ with a little
practice and patience.  The growing use of binary installations makes
this more difficult since local sites are unlikely to have the
relevant compilers.

\subsections{Initial choices to make}

     The simplest way to write an \AIPS\ task is to modify one of the
four template tasks, {\tt TAFFY}, {\tt CANDY}, {\tt FUDGE}, {\tt OFUDG},
or \hbox{{\tt UVFIL}}.  These tasks handle the \AIPS\ I/O, contain
extensive documentation, need to be modified in only a few
well-defined places, and can be easily interfaced to user subroutines.
They are limited in their ability to handle many input and output
images, however, and generally operate on one image row or one
visibility point at a time.  Softening of these limitations will be
discussed in \Sec{template}.\iodx{paraform tasks}

{\tt \tndx{TAFFY}} ---  This template task reads an existing image in
\AIPS\ line by line, modifies the line of data as desired and then
creates and writes the modified image in \hbox{\AIPS}.  This template
task might, for example, be used to blank pixels in an input image in
some specified manner.

{\tt \tndx{CANDY}} ---  This task is similar to {\tt TAFFY} except the
input data are contained in an auxiliary file which is FORTRAN
readable and outside \hbox{\AIPS}.  The task can transfer an image in
any reasonable format outside \AIPS\ into the \AIPS\ data structure.

{\tt \tndx{FUDGE}} --- This template task reads an existing \AIPS\
\uv\ database optionally applying calibration, editing, and data
selection, modifies the results point by point, and then creates
and writes this modified output \uv\ database in the \AIPS\ catalog.
This template task might, for example, be used to modify a \uv\ data
base for which the time parameter has been incorrectly written.
{\tt \tndx{OFUDG}} is an older version of {\tt FUDGE} which omits
all the complications of the calibration system.

{\tt \tndx{UVFIL}} --- This task is similar to {\tt FUDGE} without
calibration and editing, except that the input \uv\ data are contained
in one or two auxiliary files, which are FORTRAN readable and outside
\AIPS\@.  The task is useful for translating visibility data in an
arbitrary format into an \AIPS\ cataloged \uv\ data set, or for
computing a \uv\ data set from model sources.

     If you wish to make a minor change in an existing \AIPS\ task, it
will be simpler to copy the \AIPS\ task itself and modify it as
needed.  For example, if you wanted to add a option in {\tt COMB} to
combine two input images in a new way to obtain a resultant image, it
would be better to start with {\tt COMB} itself than with one of the
templates.  However, non-trivial changes to major tasks will require a
careful look at the code, which is generally well documented and
segmented.

     Changes to tasks that make plots and/or use the TV and other
graphics devices can be tricky, but are useful sometimes.  Changes to
imaging and deconvolution software should not be attempted unless
the changes are almost trivial.  Modifying existing verbs or creating
new ones require you to find which {\tt AU$xx$.FOR} routine is
involved and then require the entire {\tt AIPS} program to be
re-linked.  {\it Going\/} \AIPS\ describes some of the considerations.
The new pseudo-verbs {\tt \tndx{VERB}} and {\tt \tndx{PSEUDOVB}} allow
you to update your {\tt AIPS} vocabulary using your own procedure
rather than by changing the supplied vocabulary files and executing
{\tt POPSGN} as described in {\it Going\/} \hbox{\AIPS}.  In all cases,
do not put your modified code into the standard \AIPS\ code areas
unless your local \AIPS\ Manager agrees and has made a backup copy of
the original code and executables.\iodx{Going AIPS} Such modified
files may well disturb the \AIPS\ updates done by the so-called
``Midnight Job.''

\subsections{Getting started}

    Even if you have special privileges in \AIPS, it is wise to
generate and link new code in your own user directory rather than in
your installation's designated local \AIPS\ directory.  After the code
has been written and tested, check with your local \AIPS\ Manager
about installing it in a public area. Decide which template
\Indx{task} or other \AIPS\ task you want to modify, then follow these
instructions after logging into your private area.\iodx{paraform
tasks}

    Under Unix
\dispx{{\tt \%} source\qs /AIPS/LOGIN.CSH \CR}{to get the basic \AIPS\
      system logicals under a c-shell, or}
\dispx{{\tt \%} .\qs /AIPS/LOGIN.SH \CR}{to get the basic \AIPS\
      system logicals under a korn, bourne, or bash shell.  (These
      assume that your \AIPS\ system home directory is called
      \hbox{{\tt /AIPS}}).}
\dispx{{\tt \%} \$CDTST (or \$CDNEW) \CR}{to set up the logical
      assignments for programming.}
\dispx{{\tt \%} PROG\qs {\it TASK\/} \CR}{to locate the task called
      \hbox{{\it TASK}}.}
\dispx{{\tt \%} LIBS\qs \${\it AREA\/}\qs $>$\qs {\it NTASK\/}.OPT
      \CR}{to create a file of linking information for a task found in
      area {\it AREA\/}, \eg\ {\tt APLPGM} for {\tt OFUDG} and {\tt
      TAFFY}, {\tt APGNOT} for {\tt FUDGE}, {\tt CANDY} and {\tt UVFIL},
      {\tt YPGM} for {\tt IMEAN}, etc.}
\dispx{{\tt \%} cp\qs \${\it AREA\/}/{\it TASK\/}.FOR\qs {\it
      NTASK\/}.FOR \CR}{to copy code for {\it TASK\/} into your area
      and to give it a new name ($\leq 5$ letters).}
\dispx{{\tt \%} cp\qs \$HLPFIL/{\it TASK\/}.HLP\qs {\it NTASK\/}.HLP
      \CR}{to copy and rename the inputs/help file for the task.}
\dispx{{\tt \%} setenv\qs MYAIPS\qs `pwd` \CR}{to define {\tt MYAIPS}
      (must be uppercase) as your disk area for \AIPS\ programs, or}
\dispx{{\tt \%} export\qs MYAIPS=`pwd` \CR}{to define the {\tt
      MYAIPS} environment variable under korn, bash, and bourne
      shells.}
\pd

\subsections{Initial check of code and procedures}

     Before modifying the \tndx{task} in any way, it is wise to
compile, link and execute the unchanged task to check that the
original code is sound and that all of the \AIPS\ logical assignments
have been properly set.  The duplicated \AIPS\ task should run
identically to the original; the template tasks are set up to
duplicate the input data set with no changes and default parameters.
In this way errors or other problems associated with the generation of
new tasks can be found and corrected before getting into the quagmire
of bugs that you are about to add.  Note that {\tt CANDY} and {\tt
UVFIL} require external data files and are therefore not so easily
checked.

     One change is needed in the FORTRAN program before checking.  In
the main program, about 60 lines down, there is a data statement which
identifies the task.\iodx{paraform tasks}
\displx{{\tt DATA PRGM /'{\it TASK\/} '/}}{}
\dispe{Change this to}
\displx{{\tt DATA PRGM /'{\it NTASK\/'}/}}{}
\dispe{The maximum number of characters in a task name is five and the
{\tt DATA} statement must be in the above form.  There is no need to
change the help file yet, as long as it is named \hbox{{\tt
NTASK.HLP}}.}

     To compile and link the task, type:
\dispx{{\tt \%} COMLNK\qs {\it NTASK\/}\qs {\it NTASK\/}.OPT \CR}{}
\dispe{To compile the task for debugging, add the {\tt DEBUG NOOPT}
options to the {\tt COMLNK} line.  There should be no error messages
and no significant warnings.}

     After successful compilation and linking, try executing the task.
Under Unix, stay logged in to your area.  To initiate the {\tt AIPS}
program, type:\iodx{paraform tasks}
\dispx{{\tt \%} aips \CR}{or}
\dispx{{\tt \%} aips\qs debug \CR}{to use the debugger (\eg\ {\tt dbx})
            on tasks compiled with the {\tt DEBUG} option.  You will
            have to tell the procedure which debugger you want and
            that you do not want to start {\tt AIPS} itself under that
            debugger.}
\dispe{Your \AIPS\ Manager may have to make some arrangements for you
to activate \AIPS\ from your login. Once you have started \AIPS, type}
\dispt{VERSION\qs 'MYAIPS' \CR}{to specify the location of inputs and
            help information and of the task executable.}
\dispe{Set up the input parameters, then}
\dispt{INP \CR}{to review the input parameters.  You should be told
            {\tt AIPS 1: Found in Version=MYAIPS} at the start of the
            inputs display.  If not, there is something wrong with the
            logical or task name or the location of the inputs/help
            file.}
\dispt{GO \CR}{to run the task.  The {\tt Found $\ldots$} line should
            appear again.}
\pd

\subsections{Modifying an \AIPS\ task}

     If you are modifying an existing \tndx{task}, the only ground
rules are to read the task carefully and note the locations where
changes must be made.  Unlike the template tasks which are organized
so that additional code need be inserted in only one or two places, an
\AIPS\ task may need revisions in a variety of places.  Some
guidelines are:
\xben
\Item Change the data statement {\tt DATA PRGM $\ldots$} near
    the beginning of the program and the {\tt PROGRAM} statement at
    the very beginning, if you have not already done this.
\Item Make changes in the introductory text which describes the
    task.  This is particularly important if you are adding or
    removing adverbs.
\Item The subroutine {\tt GTPARM} obtains the adverb values from
    the input table in order.  If you add or subtract adverbs, change
    {\tt INPRMS}, the amount of input information.  Be careful in the
    translation of the adverbs, which are usually listed in a {\tt
    COMMON} named {\tt /INPARM/}.
\Item Change code as desired.  Try to modify {\tt HI}story file
    entries as well.
\Item Liberally sprinkle {\tt PRINT} statements in crucial places
    to help debug the program.  If much of the new code can be put in
    a subroutine, write and debug the subroutine outside \hbox{\AIPS}.
    Then, add it to the \tndx{task}.
\Item Revise the file \hbox{{\tt NTASK.HLP}}.  At least, change
    all references to {\tt TASK} to {\tt NTASK}!  If there are any
    changes in the adverb list, look at these changes carefully.
    Further changes in the {\tt HELP} and {\tt EXPLAIN} portions of
    the file may be needed to document your work for for others and
    for yourself at a later date.
\Item Compile and link the modified task following the
    instructions in the previous section.  When it compiles and links
    without errors, try it out in \hbox{\AIPS}.
\xeen

\vfill\eject
\Subsections{Modifying an \AIPS\ template task.}{template}

     The template tasks are:

\xben
\Item {\tt TAFFY} --- modifies an existing image file and
    writes a new image.
\Item {\tt CANDY} --- writes a new image.  Input data from
    outside \hbox{\AIPS}.
\Item {\tt FUDGE} --- modifies an existing \uv\ database and
    writes a new database with calibration, flagging, source selection,
    etc.
\Item {\tt OFUDG} --- modifies an existing \uv\ database and
    writes a new database.
\Item {\tt UVFIL} --- writes a new \uv\ database taking input data
    from outside \hbox{\AIPS}.
\xeen

     These tasks are described in detail in Chapter 2 of {\it Going\/}
\hbox{\AIPS}. The template tasks and the code for each are extensively
documented there, so only the major points are discussed here.
\iodx{paraform tasks}\iodx{Going AIPS}\iodx{task}

     {\tt \tndx{TAFFY}} reads a selected subset of an image, one row
at a time, to a user interface subroutine \hbox{{\tt DIDDLE}}.  An
output image is created, cataloged and filled with values calculated
in {\tt DIDDLE} (or attached subroutines).  The dimensionality of the
output image need not be the same as the input image.

\xben
\Item If the output image has identical dimensions to the
    input image, and an output image row can be generated from each
    input image row, then {\tt TAFFY} is relatively straight-forward
    to use and the accompanying documentation should suffice.
\Item {\tt TAFFY} has the option of deferring the writing of an
    output row until some number of input rows have been read.  This
    would allow the output to depend on some function of several, or
    even all, input rows.  Examples would include smoothing in $x$ and
    $y$ and other sorts of spatial filtering.
\Item It is possible to handle several input images and several
    output images with {\tt TAFFY} by using multi-dimensional images
    and the axis transposing task, \hbox{{\tt TRANS}}.  Suppose you
    want to calculate the spectral index from a set of four images.
    First, use {\tt \tndx{FQUBE}} to put the four images into one
    data cube.  ({\tt FQUBE} lets you avoid re-defining the frequency
    axis as {\tt MCUBE} would require.)  Then, transpose the cube so
    that the frequency axis is first with right ascension and
    declination as the second and third axes.  Use this image as the
    input to {\tt TAFFY} and use {\tt CPARM} to specify the frequency
    values.  Each input row will then be the intensity at a pixel for
    the four frequencies --- from which the spectral index and other
    parameters can be calculated.  The output dimension can be
    specified arbitrarily.  For example, you might want to write out
    the spectral index, the error, the curvature and the flux
    intercept at some fiducial frequency.  When the task has
    completed, transpose the output cube so that the celestial
    coordinates are again the first two axes and the spectral index
    and friends are the third axis.
\Item Subroutine {\tt NEWHED} may be modified to require certain
    axis types, operation codes, etc.  It must be used to change the
    output image dimensions if they are not to be the same as the
    input.  An option to omit from the output image the first input
    axis is available and must be selected in \hbox{{\tt NEWHED}}.
\Item If you can write and debug outside \AIPS\ any subroutines
    that {\tt DIDDLE} will call in calculating the output image, you
    may speed up the debugging of your algorithms.
\xeen

     {\tt \tndx{CANDY}} lets you create an image one row at a time.
Input information is obtained through a file which is external to
\hbox{\AIPS}.

\xben
\Item Subroutine {\tt NEWHED} shows an example of how the
    external file may be defined and how it can be used. The first few
    records of the external file should contain information for
    defining the header of the output image and updating the
    appropriate catalog blocks.  The pointers to the \AIPS\ catalog
    are given in Chapter 5 of {\it Going\/} \hbox{\AIPS}.\iodx{Going
    AIPS}
\Item The subroutine {\tt MAKMAP} reads further records from the
    external file until a full row of the output image is obtained.
\Item Many adverbs are built into \hbox{{\tt CANDY}}.  If you
    need more or wish to change them, read the information at the
    beginning of subroutine \hbox{{\tt CANIN}}.
\xeen

     {\tt \tndx{OFUDGE}} reads an existing \uv\ database point by point
and creates a new \uv\ database with the modified data.  It can easily
be used to make simple changes in a \uv\ database; for example, if the
$u$, $v$, or $w$ terms are to be recalculated, if all phases are to be
changed in sign, etc.  {\tt \tndx{FUDGE}} does the same but with the
full set of calibration, flagging, source selection, etc.~adverbs.

\xben
\Item If the output data set has different dimensions than the
    input data set (\eg\ by combining several spectral-line channels),
    changes must be made in the subroutine \hbox{{\tt FUDGIN}}.
\Item To combine several input data points, use the task {\tt UVSRT}
    to put the data points adjacent in the file.
\Item If you wish to calculate quantities from an input \uv\ data
    set without creating an output file, use this task.  In the
    subroutine {\tt DIDDLE} set {\tt IRET = -1} to avoid writing an
    the output \uv\ data set.
\xeen

     {\tt \tndx{UVFIL}} reads input from one or two FORTRAN-readable
files which are outside \AIPS\ to create, catalog, and fill a \uv\
database into \hbox{\AIPS}.  This task is useful for transcribing \uv\
data in an arbitrary format into an \AIPS\ database.
\iodx{paraform tasks}\iodx{task}
\xben
\Item The task code has copious notes to help the user.  The
    first auxiliary file should contain header information about the
    observations and the telescopes.  This file is read in the
    subroutine \hbox{{\tt NEWHED}}.
\Item The second auxiliary file contains the actual \uv\ data in
    some format and it is converted into an \AIPS\ \uv\ database,
    point by point, in the subroutine \hbox{{\tt FIDDLE}}.  The
    comments are extensive and an example is given in the code.
\xeen

\subsections{Further remarks}

\xben
\Item Try to use the \AIPS\ coding standards as described in
    {\it Going\/} \hbox{\AIPS}. \iodx{Going AIPS} This will make your
    code more readable and more portable.  It will also save other
    \AIPS\ programmers lots of work if your new task comes into
    general use.
\Item Declare all variables that you use.
\Item While debugging, use the FORTRAN {\tt PRINT *, ...}
    statement in your code to obtain temporary output on your terminal
    during execution.  If you want more permanent output, use the
    \AIPS\ message file facilities with the appropriate message level
    (4 is recommended for information, 6 for warnings, 8 for
    errors).
\Item You may use a debugger (such as {\tt dbx}) on \AIPS\ tasks
    by specifying {\tt DEBUG} to the {\tt COMLNK} and {\tt aips}
    procedures.  Inside {\tt AIPS}, set the ``hidden'' adverb {\tt
    SETDEBUG} to 0 for normal operation and to 20 to run tasks with
    your specified debugger.
\xeen

%\sects{Additional recipes}
