; BATCH
;---------------------------------------------------------------
;! starts entry of commands into batch-job work file
;# Verb Batch
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
BATCH     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
BATCH:  Verb used to enter a batch work file
BATQUE          1.0         2.0    Batch work file
----------------------------------------------------------------
BATCH
Type: verb (acts somewhat like a pseudoverb since remainder of
            input line will not be executed)
Use: Causes the input mode to be changed to batch (prompt symbol
     <).  All following lines are placed in the specified batch
     work file until the string ENDBATCH is found in the input.
     The lines are placed at the start of the work file if the
     file is empty or if it was last used by someone other than
     the current logged-on user.  Otherwise the lines go after
     the previously entered text.
Adverbs:
  BATQUE   The number of the work file for which the text is
           being prepared (1 or 2).
----------------------------------------------------------------
BATCH   Verb to cause following text to be added to a batch job.
Documentor:  Eric W. Greisen
Related programs: BATEDIT, BAMODIFY, BATLIST, etc.

                         PURPOSE

     In order to run a job using the AIPS batch system a text
file of commands must be prepared and submitted to it.  BATCH
is the first verb used in preparing a file of this type.  It
causes the AIPS program to read all following lines and place
them in a "work file" for later submission.  The reading of
the input text continues until the EXACT string ENDBATCH is
encountered in the input.  Then AIPS returns to normal mode.
The prompt symbol during batch preparation mode is "<" rather
than the usual ">".  The first time BATCH is used by a user
on a particular work file, the text goes at the beginning of
the file.  Thereafter, BATCH append the text at the end of the
previous text.  Verbs BATEDIT and BAMODIFY may be used to edit
the contents of the work file and BATLIST to list the contents.
     Batch is used in AIPS for several purposes.  It allows
repetitive work to go on in the background without tying up a
terminal.  It also allows long jobs to be run later when the
computer is less busy.  There are usually two queues in an AIPS
batch system.  The first is for smaller jobs and will not run
tasks which require the array processor.  The second is for
longer jobs and will run AP tasks, but will run them only
during evening hours.  Currently those hours are 6 pm to 8 am
weekdays and 4 pm to 9:30 am weekends.  These hours may vary at
various AIPS installations.

                          COMMENTS

     The editors provided for batch jobs are fairly primitive.
For this reason, we recommend two methods for reducing the
amount of text actually in a batch work file.  You can prepare
a POPS environment for a particular job or portion of a job
(e.g. a task) interactively and then SAVE it under some name.
This environment may then be recovered intact in the batch job.
For example, assume that you have a set of line maps to be
cleaned.  Prepare the adverbs for cleaning and try them on the
first map interactively.  When you are satisfied, the do
          >SAVE  CLEANTHEM
          >BATCH
          <GET CLEANTHEM
          <FOR INSEQ = 2:18 ; OUTSE=INSEQ ; GO ; END
          <ENDBATCH
          > ...
Note that AIPS batch runs tasks sequentially.  Thus, it was not
necessary to specify DOWAIT TRUE or to issue a WAITTASK.  When
using this shortcut, be careful not to change your SAVE file(s)
before the batch job has finished.
     The second shortcut is to use RUN files.  These files are
prepared using your local text editor which should have all
sorts of nice facilities.  Then the batch job work file would
be prepared using, for example,
          >BATCLEAR                (clear out last job)
          >BATCH
          <RUN DOITALL
          <ENDBATCH
          >
RUN files are expanded when the job is submitted.  Thus, they
may be modified as soon as a job is successfully in the queue.
     Be sure to list the batch work file with BATLIST before
issuing the verb SUBMIT.  That verb submits the work file to a
checking program (AIPSC) which tests the POPS grammar.  Should
it pass the test, the job is submitted to the batch AIPS called
AIPSB which will run it eventually.  Use the verb QUEUES to list
the current queue and note particularly the "submit time"
assigned to your job.  It will be after the actual submission
time by at least a few minutes.  This delay is inserted to allow
you to reconsider and to remove the job from the queue using the
verb UNQUEUE.  When UNQUEUEd, a job is returned to the work file
- for additional editing presumably.  A job which is not yet
running may be listed with JOBLIST.
     Additional help may be found in the HELP file called
BATCHJOB and in the HELP files for the various verbs.
