; NEWTASK
;---------------------------------------------------------------
;! Information about installing a new task
;# INFORMATION PARAFORM
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  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
;-----------------------------------------------------------------------
NEWTASK   LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
----------------------------------------------------------------
NEWTASK
Type: This file contains instructions for creating a new task in AIPS.

It attempts to show it for both Unix and VMS, though the VMS description
is most likely very outdated (the last VMS version of AIPS was 15APR91).

     The simplest way to create a new task is to modify an existing one.
In particular, the tasks FUDGE for UV data and TAFFY (or CANDY) for map
data are designed as paraforms for the creation of new tasks and contain
lots of instructions.  First pick a new name (up to 5 characters) unique
in AIPS (look in the $LOAD area to check).  In the following this new
name will be represented by "newname"; the quotes are not used in the
actual command.  The following steps are illustrated with a "%" prompt
for Unix and a "$" prompt for VMS.  The prompt character will be shown
in the following although it should not be typed.  You need to do these
steps after EXITing from AIPS to the operating system.

1)  Login to your own area, and issue the commands:
        Unix                         VMS
    % source /AIPS/LOGIN.CSH  (csh)  $ @[AIPS]LOGIN.COM
or  % . /AIPS/LOGIN.SH (sh/ksh/bash)
    % $CDTST                         $ CDTST

    (don't type the "(csh)" or other things in parentheses!)
    At this stage you may want to move to a subdirectory, or wherever
    you want the new task's source code to be.

2)  Copy the old code to a new file:
        Unix                         VMS
    % cp "old".FOR "new".FOR         $ copy "old".FOR "new".FOR

    For the paraforms, this is
        Unix                           VMS
    % cp $APLPGM/TAFFY.FOR "new".FOR   $ COPY APLPGM:TAFFY.FOR "new".FOR
    % cp $APLPGM/FUDGE.FOR "new".FOR   $ COPY APLPGM:FUDGE.FOR "new".FOR
    % cp $APGNOT/CANDY.FOR "new".FOR   $ COPY APGNOT:CANDY.FOR "new".FOR

    NOTE: To avoid headaches, do NOT copy it to a directory in the
    existing AIPS directory tree (e.g. do not use a LOCAL subdirectory
    under $SYSLOCAL); this will really confuse the COMLNK procedure at
    least under Unix.  Use a directory, e.g. in your login area instead.

3)  Edit the source code using your favorite editor, e.g.
        Unix                           VMS
    % emacs "new".FOR                  $ EDIT/TPU "new".FOR

    All references to the old task name should be changed to the new
    task name.  It is ESPECIALLY important to change the name of the
    task in the PROGRAM statement in the first line of the file and in
    the data statment which tells the task it's name.  This data
    statment is usually in the main routine or in a program-specific
    initialization routine.

4)  Once the source code has been modified it can be compiled
    and linked using the following:
        Unix                           VMS
    % COMLNK "new".FOR options         $ COMTST "new".FOR  options

    where the options include DEBUG for a load module linked for
    running in "debug" mode.  If you want to generate an options file,
    use the LIBS command to do so (e.g. on Unix, LIBS $APLPGM >MINE.OPT)

5)  Copy and rename the Help/Inputs/Explain file as
        Unix                           VMS
    % cp $HLPFIL/"old".HLP "new".HLP   $ copy HLPFIL:"old".HLP "new".HLP

    Use your editor to modify the new file to reflect the adverbs and
    functions of the new task.  Be sure to change the name of the task
    to the new name, to follow the format of the Inputs (first) section
    carefully, and to get the adverbs listed in the Inputs in the same
    order as expected by the new task.

7)  On VMS only, Remember to conserve disk space.  Issue
         $ PURGE  [...]
    regularly.

8)  To run the new task, define a "logical":
        Unix                           VMS
    % setenv MYAREA `pwd` (csh)        $ define MYAREA <dir name here>
or  % MYAREA=`pwd`; export MYAREA
                     (bash/ksh/sh)
    Then run AIPS using, e.g. if you want to use the debugger,
         AIPS <other options> DEBUG
    and set the VERSION adverb to 'MYAREA'.

9)  Additional information may be obtained by consulting the GOING AIPS,
    Volumes I and II.  These should be available in printed form at
    Charlottesville and the VLA and AOC.

    Also the precursor comments of standard AIPS routines give details
    about their use.
----------------------------------------------------------------
