\input COOK82.MAC
\def\chapt{12}
\tsect{12.  \AIPS\ FOR THE MORE SOPHISTICATED USER}

     The program {\tt AIPS} uses the {\ss POPS\/} language to communicate
with you. {\ss 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 {\ss POPS\/} to take
full advantage of the powerful features of {\ss AIPS}. Sections 12.1 to
12.8 therefore provide more detail about {\ss POPS}.

     The remaining sections describe some advanced features of \AIPS\
itself. Section 12.9 points out some important, but often neglected,
attributes of the most-used \AIPS\ verb --- {\tt GO}.  Section 12.10
briefly describes the \AIPS\ batch system. Section 12.11 describes a few
features of particular interest to ``remote users" of \AIPS\ systems.
Section 12.12 describes how to add your own tasks to \AIPS.

\subsect{12.1.  {\tt AIPS} syntax}

     Some niceties of using {\ss POPS\/} syntax in \AIPS\ are:

\hanstart{50pt}
\enumerate{1}{More than one expression can be put on a line.  These
   expressions must be separated by a semicolon ( {\tt ;} ).  Exceptions
   are {\tt RESTORE}, {\tt GET}, {\tt RUN} and a few other ``pseudoverbs''
   which, with their arguments, must stand alone.  For example,
   {\us GET\qs APMAP ; INDISK = 1 \CR} will ignore the {\us INDISK = 1}.
   When in doubt, see the {\tt HELP} files for the pseudoverb to find the
   restrictions on its use.}
\enumrnext{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 usually suffice.  This ``minimum matching'' has been
   exploited throughout this \Cookbook.}
\enumrnext{The parameter variables in {\tt AIPS} are called ``adverbs.''
   They are assigned values by the equals verb ( {\us =} ), \eg\
   {\us INTAPE = 2 \CR}.  The equals sign may usually be replaced by a
   space.  The exception arises when the variable on
   the left is a subscripted 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}).}
\enumrnext{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 \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 \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}.}
\enumrnext{Adverbs can be used in arithmetical expressions or set equal to
   other adverbs, \eg\ {\us OUTNAME = INNAME ; OUTSEQ = 2.5 * INSEQ + 3}.}
\enumrnext{Both upper and lower case letters may be entered by the user,
   but adverb character string values are converted to upper case
   before being stored and used by {\tt AIPS}.}
\par\hanend

     As an example, these shortcuts allow the following {\tt AIPS} command
sequence:
\dispt{INNAME '3C138' \CR}{ }
\dispt{INCLASS 'IMAP' \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 'imap' ; 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

\subsect{12.2.  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), your user
identification number, and the following three parts of the
image designation:

\hanstart{90pt}
\enumerate{1}{Name --- A string of up to 12 legal characters.}

\enumrnext{Class --- A string of up to 6 legal characters.}

\enumrnext{Seq --- A number between 0 and 9999.}

\hanend
\dispe{Each of these parts corresponds to separate input adverbs called
{\tt INNAME}, {\tt INCLASS}, and {\tt 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 OUTNAME\qs '\qs' \CR} means ``use the
actual {\tt INNAME}".  {\us 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 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 ``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.

     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 such a
file and it contains directory information for all images and \uv\ data
sets for all users on the disk pack.  On most systems, each user is
assigned their own catalog file on each disk.

     Extension files may be associated with any image data file.  Each image
can have (in principle) up to ten types of extension files and up to 255
``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 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 values.  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 subarray in up to
seven dimensions.  Whenever a sub-image is taken from an image, the pixel
designation of any image element will usually change.

\subsect{12.3.  {\tt AIPS} language}

     {\tt AIPS} contains a basic set of symbols and keywords which are
needed for facility in the language, as well as the symbols needed by
the application code.  A list of the basic symbols is given in Chapter
13 and may be listed on your terminal by typing:
\dispt{HELP\qs POPSYM \CR}{ }
\pd

     Here are some simple examples of uses of the {\tt AIPS} language:
\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.}
\displl{TYPE 'MAPNAME ', INNAME, INCLASS, INSEQ \CR}{{\tt MAPNAME \ 3C138 \
          IMAP \ 1} is written on the terminal.}
\pd

\subsect{12.4.  Processing loops}

     The do-loop capability in {\tt AIPS} uses the pseudoverbs {\tt FOR},
{\tt TO}, and {\tt BY} for repetitive operations.  Such loops are
primarily intended for use in ``procedures" (see \Sec 12.5).  If a 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 'IMAP' \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 {\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}{ }
\pd

\subsect{12.5.  Procedures}

     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 procedures in {\tt RUN} files (\Sec 12.6) than
to prepare them in interactive \AIPS.  A 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:

\eject
\disptt{PROC\qs MFIT (I) \CR}{to define procedure {\tt MFIT} with one argument
               {\tt I}.  ({\tt I} and {\tt J} are two dummy adverbs which
               are already defined in {\tt AIPS}.)}
\dispxx{{\tt : }GETNAME(I) \CR}{(Notice the prompt symbol {\tt :} .  This
               means that we are in the procedure-building mode.)}
\dispxx{{\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}
\dispxx{{\tt : }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.}
\dispxx{{\tt : }FINISH \CR}{to designate the end of the procedure-building
               mode and to get back into the normal (prompt {\tt >}) mode.}
\dispt{ }{ }
\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 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 12.6 below.

     To list the procedure {\tt MFIT}, type:
\dispt{LIST\qs MFIT \CR}{ }
\dispe{This will produce the following:}
\lalign{1&PROC MFIT(I)\cr
        2&GETNAME(I)\cr
        3&TVLOD ; IMXY ; MAXFIT\cr
        4&RETURN\cr
        5&FINISH\cr}
\dispe{The 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{EDIT\qs MFIT\qs 2 \CR}{to enter Procedure editing mode.}
\dispxx{{\tt ; }GETNAME(I) ; TVLOD \CR}{(Notice prompt symbol {\tt ; } for
               procedure-editing mode.)  This change replaces the old line 2
               adding a {\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 ; }ENDEDIT \CR}{to terminate procedure editing.}
\dispt{LIST\qs MFIT \CR}{ }
\dispe{Listing the modified procedure will give:}
\lalign{1&PROC MFIT(I)\cr
        2&GETNAME(I) ; TVLOD\cr
        3&IMXY ; MAXFIT\cr
        4&GETNAME(I+1)\cr
        5&TVLOD ; IMXY; MAXFIT\cr
        6&RETURN\cr
        7&FINISH\cr}

     To delete lines {\it n}  through {\it m} from a procedure, type:
\dispt{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
{\tt ERASE}.  Use {\tt LIST} to determine the new line numbers.}

     The pseudoverb {\tt MODIFY} lets you modify characters within
a line of a procedure to correct the line or change its meaning.
The grammar is:
\disptt{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 {\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:}
\vskip 5pt
\verbatim{50pt}
> 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'
|endverbatim
\pd

     More information about 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
{\ss 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.}

     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 pseudoverbs}.  The
``prohibited'' pseudoverbs include {\tt SAVE}, {\tt GET}, {\tt STORE},
{\tt RESTORE}, {\tt PROCEDURE}, {\tt EDIT}, {\tt ENDEDIT}, {\tt MODIFY},
{\tt LIST}, {\tt CORE}, and {\tt SCRATCH}.  Others do not make much
sense in procedures, including {\tt MSGKILL}, {\tt DEBUG}, and
{\tt ABORTASK}.  Other pseudoverbs are, however, particularly useful
in procedures.  These include {\tt TGET}, {\tt TPUT}, and {\tt GO}.

     Several verbs are extremely useful in procedures.
To set the image name adverbs to those visible on the TV, use {\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.  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.  There are numerous arithmetic
functions, useful looping constructions, and powerful methods of building
arithmetic, logical, and string expressions in {\ss POPS\/}.  Type
{\us HELP POPSYM \CR} or see Chapter 13 for details.

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

      Several procedures have been built into \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 {\tt VLARESET}.  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 \AIPS.

\subsect{12.6.  {\tt RUN} files}

     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 RUN} file facility.

      Any set of commands that can be typed on the terminal can be stored
in a text file.  At present, the computer's own text editor must be
used to generate this file so this part of the process is machine dependent.
The text files are generally stored in an area designated by the word RUN.
Thus, in VAX/VMS these text files are stored in a subdirectory called
{\tt [AIPS.RUN]} under the {\tt AIPS} logon.  On most systems, the file
name must be of the form {\it Accccc.nnn}, where {\it A} is any alphabetic
character, {\it ccccc} are any 0--7 alphanumeric characters, and {\it nnn}
is your user number expressed in 3 hexadecimal characters with leading
zeros.  \AIPS\ programmers also provide a few {\tt RUN} files for general
use in each release \eg\ {\tt VLACALIB}, {\tt VLACLCAL} and {\tt VLARESET}.
These are stored under user number 1 and are automatically available to all
users.  See Chapter 3 of this \Cookbook\ for some helpful information
(\eg\ \Sec 3.10.2).

     The first line of a {\tt RUN} file is ignored by {\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 comments which
will not be executed by {\tt AIPS}.

     To use a procedure, type:
\disptt{RUN\qs {\it xxxxxx} \CR}{to read and execute file {\it xxxxxx}
                  in {\tt AIPS}.  The text will be listed as it is read.}
\dispt{ }{continue {\tt AIPS} in normal mode.}
\dispe{The file {\it xxxxxx.nnn} or, if it does not exist, {\it xxxxxx.001}
will be executed by the above command.  Note that minimum match also applies
to {\tt RUN} file names.}

     {\tt RUN} files are a convenient place to store procedures that are
often used, since the code can be accessed from {\tt AIPS} simply by typing
{\us RUN {\it whatever} \CR}.  {\tt RUN} files are also useful for storing
the commands associated with a convenient set of tasks, such as loading an
image, sorting the data, and making and cleaning the image. All facilities
in {\tt AIPS} such as {\tt GET}, {\tt SAVE}, and {\tt TGET} can be used in
{\tt RUN} files.

\subsect{12.7. Writing your own programs with {\ss POPS}}

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

     Consider a the following example.  (This example is
presented as if it were typed into an interactive {\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}
\par\vskip 5pt\setbox9=\vbox{\halign{\lft{{\tt #}}\qquad&\lft{#}\cr
    PIXXY&is the pixel location in the images,\cr
    N    &is the number of images,\cr
    AVG  &is the average value at the pixel location, and\cr
    RMS  &is the rms value at the pixel location.\cr}}
\centerline{\box9}
\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
{\tt AIPS}.  These must be defined before we can write the procedure
{\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 ; SUM = 0 \CR}{to zero some variables.}
\displx{{\tt : }FOR\qs INSEQ =1 TO\qs N \CR}{to begin summing loop.}
\displxx{{\tt : }\ind QIMVAL \CR}{to get pixel value at {\tt PIXXY}
                       in image {\tt INNAME} {\tt INCLASS} {\tt INSEQ}.}
\displxx{{\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 : }\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 procedure could be run as follows. First
fill in the adverbs {\tt INNAME}, {\tt INCLASS} and {\tt PIXXY} with
the desired values. Then type:
\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 {\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.}

\subsect{12.8.  Character handling in {\ss POPS}}

    In some cases, you may wish to manipulate character strings to
give your files meaningful names --- particularly if your {\tt RUN} file
or procedure operates repetitively on many similar files.

    {\ss POPS\/} provides several string handling expressions.  These are:

\par\vskip 4pt
{\tt \hbox to \hsize{\hfil\vbox{\halign{\lft{#}\quad&\lft{#}\quad&
\lft{#}\quad&\lft{#}\cr
POPS symbol & use  & operation \cr
 !!     & A !! B    &String = string {\tt A} followed by string
                        {\tt B}                               \cr
 SUBSTR & SUBSTR(A,{\it i},{\it j}) &String = chars {\it i}
                        through {\it j} of string {\tt A}     \cr
 LENGTH & LENGTH(A) &Position last non-blank in {\tt A}       \cr
 CHAR   & CHAR(A)   &Convert number {\tt A} to string         \cr
 VALUE  & VALUE(A)  &Convert string {\tt A} to number         \cr
 \noalign{\vskip 10pt}
}}\hfill}}

\vfill\eject
\subsect{12.9.  More about {\tt GO}}

     The verb {\tt 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 \CR}.
{\tt GO} has two further parameters, {\tt DOWAIT} and {\tt VERSION}.  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 \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.}

     {\tt VERSION}, the last input to {\tt GO}, 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.  Type {\us HELP\qs VERSION \CR} for details.

     {\tt 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:}
\disptt{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 TGET\qs
PRTMSG \CR}.}

\subsect{12.10.  Batch jobs}

     The \AIPS\ 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.  The Array Processor, if any, can be
used in batch although interactive users generally have priority on it.
{\tt RUN} files may be used in batch jobs --- as the batch editor
facility is also primitive, they are particularly attractive to batch
users.

     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:}
\disptt{BATQUE = 2 ; BATCLEAR \CR}{to select queue 2 and clear its workfile.
              There are generally two queues and, if so, jobs which use an
              array processor cannot be run in queue 1.}
\dispt{BATCH \CR}{to enter batch preparation mode.}
\dispx{{\tt < }TASK = 'UVSRT' \CR}{(Notice {\tt <} prompt.  Begin
              typing as in {\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}{ }
\dispxx{{\tt < }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 ; BATLIST \CR}{ }
\dispe{To edit line {\it n} in a batch file, type:}
\dispt{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, if {\it n} is an integer, the existing line
{\it n} is overwritten with the line or lines typed before {\tt ENDBATCH}.
If {\it n} is not an integer, the new lines are simply inserted between
lines {\it n} and {\it n}+1.  {\tt 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{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
hexadecimal number $<$ F) 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 UNQUE}.}

     To submit a batch job from outside the {\tt AIPS} interactive
program, log in to the {\tt AIPS} area and then type:
\dispx{\dol\ BATER\qs{\it version} \CR}{to specify {\it version} {\tt OLD},
                        {\tt NEW} or {\tt TST}.}
\dispe{and generate the batch work file as shown above.  It can be
submitted without ever going into {\tt AIPS}.  Note that a different
version of this command syntax may be required on your non-VAX/VMS
computer.}

     Batch has several limitations.  First, devices which require
interactive use (TV device, Tektronix device, and the tape drives) cannot
be used in batch.  Also, batch uses a different set of {\tt TPUT} and
{\tt TGET} files.  Thus, a {\tt TGET} in batch does not get the adverbs
from your last interactive use of the specified task.  However, the
{\tt AIPS} facilities {\tt GET} and {\tt 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, however, that {\tt SAVE} / {\tt GET} files may become
obsolete with new \AIPS\ releases.

     At present, batch jobs are run after a short delay, on a
first-come, first-served basis.  However, batch jobs which use an array
processor are forbidden in batch queue number 1 (if there is $>$ 1 batch
queue) and may be excluded at some times of day by your \AIPS\ Manager in
the other queues.  After your job has been submitted successfully, type:
\dispt{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.  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.}

\subsect{12.11.  Remote use of \AIPS}

        \AIPS\ has a built-in service for remote users who will forgo
the use of a TV.  To request the remote user mode, log in to the
\AIPS\ account on your computer, and start up {\tt AIPS} with
one of {\us AIPS TST REMOTE \CR}, {\us AIPS NEW REMOTE \CR} or {\us
AIPS OLD REMOTE \CR}. \AIPS\ will then skip the TV selection step and will
assume that your terminal supports a Tektronix 4010 emulator.

\subsubsect{12.11.1.  Remote printout: {\tt OUTPRINT}}

        \AIPS\ does not support remote printers explicitly.  You have two
options for capturing \AIPS\ printer output, however.  One is to route it
to disk on the \AIPS\ machine using the {\tt OUTPRINT} parameter of an
\AIPS\ task or verb, and later copy the disk file to your own location.
The other, which is less satisfactory but does not require you to
exit from \AIPS, is to use the screen capture mode of your terminal or
communications program to record \AIPS\ messages or ``printout" with {\tt
DOCRT} set to 1.   For a current list of \AIPS\ verbs and tasks that
support the {\tt OUTPRINT} feature at your \AIPS\ installation, type {\us
HELP OUTPRINT /CR}.

\subsubsect{12.11.2.  Remote graphics: {\tt TKPL} and {\tt TXPL}}

        If you have started up {\tt AIPS} in {\tt REMOTE} mode as described
in \Sec 12.11. the graphics output from {\tt TKPL} will be routed to your
terminal as if it is a stand-alone Tektronix graphics device. Do not use
any {\tt TK...} task in \AIPS\ unless your terminal can diagnose the onset
of Tektronix graphics instructions and switch to graphics mode
appropriately!

        Many terminal and communications packages that claim to have a
Tektronix 4010 emulation mode do not implement a strict emulation. Because
of this, you may find that {\tt TKPL} graphics appear correctly on your
terminal but are then over-written by \AIPS\ messages. This is
unfortunate, but in the absence of a firm emulation standard, it is
difficult or impossible to write generic \AIPS\ code that will prevent it.

        The \AIPS\ task {\tt 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 UVPL} (to guide
self-calibration or to diagnose interference) or examining calibration
solution plots from {\tt SNPLT} or {\tt GNPLT}. {\tt TXPL} can also
usefully interpret simple contour plots or even grey scales(!) for a remote
user.  It is always 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).

         The \AIPS\ task {\tt QMSPL} also has an option to write its output
to a disk file using the {\tt OUTFILE} parameter.  Remote users with
wide-bandwidth links may find it practical to transfer these disk files
(which can be very large for complicated plots) to their local QMS system for
plotting.

\subsubsect{12.11.3. Remote data entry and extraction}

         Remote users should be aware of the FITS disk capabilities of the
\AIPS\ tasks {\tt FITTP}, {\tt UVLOD} and {\tt IMLOD}. These provide ways
to get data out of, and into, remote \AIPS\ systems without using tape
drives.  {\tt FITTP} can write both images and \uv\ data to non-\AIPS\ disk
files in FITS format using its {\tt OUTFILE} parameter.  {\tt UVLOD} can
read FITS disk \uv\ data files from outside \AIPS\ and {\tt IMLOD} can read
FITS disk image files from outside \AIPS, using the {\tt INFILE} parameter.
The details of both approaches are somewhat system-specific, but see
Appendix Z.1.8.1 of this \Cookbook\ for an illustrative example from the
NRAO Convex systems. At present, remote-to-local and local-to-remote FITS
disk file transfers must be done outside \AIPS\ with standard network
software such as {\us ftp}.

\subsect{12.12.  Adding your own tasks to {\af \AIPS}}

     This Section is a brief guide for the average user who wants to modify
an existing 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.

\subsubsect{12.12.1.  What kinds of task can I write?}

     The simplest way to write an \AIPS\ task is to modify one of the four
template tasks, {\tt TAFFY}, {\tt CANDY}, {\tt FUDGE} or {\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 12.12.5.

{\tt 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 \AIPS.  This template task might, for example, be used
to blank pixels in an input image in any specified manner.

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

{\tt FUDGE} - This template task reads an existing \AIPS\ \uv\ data base,
modifies this data base point by point, and then creates and writes this
modified output \uv\ data base 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 UVFIL} - This task is similar to {\tt FUDGE} except that the input \uv\
data may be 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 best to start
with {\tt COMB} itself than with one of the templates.  However, more than
trivial changes to major tasks will require a careful look at the code,
which is generally well documented and segmented.

     Changes to tasks that use the TV and other graphics devices, imaging
and deconvolution software should not be attempted unless the changes are
almost trivial.  It is not advisable to modify verbs, because the entire
{\tt AIPS} program must be relinked when this is done.  This should not be
attempted unless the local \AIPS\ manager agrees with the changes.

\subsubsect{12.12.2.  How do I get started?}

    Unless you have certain privileges in \AIPS, it may be more convenient
to generate and link new code in your own user directory rather than in
your installation's designated local \AIPS\ directory.  Check with your
local \AIPS\ Manager about this. Decide which template task or other \AIPS\
task you want to modify, then follow these instructions after logging into
your private area.

    Under VMS in a VAX:

\dispe{Set up logical assignments with}
\dispxx{{\tt \$} @DISK:[AIPS]LOGIN.PRG \CR}{You may
                                        have to specify the {\us DISK}}
\dispe{Copy compilation and linking libraries with}
\dispx{{\tt \$} COPY SYSVMS:QYPGNOTOPT.OPT LOCAL.OPT \CR}{}
\dispe{Find out which \AIPS\ subdirectory the target task is in with}
\dispx{{\tt \$} DIR APLPGM:*.FOR \CR}{}
\dispe{or}
\dispx{{\tt \$} DIR APGNOT:*.FOR \CR}{}
\dispe{Copy the original code to your area and rename it to NTASK.FOR:}
\dispx{{\tt \$} COPY APLPGM:TASK.FOR NTASK.FOR \CR}{}
\dispx{{\tt \$} COPY APGNOT:TASK.FOR NTASK.FOR \CR}{}
\dispe{as appropriate and where NTASK is your new task name}
\dispxx{{\tt \$} COPY HLPFIL:TASK.HLP NTASK.HLP \CR}{Copy {\tt INPUTS/HELP}
                                                   file for task.}
\pd

    Under UNIX in a CONVEX:

\dispxx{{\tt \%} \$CDTST (or \$CDNEW) \CR}{Set up logical assignments.}
\dispxx{{\tt \%} LIBS \$APGNOT $>$ APGNOT.OPT \CR}{Copy compilation and linking
                                     libraries.}
\dispx{{\tt \%} LIBS \$APLPGM $>$ APLPGM.OPT \CR}{}
\dispx{{\tt \%} ls \$APLPGM/*.FOR \CR}{}
\dispe{or}
\dispxx{{\tt \%} ls \$APGNOT/*.FOR \CR}{To find where your
                      task is located.}
\dispxx{{\tt \%} cp \$APLPGM/TASK.FOR NTASK.FOR \CR}{Copy code for TASK into
                                                   your area and rename.}
\dispxx{{\tt \%} cp \$APGNOT/TASK.FOR NTASK.FOR \CR}{Alternate for above.}
\dispxx{{\tt \%} cp \$HLPFIL/TASK.HLP NTASK.HLP \CR}{Copy INPUTS and HELP file
                                                for task.}
\dispxx{{\tt \%} setenv MYAIPS `pwd' \CR}{Define MYAIPS (must be uppercase) as
                                        your version name for \AIPS.  This must
                                        be done in UNIX systems in order to
                                        avoid \AIPS\ upper/lower case problems.}

\subsubsect{12.12.3.  Initial check of code and procedures}

     Before modifying the 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!

     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.

\par\noindent{\tt DATA PRGM / 'TASK '/}

This should be modified to

\par\noindent{\tt DATA PRGM / 'NTASK'/}

The maximum number of characters in a task name is five and the data
statement must be in the above form.  There is no need to change the help
file yet, as long as it is named NTASK.HLP.

     To compile and link a task, type:

\dispxx{{\tt \$} COMTST NTASK \CR}{(VMS)}
\dispxx{{\tt \%} COMLNK NTASK LINK.OPT \CR}{(Convex UNIX)}

There should be no important error messages.  Sometimes, the template tasks
have not been fully updated and there may be a few errors to correct,
however.

     After successful compilation and linking, try executing the task.

     Under VMS, log in to \AIPS\ and start {\tt AIPS OLD}, {\tt AIPS NEW} or
{\tt AIPS TST}, as desired.  To run any tasks that have been compiled and
linked in your logon, set the adverb

\dispt{VERSION 'DISK:{\it your-logon}' \CR}{}
\dispe{
You may have to explicitly state the disk drive.  Check the inputs and run
the program.}

     Under Convex UNIX, stay logged in to your area.  To initiate the
{\tt AIPS} program, type:

\par\noindent{\tt \%} {\us AIPS [OLD,NEW,TST] \CR} (as appropriate)

Your \AIPS\ Manager may have to make some arrangements for you to
activate \AIPS\ from your logon. Once you have started \AIPS, type

\dispt{ VERSION 'MYAIPS' \CR}{}

look at the inputs, then execute the task.

\subsubsect{12.12.4.  Modifying an \AIPS\ task}

     If you are modifying an existing 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:

\hanstart{50pt}
\enumerate{1}{Change the data statement {\us DATA PRGNAM} near the
beginning of the program if you have not already done this.}
\enumrnext{Make changes in the introductory text which describes the task.
 This is particularly important if you are adding or removing adverbs.}
\enumrnext{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, usually
in a common named {\tt /INPARM/}.}
\enumrnext{Change code as desired.  Try to modify {\tt HI} file entries as
well.}
\enumrnext{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 \AIPS\.  Then, add it to the
task.}
\enumrnext{Revise the file {\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 yourself later or if anyone else will use your program.}
\enumrnext{Compile and link the modified task following the instructions
in the previous section.  When it is error-free, try it out in \AIPS.}

\par\hanend

\subsubsect{12.12.5.  Modifying an \AIPS\ template task.}

     The template tasks are:

\hanstart{50pt}
\enumerate{1}{{\tt TAFFY}---modifies an existing image file and
        writes a new image.}
\enumrnext{{\tt CANDY}---writes a new image.  Input from outside \AIPS.}
\enumrnext{{\tt FUDGE}---modifies an existing \uv\ data base and
        writes a new data base.}
\enumrnext{{\tt UVFIL}---writes a new \uv\ data base.  Input from
             outside \AIPS.}
\hanend

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

     {\tt TAFFY} reads a selected subset of an image, one row at a
time, to a user interface subroutine {\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.

\hanstart{50pt}
\enumerate{1}{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.}
\enumrnext{It is possible to handle several input images and several
output images with {\tt TAFFY} by using multidimensional images and the use
of the axis transposing task, {\tt TRANS}.  Suppose you want to calculate the
spectral index from a set of four images.  First, use {\tt MCUBE} to put the four
images into one data cube.  You will have to redefine the frequency axis of
each image to 1,2,3,4 in order to run {\tt MCUBE}.  Then, transpose the cube so
that the frequency axis is first with RA and DEC 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 arbitrarily
specified.  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 RA and DEC
are the first two axes and the spectral index, etc are the third axis.}
\enumrnext{You can write and debug outside \AIPS\ any subroutines that
{\tt DIDDLE} will call in calculating the output image.  This will speed up
debugging of your algorithms.}
\enumrnext{It is possible to read several input rows before writing one output
row.}
\hanend

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

\hanstart{50pt}
\enumerate{1}{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} \AIPS.}
\enumrnext{The subroutine {\tt MAKMAP} reads further records from the
external file until a full row of the output image is obtained.}
\enumrnext{Many adverbs are built into {\tt CANDY}.  If you need more or wish
to change them, read the information at the beginning of subroutine {\tt
CANIN}.}

\par\hanend

     {\tt FUDGE} reads an existing \uv\ data base point by point and
creates a new \uv\ data base with the modified data.  It can easily be
used to make simple changes in a \uv\ data base; for example, if the $u$,
$v$, or $w$ terms are to be recalculated, if all phases are to be changed
in sign, etc.

\hanstart{50pt}
\enumerate{1}{If the output image has different dimensions than the input image
(combining several spectral line channels), changes must be made in the
subroutine {\tt FUDGIN}. }
\enumrnext{To combine several input data points, use the task {\tt UVSRT}
to put the data points adjacent in the file. }
\enumrnext{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. }

\par\hanend

     {\tt UVFIL} reads input from one or two FORTRAN
readable files which are outside \AIPS,  from which a \uv\ data base is
created, cataloged and filled into \AIPS.  This task is useful for
transcribing \uv\ data in an arbitrary format into an \AIPS\ data base.

\hanstart{50pt}
\enumerate{1}{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 NEWHED. }
\enumrnext{The second auxiliary file contains the actual \uv\ data in some
format and it is converted into an \AIPS\ \uv\ data base, point by point,
in the subroutine {\tt FIDDLE}.  The comments in {\tt FUDGE} are complete
and an example is given in the code.}
\par\hanend

\subsubsect{12.12.6.   Further comments}

\hanstart{50pt}
\enumerate{1}{Try to use the \AIPS\ coding standards as described in {\it
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.}
\enumrnext{While debugging, use the FORTRAN call {\tt PRINT *, ...} 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).  Running a task in \AIPS\
using the system debugger can be complicated and is not recommended for the
casual user. }
\enumrnext{Declare all variables that you use.}
\hanend




\end

