AIPS HELP file for BATCHJOB in 31DEC24

As of Thu Apr 25 6:34:13 2024

HELP SECTION

Type:  Operations to prepare, submit, and monitor batch jobs

Use:   There are a number of batch streams of AIPS, each capable of
   processing a queue of jobs.  To run a batch job, one must first
   prepare the text of the job in a work file.  This text may contain
   any normal AIPS/POPS statement including RUN, except for verbs and
   tasks related to batch preparation, the TV, the TEK4012 green
   screen, and the tape drives.  When the text is ready, it may be
   submitted to the batch AIPS.  On the way, it is tested for errors
   and is submitted only if none are found.  After successful
   submission, the work file and any RUN files involved may be altered
   without affecting the job.  Array processor tasks are now allowed
   in any queue and at any time.  Line printer output should be
   directed to a user chosen file (via adverb OUTPRINT).  If OUTPRINT
   = ' ', all tasks and AIPS itself will write to a file named
   PRTFIL:BATCHjjj.nnn, where jjj is the job number in hex and nnn is
   the user number in hex.  Note that all print jobs are concatenated
   into the specified file(s).

        Hint: to find the local limit on the number of batch queues,
   enter BATQUE=99; INP BATCH and the error message will tell you the
   allowed upper limit locally.

Adverbs:
   BATQUE.....Number of queue to be used ( 1 or 2 or more )
   JOBNUM.....Job number involved (101 - 164, 201 -264, ...)
   BATFLINE...First line number to be editted or listed
   BATNLINE...Number of lines to be listed

Verbs:
   BATCH......Add text to BATQUE work file
   BATCLEAR...Initiate and clear BATQUE work file
   BATLIST....List BATNLINE starting with BATFLINE from BATQUE work
              file
   BATEDIT....Edit text in BATQUE work file starting with line
              BATFLINE (or immediate argument)
   BAMODIFY...Edit text in BATQUE work file in line BATFLINE (or
              immediate argument), character-mode editing.
   SUBMIT.....Submit text in BATQUE work file as job for queue BATQUE
   JOBLIST....List BATNLINE starting with BATFLINE from text file of
              job JOBNUM
   QUEUES.....List jobs submitted, running, and completed in queue
              BATQUE
   UNQUE......Remove JOBNUM from queue, copy text of job to work file
              BATQUE

Batch jobs may also be prepared and submitted outside of AIPS, using
the program BATER.  See HELP BATER.

                         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 (or 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 appends 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.
BATCLEAR removes all of the contents of the work file.

     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, although there
can be fewer or more.  (Type BATQ=99; INP BATCH to be told the local
upper limit.)  The first should be for smaller jobs but it will now
run tasks which require the array processor.  The others are for
longer jobs and will run AP tasks, and will now run them whenever
you want.

                          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 one minute.  This delay
is inserted to allow you to reconsider and to remove the job from the
queue using the verb UNQUE.  When UNQUEd, a job is returned to the
work file - for additional editing presumably.  A job which is not yet
running may be listed with JOBLIST.