TOPS-20 Commands Reference Manual
SUBMIT
Enters a command procedure into the batch job queue.
Format
@SUBMIT (BATCH JOB) /switch(es) filespec/switch(es),...
where:
| switches | are keywords, chosen from the list below, indicating your choice of
SUBMIT command options. These switches have different effects according to
their position in the command line: placed before all files in the command,
they act as defaults for all; otherwise they affect only the nearest
preceding file.
Defaults are shown in the list of switches |
| filespec | is the specification of a batch control file (see the TOPS-20 User's
Guide), containing batch commands and the commands with which you would
have done the job as a timesharing user instead of as a batch user
Default file type - .CTL |
Summary of SUBMIT Command Switches (defaults in boldface)
| /ACCOUNT:account | Default account - your current account | ||
| /AFTER:date | and/or time | ||
| |||
| |||
| /BEGIN:n | Default n - 0 | ||
| /CARDS:n | Default n - 1000 | ||
| /CONNECTED-DIRECTORY:dev:<directory> | |||
| /DELETE | |||
| /DEPENDENCY-COUNT:n | Default n - 0 | ||
| /DESTINATION-NODE:node name | |||
| /FEET:n | Default n - 200 | ||
| /JOBNAME:6-character name | Default name - first six characters of control filename | ||
| |||
| /LOGNAME:filespec | Default filespec - control filename, file type .LOG | ||
| |||
| |||
| /PAGES:n | Default n - 200 | ||
| /PRIORITY:n | Default n - 10 | ||
| /PROCESSING-NODE:node name | |||
| /READER | |||
|
Default argument (if switch is given) - YES | ||
| /SEQUENCE:n | |||
| /TAG:6-character label | |||
| /TIME:hh:mm:ss | Default time limit (if switch is omitted) - 00:05:00
Default hh:mm:ss (if switch is given without colon or argument) - 60 (minutes) | ||
| /TPLOT:n | Default n - 200 | ||
| |||
| /USER:user | name |
SUBMIT Command Switches
| /ACCOUNT:account | specifies the account of 39 or fewer characters to charge for your
batch request. This account must be valid for your user name.
Default account - your current account (check with INFORMATION JOB-STATUS) | ||
| /AFTER:date and/or time, or day of week (or TODAY) and/or time | ensures that the job will not be started until after the date and/or
time specified. NOV-12-79, and 18:00:00 illustrate two arguments to this
switch. If you give both date and time, separate them with a space. When
given alone, the time may be preceded with a plus sign (+), which will
delay processing by the indicated length of time from the
present.
Alternatively, you may give a day of the week (such as MONDAY) or TODAY as argument; then the batch job will not be started until the beginning of the following day. If you follow this argument with a plus sign and a time, the job will be further delayed by this amount. | ||
|
tells the system whether your job will require the assistance of the
operator (for example, to mount a structure or magnetic tape) when it is
run
Default - YES | ||
|
tells the system either to append the log file of the batch job to any
existing log file of the same name, or to write a new generation of the log
file, or to send the log file to the spool area only.
Default - APPEND | ||
| /BEGIN:n | starts processing the control file at line n of the file. Use this
switch for a control file that can fit different applications depending on
where processing begins. (See also the /TAG switch.)
Default n - 0 | ||
| /CARDS:n | limits to n the maximum number of cards to be punched by the job.
Default n - 1000 | ||
| /CONNECTED-DIRECTORY:dev:<directory> | specifies the connected directory for the batch job. For privileged users only. | ||
| /DELETE | tells the system to delete the control file after the batch job has run. | ||
| /DEPENDENCY-COUNT:n | sets the job's dependency count to n. Because a batch job does not get
processed until its dependency count is 0, you can delay a job by assigning
it a positive dependency count and then using the MODIFY command to bring
the count to 0 at the proper time.
Default n - 0 | ||
| /DESTINATION-NODE:node-name | specifies the IBM remote job entry station on whose line printer the log file of your batch job is to be printed. Two colons (::) following the node name are optional. | ||
| /FEET:n | limits to n the maximum number of feet of paper tape to be punched by
the job.
Default n - 200 | ||
| /JOBNAME:name | assigns a name (of six or fewer characters) to the batch job.
Default name - first six characters of control filename | ||
|
tells the system whether to delete the log file after it has been
printed.
Default - KEEP | ||
| /LOGNAME:filespec | specifies where to place the log file of the batch job.
Default dev:<directory> - your connected directory at the time of the SUBMIT command Default filename - control filename Default type - .LOG | ||
|
tells the system whether to send a message to your terminal /xp /NOTIFY
switch when the batch job has been completed.
Default argument - NO Default argument (if switch is given) - YES | ||
|
says whether you want the log file to be printed always, or only in the
case of unhandled errors occurring within the job, or never. No matter
which option you choose, the log file is always written.
Default - ALWAYS | ||
| /PAGES:n | limits to n the maximum number of pages of line printer output to be
printed by the job.
Default n - 200 | ||
| /PRIORITY:n | assigns a decimal number n to the job, reflecting the urgency of the
batch request. This n must be from 0 to 63, with larger numbers receiving
earlier treatment. The system acknowledges this switch by displaying the
message [Priority has been modified].
Default n - 10 | ||
| /PROCESSING-NODE:node name:: | specifies the IBM host system on whose CPU the JCL batch job is to be run. Two colons (::) following the node name are optional. | ||
| /READER | tells the system that your control file is composed of card images, including control cards, on disk. For details see the TOPS-10/TOPS-20 Batch Reference Manual. | ||
|
decides whether the job should be started again if the system crashes
and is restarted.
Default argument - NO Default argument (if switch is given) - YES | ||
| /SEQUENCE:n | specifies that n, instead of a number supplied by the system, is to be the sequence number of the job. | ||
| /TAG:label | starts processing the control file at the line beginning with label::, where label is an alphanumeric name of six or fewer characters. Use this switch for a control file that can fit different applications depending on where processing begins. | ||
| /TIME:hh:mm:ss | limits the maximum amount of CPU time available to the job; given in
hours, minutes, and seconds.
Default time limit (if switch is omitted) - five minutes Default hh:mm:ss (if switch is given without colon or argument) - 60 (minutes) | ||
| /TPLOT:n | limits to n the maximum number of minutes of plotter time allowed for
plotter time allowed for the job.
Default n - 200 | ||
|
when submitting multiple batch jobs, tells the system whether to run
the jobs concurrently or at separate times. The control files must be
submitted while connected to the same directory; the control files can be
located in any directory. This switch applies to batch jobs submitted with
a single or multiple SUBMIT commands. See Example 5.
Default - YES | ||
| /USER:user | name specifies the user who is to be the owner of the batch request. For privileged users only. |
Output
Jobname, Request ID, and Time Limit
As soon as you complete a valid SUBMIT command, the system responds by printing, on your terminal, the jobname, request ID, and time limit for the job. Each control file you submit is a separate batch request, and is described on a separate line.
Characteristics
Switch Defaults Set by System Manager
The defaults shown in the list of switches are correct for most user sites. However, your system manager can change some of these default settings. The changes go into effect during system installation. The switches most commonly affected are: /CARDS, /FEET, /OUTPUT, /PAGES, /PRIORITY, /TIME, and /TPLOT.
Disposition of Log Files
The three SUBMIT command switches /BATCH-LOG, /LOGDISPOSITION, and /OUTPUT, control what happens to the log file of your batch job.
Where Written
The log file is always written as the job runs, either to the batch job's connected directory, or to a directory specified as argument to the /LOGNAME switch, or to the system's output spooling area (it is written to the spooling area only if you give the /BATCH-LOG:SPOOL switch). If the /DESTINATION-NODE switch is also given, the log file will be written into a directory or spooling area at the specified node. Remember that a batch job's connected directory is ordinarily defined to be your connected directory at the time of the SUBMIT command; privileged users may specify a batch job's connected directory by using the /CONNECTED-DIRECTORY switch.
How Written, When Printed
The /BATCH-LOG switch's APPEND and SUPERSEDE arguments describe the manner in which the log file is to be written: either it is appended to any existing file of the same name (usually produced by a previous running of the batch job) or it is written as a new generation of the file. The /LOGDISPOSITION switch tells the system whether to keep this file, wherever it is written, once the batch job is finished. The /OUTPUT switch specifies when you want a listing of the log file to be printed: either always, or never, or only if errors occur when the batch job is run. By using combinations of these switches you can cause any desirable action. Giving /OUTPUT:ALWAYS along with /LOGDISPOSITION:DELETE allows a record of your batch job with only a temporary use of your disk area, and permits you to monitor the progress of the job while it is running (give TYPE commands to view the file at your terminal). Giving just the /BATCH-LOG:SPOOL switch allows a record without any use of your disk area, although then you must wait for the printed output to see this record.
Execution of Command Files
As soon as one of your batch jobs logs in, the system processes your login directory's command files and the system's command files. The files are processed in this order:
- SYSTEM:BATCH.CMD
- BATCH.CMD
- SYSTEM:COMAND.CMD
- COMAND.CMD
If a LOGOUT command is included in the batch control file, the system processes your login directory's LOGOUT.CMD file followed by the system's SYSTEM:LOGOUT.CMD file. These files are not processed if the batch job is logged out automatically.
Automatic Logout
If the batch control file is not terminated by a LOGOUT command, the batch job is logged-out automatically and the message "KILLED BY OPERATOR TTYnn" is printed in the log file.
Hints
Using SET DEFAULT SUBMIT
If there are switches that you always or usually supply when using SUBMIT, give the SET DEFAULT SUBMIT command to establish them as defaults for the remainder of your terminal session. The switches will then behave as if you had typed them directly after the word SUBMIT. You can supersede any of these default switches by actually supplying the switch, with another value, when you give the SUBMIT command.
For Future Terminal Sessions
Put SET DEFAULT SUBMIT commands into a file named COMAND.CMD or LOGIN.CMD in your log-in directory if you want these default switches to be in effect for batch jobs you submit during future terminal sessions as well. If both files exist, the system reads LOGIN.CMD first.
For Nested Batch Jobs Only
Put SET DEFAULT SUBMIT commands into a file named BATCH.CMD in your log-in directory if you want them to be in effect at the log-in time of a "nested" batch job only, that is, a batch job started by a SUBMIT command within the control file of another of your batch jobs. Note, however, that the system also reads COMAND.CMD at the log-in time of a batch job if the file exists in your log-in directory. It reads this file after BATCH.CMD.
Monitoring the Progress of a Batch Job
You can include the SEND command or the commands that run the MAIL or DECmail/MS mail programs in your batch control file. Use these commands to send messages to your terminal informing you of the status of your batch job. Since a batch job creates a job in addition to your timesharing job, use the terminal line number argument instead of the user name argument in the SEND command.
More Information
For more information about batch jobs, see the TOPS-10/20 Batch Reference Manual.
Restrictions
Access Rights for Batch Jobs
For Specifying Control Files and Log Files
You cannot use the ACCESS command to obtain the right to submit control files from another directory, because your batch jobs are logged in with rights only to your connected directory and to directories to which you (through your login directory name) have access as a group member. The control file, if not in your connected directory, must be in one to which you have read access as a group member; the log file specification, if you give one, must be for your connected directory or for one to which you have write access as a group member.
For Use Within the Batch Job
Although it is possible to give CONNECT and ACCESS commands within a batch job to obtain rights beyond those mentioned above, you may then have to include passwords in the job's control file. Because this practice could endanger system security, it is generally best to establish and rely on appropriate group rights when preparing batch jobs for submission.
PUSH During Batch Job Execution
Note that a PUSH command reads the COMAND.CMD file. Therefore, if your batch control file contains a PUSH command, only the defaults set in COMAND.CMD are in effect while in the inferior EXEC.
Editing a Queued Control File
The batch system processes the exact version of the control file specified in your SUBMIT command. Therefore, if you edit a file while it is in the batch queue, the new version of the file will not be processed.
To change the request to process the latest version of the control file, CANCEL the request and resubmit the job.
Related Commands
| CANCEL | for withdrawing SUBMIT requests |
| INFORMATION BATCH-REQUESTS | for examining in the batch input queue |
| MODIFY | for changing SUBMIT requests before processing has begun |
| SET DEFAULT SUBMIT | for establishing default switches for subsequent SUBMIT commands |
Examples
- Submit a control file to begin a batch job.
@SUBMIT DIFS.CTL [Batch job DIFS queued, request-ID 461, limit 0:05:00]
- Submit two control files (specifying only the filenames) in the same
command. then use the information batch-requests command (with the /USER
switch) to examine your entries in the batch input queue.
@SUBMIT SUMS, DIFS [Batch job SUMS queued, request-ID 629, limit 0:05:00] [Batch job DIFS queued, request-ID 630, limit 0:05:00] @INFORMATION BATCH-REQUESTS /USER Batch Queue: Job Name Req# Run Time User -------- ---- -------- -------- * SUMS 629 00:05:00 C.BURKE In Stream:2 Started at 15:21:01 DIFS 630 00:05:00 C.BURKE There are 2 jobs in the queue (1 in progress)
- Connect to another user's directory, then submit two of his control
files. Prevent the printing of a log file for one job, and allow the
second job's to be printed only if errors occur within the job; make both
jobs restartable. Request an inclusive listing of your entries in the
batch queue - notice that the jobs are logged in under your own user name,
although the log files will be stored in user Holland's directory. Note
also that an asterisk (*) indicates a job currently in progress.
Connect back to your directory and submit one of your own control files, specifying a particular jobname, then check on it.
@CONNECT <HOLLAND> Password:___ @SUBMIT /RESTARTABLE:YES FLDTST.CTL/OUTPUT:NOLOG, LODT.CTL - /OUTPUT:ERRORS [Batch job FLDTST queued, request-ID 464, limit 0:05:00] [Batch job LODTST queued, request-ID 465, limit 0:05:00] @INFORMATION BATCH-REQUESTS /ALL/USER Batch Queue: Job Name Req# Run Time User -------- ---- -------- -------------------------------- * FLDTST 464 00:05:00 C.BURKE In Stream:2 /Uniq:Yes /Restart:Yes /Assist:Yes /Seq:1993 Started at 8:40:38 LODTST 465 00:05:00 C.BURKE /Uniq:Yes /Restart:Yes /Assist:Yes /Seq:1994 There are 2 Jobs in the Queue (1 in Progress) @CONNECT MISC:<C.BURKE> @SUBMIT SUMS/JOBNAME:1-SUMS [Batch job 1-SUMS queued, request-ID 466, limit 0:05:00] @INFORMATION BATCH-REQUESTS /ALL/USER Batch Queue: Job Name Req# Run Time User -------- ---- -------- -------------------------------- * 1-SUMS 466 00:05:00 C.BURKE In Stream:2 /Uniq:Yes /Restart:No /Assist:Yes /Seq:1995 Started at 8:41:29 There is 1 job in the queue (1 in progress) - Give a SET DEFAULT command to ensure that your batch jobs will be run
after 5:00 P.M. unless you specify otherwise. Submit a batch job and
check that this default is in effect. Then use a MODIFY command to delay
the starting time of this job till 11:00 P.M. Finally, give the CANCEL
command to withdraw the batch request entirely.
@SET DEFAULT SUBMIT /AFTER:17:00 @SUBMIT SUMS [Batch job SUMS queued, request-ID 467, limit 0:05:00] @INFORMATION BATCH-REQUESTS /USER Batch Queue: Job Name Req# Run Time User -------- ---- -------- -------------------------------- SUMS 467 00:05:00 C.BURKE /After: 9-Nov-85 17:00 There is 1 Job in the Queue (None in Progress) @MODIFY BATCH 467 /AFTER:23:00 [1 Job modified] @INFORMATION BATCH-REQUESTS /USER Batch Queue: Job Name Req# Run Time User -------- ---- -------- -------------------------------- SUMS 467 00:05:00 C.BURKE /After: 9-Nov-85 23:00 There is 1 Job in the Queue (None in Progress) @CANCEL BATCH 467 [1 Job canceled]
- Submit two control files, one located in your connected directory and
the other in a directory you are accessing. Use the /UNIQUE:NO switch to
allow the jobs to run simultaneously. Display the status of the batch
queue and note that both jobs are running.
@SUBMIT NETCOM.CTL, RANDOM:[LOWELL]CLEAN.CTL /UNIQUE:NO [Batch job CLEAN queued, request 58, limit 0:05:00] [Batch job NETCOM queued, request 59, limit 0:05:00] @INFORMATION BATCH-REQUESTS Batch Queue: Job Name Req# Run Time User -------- ------ -------- ------------------------- * CLEAN 58 00:05:00 DBONIN In Stream:0 Job# 156 Running EXEC Runtime 0:00:16 * NETCOM 59 00:05:00 DBONIN In Stream:1 Job# 156 Running EXEC Runtime 0:00:08 GTSTK 2 00:15:00 PURRETTA CIGIDN 3 01:00:00 CSSE.WAIBLE There are 4 jobs in the queue (2 in progress)