





     Building the Batch System
     -------- --- ----- ------

          Note:  these notes apply to RSX-11M V3.2.  The system runs  OK
     under  V4.0  but  the  procedure  described  here  may  be slightly
     different in the SYSGEN section.  I apologise in advance  for  this
     not  being  fully  documented,  and also for the documentation file
     BATCH.DOC being somewhat specific.   There  is  a  new  and  vastly
     improved  version  of the batch system being developed (Version 3).
     If you are interested in getting a copy of it, or have  suggestions
     for  improvements or bug fixes to the current version, please write
     to me.  If you want to use the package at all, please let  me  know
     so  that  I can put you on my mailing list for improvements.  I can
     be reached at:
      
          Steve Thompson
          School of Chemical Engineering
          Olin Hall
          Cornell University
          Ithaca NY 14853
          (607) 256 4616 (office)
          (607) 256 3895 (computer room; rather noisy)
      

          The virtual terminal driver is loadable but  it  must  have  a
     resident  data  base.   Therefore,  a  SYSGEN  must be performed to
     incorporate the batch system.  In what follows, [g,m]  is  the  UIC
     under  which  the batch system files are stored.  Go straight ahead
     and perform the SYSGEN;  the following support *must* be included:

          (i) Spawn directive (Parent/Offspring tasking)

          (ii) Stop bit support.

          (iii) Loadable Driver support.

          (iv) Support for user-written drivers.  The  virtual  terminal
     driver does not require the Executive routines $GTWRD and $PTWRD.

          (v) Read-after-prompt support in the terminal driver.

          (vi) Crash dump support with a magnetic tape as the crash dump
     device  (this  is optional but necessary if you want to restore the
     state of the batch system in the event of a system crash).

          You should also modify IND.TSK (...AT.)  as  per  the  release
     notes  to  include  spawning  and  stop bit support (RSX-11M V3.2).
     This involves a source change (in INDIMP.MAC and INDPDW.MAC) and  a
     change  in  the task builder command file, INDBLD.CMD.  When SYSGEN
     pauses and asks for  you  to  assemble  your  drivers,  proceed  as
     follows:

     	SET /UIC=[g,m]


                                                                  PAGE 2



     	EDI VTTAB.MAC	(jocks use TECO here)

          Now locate the line NVT=...  and  change  the  number  to  the
     largest  number  of  batch  streams that you will ever want to have
     running jobs simultaneously;  the value set can  be  from  1  to  4
     inclusive  (in  fact it could be 20 if you wanted it but this would
     give the loader a hard time).  The batch system can  be  built  for
     any number of batch streams up to this number so that by specifying
     4 you don't commit yourself  to  running  4  batch  streams.   Each
     virtual  terminal  that  you specify in excess of your batch stream
     requirements in this manner costs you only 32 words of pool.   Once
     the  basic data base has been incorporated into the system, you can
     change the number of batch streams up to the SYSGEN  limit  at  any
     time,  providing  that  there  are  no jobs active.  Note also that
     batch streams are only represented  by  VT1:   and  up;   VT0:   is
     always  added  and  is  the exclusive property of the Batch Manager
     program.  If you have other user-written drivers  in  your  system,
     this procedure will have to be diddled slightly, but this should be
     straightforward.

          Once you have edited VTTAB.MAC to your satisfaction,  continue
     as follows:

     	LBR [1,1]EXEMC.MLB/RP/SZ=[g,m]QUEDF.MAC
     	MAC VTTAB=[1,1]EXEMC/ML,[11,10]RSXMC,[g,m]VTTAB
     	MAC VTDRV=[1,1]EXEMC/ML,[11,10]RSXMC,[g,m]VTDRV
     	SET /UIC=[11,24]

          If any errors occurred, repeat the procedure until  everything
     is  fixed.   Then,  making  sure  that  the  UIC is set to [11,24],
     continue with

          UNS AT.  or

          RES AT.

          depending on whether the version of AT.   you  are  using  has
     stop bit support in it or not.

          Some time later, you will get a prompt from LBR together  with
     instructions  to  add  your  modules to the Executive object module
     library.  The modules for the virtual terminal driver and its  data
     base can be inserted with the command

          LBR>RSX11M/RP=[g,m]VTDRV,VTTAB

          After this, SYSGEN will carry on as it is wont to do, and  you
     will  come  to  a  place  where  the  Executive build file is to be
     edited.  When SYSGEN prompts with

          EDI RSXBLD.CMD

          the only EDI commands that you need to issue are


                                                                  PAGE 3



     	SC/SYSTB/SYSTB:VTTAB/
     	EX

          Of course, this may have to be  modified  if  you  have  other
     user-written drivers.

          The executive should now  task-build  ok.   Some  time  later,
     SYSGEN will ask if you want to build any loadable drivers.  To this
     question answer YES, and specify VT as  a  (or  the)  device  name.
     Don't  forget  that  just  before the new system is configured with
     VMR, edit SYSVMR.CMD and include LOA VT:  just after the definition
     of  DRVPAR.  The size of the partition needed by VTDRV is 600 octal
     bytes.

          After SYSGEN, when the system (V3.2) is up  and  running  (?),
     you  will  probably want to select certain options available in the
     batch system.  The various possibilities are  fully  documented  in
     the  source files.  You will have to examine the first few pages of
     BAT.MAC and BATMAN.MAC and comment  out  the  conditional  assembly
     parameters you don't need support for.  By default you get the lot.
     Also, you will want to change the number of active batch streams by
     looking  for  where  the  macro  "STREAM"  is called in BATMAN.MAC.
     There it gives instructions on what to do.  You will also  need  to
     edit BATBLD.CMD and BATMANBLD.CMD and possibly also STACKBLD.CMD if
     you want to change the default maximum stack size.  It's probably a
     good  idea  to  read  the Batch System User's Guide first, but this
     step can be skipped if you really can't face it.  The RUNOFF source
     for  the  guide is included in the file BATCH.RNO.  To assemble the
     system, issue the command

          @BATCHASM

          Any questions that may be  asked  are  self-explanatory.   The
     whole lot can be task-built by typing

          @BATCHBLD

          You  can  now  run  the  batch  system.   The   command   file
     BATCHINIT.CMD  will  initialise  everything.   You may want to edit
     this first, so have a look at it (it's only short, honest).

          The following approximate task sizes are a guide to the memory
     used  by  the  batch manager program (BATMAN).  The MCR command BAT
     (the task BAT.TSK) is large and will always lead to an  overlapping
     I/O page message when it is installed - ignore it.

     	NUMBER OF	SIZE OF BATMAN		SIZE OF BATMAN
     	STREAMS		WITH ALL OPTIONS	WITH MINIMUM OPTIONS
     	(NOT # OF VT:'S)   (WORDS)		   (WORDS)

     	    1		    5000		    4700

     	    2		    5350		      -


                                                                  PAGE 4



     	    3		    5670		      -

     	    4		    6020		    5700

          Building BATMAN.TSK (but *not* BAT.TSK) with an  FCS  resident
     library  is a good idea if you have one since it reduces these task
     sizes by anything up to 2900 words.

          All the batch system tasks run  in  partition  GEN.   You  can
     change  the  partition  for  BATMAN  to a dedicated user-controlled
     partition if batch will always be running, but one thing to note is
     that  it should *never* be built as checkpointable.  BATMAN will at
     times have two I/O operations outstanding, and nearly  always  one,
     so if it is checkpointable it will just not work!

          The task CQR will restore the state of the batch  queue  if  a
     system  crash should occur, but only if you have taken a crash dump
     on magtape (CQR reads the dump on the tape).   Running  CQR  is  an
     option in the startup file BATCHINIT.CMD.  If you want to perform a
     normal system shutdown when there are jobs in the queue, run SHUTUP
     as normal.  The file [1,2]SHUTUP.CMD should contain the command

          @[g,m]BATCHCLOS.CMD

          This command file will cause the queue to wind down in such  a
     way  as  to  cause BATMAN to exit at the end of the current job(s).
     If there are any jobs in the hold queue, you will have  to  release
     them  at  this  point  with BAT /RL:n.  (Note that you cannot BRO a
     message to a batch job:  VTDRV allows the operation and marks it as
     successful,  but  does  not  actually perform a data transfer.  The
     original intention behind  this  was  to  stop  someone  running  a
     program  in one batch stream that had got a LUN assigned to another
     stream from corrupting someone else's log file by  writing  garbage
     into  it.   VTDRV  could easily be modified to insert a subfunction
     bit so that IO.WBT's could be used to send external messages to log
     files.)

          When the system has halted as a result  of  SHUTUP,  you  must
     force  a system crash.  To do this, load address 40 and restart the
     processor.  The normal system crash display will  appear,  and  you
     can then take a crash dump in the usual way.






                                                                  PAGE 5



     Batch System Operator Commands
     ----- ------ -------- --------

          The following switches are  accepted  by  BAT  (at  privileged
     terminals  only)  to  perform  various queue maintenance functions.
     All these switches fall into a single class of  commands  with  the
     /ID  switch, and may be used in any combination in a single command
     line.  All of the specified characters are required.

          /SAVE

          This switch is accepted but no action is performed.  It is  to
     be used for a future extension where the queues will be copied to a
     disk file.

          /RESTORE

          Like /SAVE, this is a  dummy  switch,  which  will  eventually
     restore  the  queues from a disk file created with /SAVE.  The idea
     is to make machine shutdown a tidier looking affair.

          /RUNDOWN

          This switch puts  the  batch  system  in  a  state  where  all
     currently  running  jobs will be allowed to finish, but no new jobs
     will be started.  New jobs will still be accepted into  the  queue.
     It can be used to wind down operations preparatory to shutting down
     the system (see also  /STOP).   Don't  forget  that  you  must  use
     /RUNDOWN  whenever  you  SET /NOLOGON, or jobs may terminate due to
     logon failure.

          /CLOSEDOWN

          This switch puts  the  batch  system  in  a  state  where  all
     currently  running  jobs  will  be allowed to finish, all currently
     waiting jobs will be allowed to start and to run to completion, but
     no  new  jobs will be accepted into the queue.  This is a different
     condition to that implied by  /RUNDOWN.   Setting  /CLOSEDOWN  will
     cause the job queues to empty.

          /STOP

          This switch puts the queue in rundown, and  causes  BATMAN  to
     exit  when  all the currently running jobs have finished, providing
     there are no jobs in hold.  If there are jobs in hold, BATMAN  will
     exit when all the hold conditions have expired.  This switch can be
     used to terminate BATMAN activity, while still allowing jobs to  be
     accepted  into the queue.  If you wish to set /STOP at a particular
     time of day without being present, putting the task BQSTOP into the
     clock  queue  to  execute at the desired time will accomplish this.
     BQSTOP issues a BAT /STOP in internal form and  then  exits.   When
     BATMAN  finally  exits,  it  will  do  so  with an exit status of 4
     (severe error).  This is intentional.


                                                                  PAGE 6



          /RUNJOBS

          This switch clears all three conditions:  /RUNDOWN, /CLOSEDOWN
     and  /STOP.   If the queue is in rundown and closedown, the rundown
     condition alone can be  cleared  with  /RUNJOBS/CLOSEDOWN,  or  the
     closedown condition alone can be cleared with /RUNJOBS/RUNDOWN.

          /QUESIZE:n

          This switch sets the maximum  size  of  the  job  queue.   The
     number  of jobs, n, is octal by default;  to specify decimal append
     a decimal point.  The number  sets  the  largest  number  of  jobs,
     including executing jobs, that can be in the queue at any one time.
     The size cannot be set lower than the number of jobs already in the
     queue.  After the execution of this command, BAT displays

          QUESIZE=n:m

          where n is the (decimal) maximum queue  size,  and  m  is  the
     (decimal)  number of jobs currently in the queue.  This text can be
     displayed by omitting :n  on  the  switch  (just  /QUESIZE)  or  by
     specifying  a  zero  or negative switch value.  The assembly source
     VTTAB.MAC sets the default maximum queue size at 15(10) entries.

          /NEXTJOB:n

          This switch sets the number to be assigned  to  the  next  job
     accepted to be (n+1).  Again n is octal by default.  The value of n
     can be lower than the largest job number already in the queue,  but
     it should not be too close to avoid the situation arising where two
     different jobs might have the same job  number.   The  system  will
     function  correctly  under  such  circumstances, with the exception
     that the cancel or release commands may not be able to act  on  the
     right  job,  depending  on  the  order  of the jobs with duplicated
     numbers in the queue.  After the execution  of  this  command,  BAT
     displays

          NEXTJOB=n

          where (n+1) is the (octal) number that will be assigned to the
     next job submitted.  If /NEXTJOB is used without a switch value, or
     a zero or negative value is specified, BAT  will  display,  in  the
     above  format,  the  job  number  that was assigned to the last job
     accepted, or the value at the last /NEXTJOB  command  if  this  was
     later.

