BAT User's Guide
BAT USER'S GUIDE AND INSTALLATION NOTES
SMALL BATCH PROCESSOR FOR RSTS
By Jim Condict
Middlebury College
Middlebury, Vermont
June 22, 1977
BAT User's Guide
Introduction to BAT
1.0
PAGE 2
INTRODUCTION TO BAT
Sections 1 and 2 of this manual contain all the information necessary to run a BAT job. The rest of the manual describes in more
detail the operation of BAT and its capabilities. The sample run in
section 4.2 may be instructive to any level user.
1.1
AN INTRODUCTION TO BATCH PROCESSING.
Batch processing under RSTS allows one or more programs, hereafter referred to loosly as "a job" or "the job", to be run without
the need of being attended to from a terminal. Instead of typing in
all the commands and responses needed to run the job, the user puts
all the information necessary to execute the programs in the job into
a file, called a control file. A batch processing program is a program that takes the control file as input and runs the desired programs.
It usually reports the dialog that was necessary to run the
job in another file, called a log file. The batch program, therefore,
can take the place of an operator at a terminal when all the needed
terminal responses are known in advance. The greatest advantage of
using batch processing is when a job will take a long time and human
interaction is not needed, or when a task is to be performed repeatedly and the same terminal input is needed each time.
1.2
WHY BAT?
BAT is a powerful batch processor designed as an alternative to
the DEC supported BATCH program. Instead of operating detached and
accepting job requests through a queue, BAT starts its run at the
user's terminal and then detaches. At any point during BAT processing
the user may attach to BAT and abort the job.
For convenience, BAT
logs the user back in at his terminal as it detaches.
BAT was developed at Middlebury College to better meet the
for a batch processing program in three areas:
needs
1.
BAT takes up a minimun of overhead. The program runs in 6K
of core and runs only when a job is being processed. When
the job is not performing terminal I/O, BAT uses an average
of 1 KCT every 45 minutes, sleeping for 10 minute intervals.
Start-up overhead was reduced to a minimum to allow the job
to begin immediately.
2.
The log file produced is easily readable. The log contains
the terminal dialog just as it would appear at a keyboard
during the job run. LOGIN and LOGOUT dialog have been replaced each by one line giving the vital statistics of the
job. BAT control file commands are available for turning on
BAT User's Guide
Introduction to BAT
PAGE 3
and off the dialog reporting in the log file. Comments in
the control file may or may not be written in the log file.
Form feeds may be inserted in the log for neat printing on a
line printer.
3.
2.0
BAT is easy to use. The control file need only contain the
desired keyboard input; job control commands are unnecessary. BAT can be started by using the CCL "BAT <filename>" or,
if a job is very commonly executed, just typing "BAT" will
execute the control statements in a default control file.
RUNNING BAT
BAT may be started by the RUN command or as a CCL.
formats are:
USER:
BAT:
BAT:
USER:
The
starting
RUN $BAT
BAT - <system identification>
*
[<filename>] [/M] [/L]
or
USER:
BAT [<filename>] [/M] [/L]
where <filename> is the name of the control file to be processed.
If
the filename does not have an extension, a default extension of .BAT
is assumed. If the filename is not present, the default control file
is BATJOB.BAT on the user's account. The control file may be from
another account, if the user has read privileges on that file.
The
account specification must preceed the filename. If just "BAT" is
typed with no filename and BATJOB.BAT is not found, the program will
print the header and prompt as though it were a run entry. The two
optional switches may appear in either order. Their functions are:
/M
-
/L
-
Send a message to the user's terminal when the job is
finished.
(The same restrictions apply as to the
$: command.)
Lower the priority of the job to be run by one priority
level.
(See the description of the $LOW command for
details.)
BAT creates a log file on the user's account using the name of
the control file with the extension .LOG. Once these files have been
properly opened, BAT prints a message of the type:
BAT Job nn - JOBNAM Detaching ...
Please Wait ...
where nn is the number of the detached job under
which
BAT
will
be
BAT User's Guide
Operating BAT
PAGE 4
running, and JOBNAM is the user's name for the job, taken from the
control file name. After this message BAT detaches from the terminal
and runs the user's job from a detached state. Just after BAT detaches, it logs the user back in at his terminal by forcing HELLO and
the user's number and password to the terminal. The printing on the
terminal, however is disabled until LOGIN is through running and
prints its "Ready" message. The user then has free use of his terminal under the new job.
The BAT control may be created with an editor. It should contain
all the terminal dialog needed to run the programs and respond to any
terminal input they require. It need not, however, contain the commands to log in and out. That is handled by BAT. All lines in the
control file beginning with a dollar sign ($) are treated as special
commands by BAT. A detailed description of them are given below. If
the control file is to contain a line beginning with a $ character
that should not be interperated as a command, the line should begin
with a double dollar sign $$. BAT will ignore the first dollar sign
and process the rest of the line as normal terminal input to the controlled job.
The user now knows all he needs to know to write a
and run BAT.
3.0
control
file
BAT COMMANDS
Given below are the control file commands recognized by BAT.
Spaces and tabs may be inserted anywhere in the command lines for convenience of formatting the control file.
$$<text>
Send $<text> to job.
The first dollar sign will be ignored and $<text> will
to the job as normal terminal input.
$!<text>
be
Control file comment.
Any line beginning with a $! combination will be treated
control file comment line and ignored by BAT.
$&<text>
sent
as
a
Print text in log file.
The rest of the line following the $& will be printed in the log
file.
This command does not in any way affect the job being
run.
$:<text>
Send text to user's terminal.
The rest of the line following the $: will be printed out on
the user's terminal when the execution of the job reaches this
BAT User's Guide
BAT Commands
PAGE 5
point. This action will not interfere with the execution of either the job running under BAT or any job running on the user's
terminal. The message will only be sent if the user who started
the BAT job is still logged on at the terminal from which he
started it, or if the user is privileged.
$^<character>
Send control character to job.
The first character following the $^ will be treated as a control character and sent to the job when it is waiting for terminal input. This allows a CTRL/Z or a CTRL/C to be entered during a program run.
$LIMIT nn
Set program run limit to nn.
This command sets the program run limit to nn minutes.
This
does not limit the total job time or even the length of time for
which one program can run. The time that is limited is the time
between waits for input by the controlled job. Each time a line
of terminal input is entered from the control file, this time
restarts.
The default limit at the start of each BAT run is 30
minutes. This should be enough for almost any run.
$NO LIMIT
Do not limit program run time.
This command completely prevents a job from being halted by its
program run limit being exceeded. This may be desired for a
long compute-bound program whose total run time may not be easily estimated in advance. The $LIMIT and $NO LIMIT commands may
be used at any point in the control file to dynamically change
the program run limit.
$STOP
Stop running program.
This command assures that the running program will be stopped
after its next wait for input. This cannot be insured with $^Z
or $^C commands if the program running is designed not to terminate when one of these control characters is entered. The $STOP
command causes a ^Z to be entered as terminal response to the
program.
If the program does not stop in 10 seconds, BAT sends
a ^C to the program to stop it. If this doesn't work, a double
^C is sent after another 10 seconds. Finally, if the program
still is not stopped within 10 seconds, the controlled job is
killed and an error reported in the log file.
$LOW
Lower job priority.
This command lowers the priority by one level of the job being
run by BAT. It should be used for long jobs where the job completion time does not matter and where the job may slow down the
system.
Giving this command has the same effect as specifying
the /L switch when starting a BAT run. The /L switch causes the
priority to be lowered at the start of the job. The $LOW com-
BAT User's Guide
BAT Commands
PAGE 6
mand causes the priority to be lowered just before the next control file line is processed. The command may be given more than
once to lower the priority by more than one level. BAT does not
allow the priority to go below -120, which is the lowest priority a job may have and still run. There is no BAT command to
raise or restore the priority of a job.
$PAGE
New page in log file.
A form feed - carrage return combination will be printed in the
log file before the next terminal input from the control file.
$NOLOG
Turn log reporting off.
All normal terminal dialog starting with the next terminal input
from the control file will not be printed in the log file. Any
BAT error messages and any $& commands will stil be entered in
the log.
Note that if this command is given just before the
response to a question that will be printed out by the controlled job, the question will appear in the log file but the
response will not. The main use of the $LOG and $NOLOG commands
is to selectively not report whole program runs in the log file.
$LOG
Enable log reporting.
All terminal dialog starting with the next terminal
the control file will be printed in the log file.
default condition at the start of any BAT run.
$KILL LOG
input from
This is the
Kill log file at end of run.
After successful termination of the controlled job run, the log
file will be killed. This may be desired if many short BAT runs
are being made where the log file contains no useful information
the user does not want to keep these files in his directory. On
any abnormal job termination such as a "Run time limit exceeded"
error, the log file will not be killed.
BAT User's Guide
More on operating BAT
4.0
PAGE 7
HOW TO STOP A BAT RUN
If, during any part of a job run after BAT has detached from the
user's keyboard, the user wants to stop the job, he may do so by attaching to BAT and halting it with a single CTRL/C as follows:
USER:
ATTACH nn
SYSTEM: Attaching to job nn
USER:
^C
BAT:
Ready
where nn is the job number in the detaching message. The user is now
free to use the terminal. He may inspect the log file to deturmine
the point at which the controlled job was interrupted. If there are
any messages sent to the terminal during the job run, BAT will print
the same job number and user's job name for identification. Attaching
to BAT is the only proper way to stop a job run in progress. The user
should not attach to BAT unless he does so to kill the job.
4.1
MORE ABOUT BAT
Since BAT logs the user back in at his terminal, giving the user
a new job, anything assigned with the ASSIGN command before the BAT
run will not be assigned to the job at the terminal after BAT detaches.
To insure that any assigned devices will be available to the
new job, BAT deassignes all the devices from the detaching job as it
detaches.
In a BAT job run, the user may run LOGIN to change accounts
and/or job numbers. At the end of BAT's run it will report the current job number and current job run time in the log file.
At the beginning of each BAT run, the TTYSET option FORM is on
and WIDTH is set to 132 so the log file may be neatly printed on a
line printer. The user may reset any terminal characteristic by running TTYSET in his BAT job.
All line terminators in the
BAT.
If a line to be sent to
terminal ends with an escape, or
with that terminator. Note that
control file are passed unchanged by
the job or the log file or the user's
a form feed, etc., it will be sent
this is different from DEC BATCH.
BAT processes the control file in the following way:
It
gets
a
line from the control file and determines whether or not it is a command. If it is a command, it performs the required operation. If the
line is not a command or if it is a control character, BAT passes it
BAT User's Guide
More on operating BAT
PAGE 8
on to the controlled job. BAT then collects any output from the controlled job to the terminal and reports it in the log file unless $NO
LOG is in effect. When the controlled job is not outputting to its
terminal, BAT sleeps. BAT continues waiting and getting any terminal
output until the job enters a wait for input from the terminal or
until the program running stops. BAT then gets the next line from the
control file. If the time while BAT was waiting and getting terminal
output exceeds the program run limit time, BAT stops the job and reports the error in the log file. When BAT is ready for another control file line and there are no more lines in the control file, BAT
terminates the controlled job.
4.2
SAMPLE BAT RUN
Below is a sample BAT control file. The terminal dialog for the
BAT run and the listing of the output log file are shown on the next
page.
This is a listing of DEMO.BAT
----------------------------$!
$!
This control file demonstrates the use of BAT.
$!
$&
Test line to log file.
$&
$: Test message to keyboard.
$NO LOG
NEW TEST
10 !THIS TEST PROGRAM IS BEING CREATED DURING A BAT RUN.
20 PRINT "BAT TEST PROGRAM"
30 END
SAVE
$LOG
RUN
RUN $PIP
TEST.BAS
$STOP
PRINT TIME$(0%)
BAT User's Guide
Sample BAT run
PAGE 9
Below is the sample run of BAT.
------------------------------BAT DEMO/M
BAT Job 14 - DEMO Detaching ...
Please wait ...
Ready
BAT Job 14 - DEMO Message:
Test message to keyboard.
BAT Job 14 - DEMO Message:
Job terminating.
After the run, this is the listing of DEMO.LOG
---------------------------------------------RSTS V06B-02 MANIAC/11
[1,6]
Job 16 - DEMO
KB3
20-Jun-77
05:33 PM
Test line to log file.
RUN
TEST
05:34 PM
BAT TEST PROGRAM
20-Jun-77
Ready
RUN $PIP
PIP
V06B-03A
- RSTS V06B-02 MANIAC/11
#TEST.BAS
10 !THIS TEST PROGRAM IS BEING CREATED DURING A BAT RUN.
20 PRINT "BAT TEST PROGRAM"
30 END
#^Z
Ready
PRINT TIME$(0%)
05:34 PM
Ready
Job 16 terminated 20-Jun-77 at 05:34 PM.
Run time was 0:00:01.4
BAT User's Guide
BAT Command Summary and TBAT
5.0
BAT COMMAND SUMMARY
$$<text>
$!<text>
$&<text>
$:<text>
$^<character>
$LIMIT nn
$NO LIMIT
$STOP
$LOW
$PAGE
$NOLOG
$LOG
$KILL LOG
6.0
PAGE 10
Send $<text> to job.
Control file comment.
Print text in log file.
Send text to user's terminal.
Send control character to job.
Set program run limit to nn.
Do not limit program run time.
Stop running program.
Lower job priority.
New page in log file.
Turn log reporting off.
Enable log reporting.
Kill log file at end of run.
TBAT - TERMINAL BAT
TBAT was developed for applications where batch processing is desired and where the log of the batch run needs to be seen as soon as
possible.
TBAT operates similarly to BAT, but it does not detach from the
terminal and, instead of reporting to a log file, it prints the dialog
of the job run on the terminal as it happens. TBAT accepts the same
control file format as BAT and has the same control file name defaults. Its whole operation is very similar to that of BAT.
Given
below are all other differences between the two.
1.
The run entry for TBAT is RUN $TBAT. The CCL is TBAT or just
TB.
The control file name input procedure is the same as
that of BAT.
2.
There is no limit on TBAT program run time. All $LIMIT and
$NO LIMIT commands are ignored. The user may type CTRL/C at
any time to halt the controlled job and to stop TBAT.
3.
No terminal messages are sent to the terminal.
and the $: command are ignored.
4.
The terminal output appears just as the log file of BAT would
appear but all null characters are removed before printing.
The login and logout messages are also not given. The $KILL
LOG command is ignored.
5.
The only way to run at a lower priority
switch. The $LOW command is ignored.
is
The /M switch
through
the
/L
6.
The initial TTYSET settings for a TBAT run are
WIDTH 80.
NO
FORM
and
BAT Installation Notes
7.0
PAGE 11
INSTALLATION NOTES
BAT and TBAT should be compiled on the library account and stored as
$BAT.BAC<232>
$TBAT.BAC<232>
To add BAT and TBAT as CCLs, the following UTILTY commands
given:
should
be
CCL BAT-CH=$BAT.BAC;PRIV 30000
CCL TB-ATCH=$TBAT.BAC;PRIV 30000
These commands should also be added to any normal and
startup files.
crash
recovery
BAT and TBAT assume certain standard options on the DEC system
programs LOGIN and TTYSET. If these options have been changed at the
installation, further modifications must be made to insure the correct
operation of BAT and TBAT. What BAT expects from LOGIN and TTYSET is:
1.
BAT expects from LOGIN that the command "HELLOnn/nn;Password"
given at a logged out terminal will log the user in and not
ask "Job to attach to?" or any other question. It does not
matter how much text LOGIN prints out to the terminal, but
BAT is currently set not to print any of it in the log file.
BAT uses this command both to log in the controlled job and
to log the user back in at his terminal. Before it detaches,
BAT disables the echo at the user's terminal so that
HELLOnn/nn;Password is not echoed.
BAT expects LOGIN to
reenable the terminal echo before exiting.
2.
BAT
expects
TTYSET
to
respond
to
the
command
"SET FORM;WIDTH 132;LC INPUT" from a logged out terminal by
setting the characteristics. BAT gives this command to the
controlled job just before logging it in. The only way to
set pseudo keyboard characteristics under 6B is to set them
from a job having the pseudo keyboard as its console terminal. If different default terminal characteristics are desired (such as a narrower width), the SET command may easily
be changed in the source code of BAT.
TBAT has the same requirements of LOGIN and TTYSET as
its TTYSET command is just SET WIDTH 80;LC INPUT.
does
END OF BAT USER'S GUIDE AND INSTALLATION NOTES
BAT,
but