; RUN
;---------------------------------------------------------------
;! Pseudoverb to read an external RUN files into AIPS.
;# VERB POPS
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2009, 2013
;;  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
;-----------------------------------------------------------------------
RUN       LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
RUN:  Pseudoverb to read an external RUN files into AIPS.
VERSION                            Version of code to use.
            Must be the ONLY command on the input line.
          Grammar:
                    RUN  name
            where name is the name of a file in the RUNFIL or
            VERSION areas of your computer cataloged as
            name.usr, where usr is your user number in hex or in
            VERSION or the RUNSYS area cataloged as name.001.
            The latter are AIPS-provided service routines.
----------------------------------------------------------------
RUN
Type:  Pseudoverb        (ONLY command on the input line)
Use:   To cause the command input to AIPS to be taken from the specified
       (text-editor type) file until an end of file is found.  The
       command input then reverts to the normal source.
Grammar:   RUN  name
       where name is the name of a sub-file within the area reserved for
       RUN texts or in one of your disk areas.  See your local systems
       programmer for info on how to create your own subfiles.  These
       files are created using your local text editor and may contain
       any legal AIPS commands including RUN itself.  Their names must
       begin with a letter (A-Z).  They are used primarily to keep
       your own set of procedures, initial value specifications, and
       the like.  On UNIX systems, the RUN files are stored in an area
       called /AIPS/RUN (environment variable $RUNFIL) under names of
       the form yourname.usr, where yourname is any name up to 8
       characters and usr is your AIPS user number in three
       extended-hexidecimal digits, right-justified with leading 0 if
       needed.  NOTE: the first line of a RUN file is not executed by
       AIPS and is intended to contain info on the date and user name.
       If it does not, the file may vanish from a public area without
       notice.

       RUN x must be the only command on the input line.  All other
       commands on the line will be ignored.  RUN files may be nested
       up to 20 deep, but note that the COMPRESS "verb" does a RUN
       operation and so counts against this limit.

       The RUN file may be either one of your files called name.usr
       where usr is your user number in extended HEX or it may be a
       user- or AIPS-provided utility called name.001.  Min match
       applies to name as follows:
          (a) If VERSION = ' ', the file $RUNFIL/name.usr is sought
              and if it is not found, then the file $RUNSYS/name.001
              is sought.  (RUNSYS is an AIPS-provided system area for
              things like VLBAUTIL.)
          (b) If VERSION = 'xxx', the file $xxx/name.usr is sought
              and if it is not found, the file $xxx/name.001 is
              sought.
       Hint - if you have put the file under user 1 in $RUNFIL, then
       you must set VERSION = 'RUNFIL'.
Adverbs:
   VERSION...Version of run file to be used.  See HELP VERSION and
       above for details.
----------------------------------------------------------------
RUN: Pseudoverb to read an external RUN file into AIPS.
RELATED PROGRAMS: REDIT, PROC, BATCH

                         PURPOSE

     The writing and editing of procedures more than a few lines long in
AIPS (see PROCEDURES) is tedious because of the primitive editor.  Long
procedures are better written in text files at monitor level in the
computer, where there are good editing facilities (e.g. SOS or EMACS in
VAX/VMS, SEDIT in Modcomp, emacs or vi in UNIX).  These files can then
be transferred to AIPS and executed very simple by use of the RUN file
facility.
     The pseudoverb RUN facilitates the preparation of such files at
monitor level.  Any set of commands consistent with the text editor can
be stored in a text file.  This includes anything you can use in AIPS.
The text files are generally stored in an area associated with the name
of RUN.  Thus, in UNIX these text files are stored in a sub-directory
called /AIPS/RUN usually (always $RUNFIL) so that they are directly
accessible under the AIPS logon.

                 HOW TO SET UP A RUN FILE

     The following illustration applies to VAX/VMS, with SOS editor. You
are going to prepare a file whose name is xxx.  (Your user number in
extended hexadecimal is called usr below.)   First get into monitor
level ($ prompt).  Then:

$ EDIT/SOS RUNFIL:xxx.usr (cr)   $EDIT/EDT xxx.usr (cr) will
                                 gives you EDT editor)
* 00100 --TASK TO SUBTRACT (cr)  first line is ignored by AIPS,
                                 It is used for your
                                 information only.
* 00200  task='uvmap';dowa=1;    note dowait=1 will normally be
                                 necessary if you are executing
                                 several tasks in sequence
* 00300  [various inputs] (cr)

* 00400  GO;(cr)                 in AIPS, certain information
                                 cannot be set on the same
                                 line as GO.  Safest to use a
                                 separate line for GO.
* 00500  task='apcln'(cr)

* 00600  [various inputs] (cr)

* 00700  GO; (cr)

* 00800  [escape] (cr)           hit escape key for SOS or
                                 CNTR Z for EDT; line 00800 will
                                 not appear in text file
* L (cr)                         print out file on line printer

* E or ET (cr)                   catalogue file and leave editor

$ SET DEF [AIPS]                 set back to AIPS logon

$ AIPS <version> (cr)            enter AIPS version you want
                                 (OLD,NEW,TST), user no. etc
> RUN xxx (cr)                   read and execute file xxx.RUN.
                                 Text will be listed as read.

                         COMMENTS

     Your new file xxx is stored as xxx.usr;n where n is the version
number, starting at 1.  When you invoke file xxx from AIPS, it
automatically selects the version with the highest sequence number
(latest version).
     All versions n of xxx.usr are stored in AIPS.RUN.  The command EDIT
xxx.RUN selects the highest n when you want to change something in an
already existing file xxx.  You make the changes using the usual SOS
editor facilities (Pyyy:zzz lists lines yyy to zzz; Ryyy replaces line
yyy; Sindisk=1$indisk=2$/. changes indisk=1 to indisk=2 throughout; and
so on).  When you have finished making changes, E (or ET) catalogs the
file with the version number augmented by 1.
     If you specifically want to change a version of xxx other than the
latest one, type EDIT xxx.usr;n where n is the desired version.
     To list all run files existing in AIPS.RUN, type $ DIR at monitor
level but after $ RUN has been invoked.  You will get a listing of
everyone's files, not just your own. At present, the RUN area separates
users by the .usr portion of the file names. Considering that every
version of everyone's files is stored, there can be space problems.
Therefore it is requested that users delete files or versions they don't
need.  To do so:

 $ DEL xxx.usr;n   (cr)     deletes version n, and only n, of
                               file xxx.  n MUST be specified
                               when using DEL.
 $ PURGE xxx.usr            deletes ALL versions of xxx except
                               the latest one.
     These comments apply to VAX/VMS.  The entire RUN file management is
different on other machines.  Consult COOKBOOK for a few facts about the
Modcomp.

CATALOGING:
     The command "E" stores the RUN file WITH the line numbers retained.
Line numbers are acceptable when using the SOS editor but not the EMACS
editor.  "ET" stores the RUN file without line numbers.  If the SOS
editor is then subsequently invoked, it automatically reinserts a
sequenced set of line numbers starting at 00100.  "EQ" declines to store
a RUN file at all, but otherwise exits from the editor.
