If you have a procedure that you execute frequently, you can submit it as a batch job rather than repeatedly executing it from your terminal.

To prepare to submit a batch job, enter the commands you would normally type on a terminal into a file called a batch control file. You can submit a control file to the batch system via a punched card deck or your terminal. Submitting this file creates a request for the system to run your job. The batch system logs your job in, executes the commands stored in the batch control file, and after executing the last command in the file, ends the job by logging it off. The batch system records the input and output of the job in a log file.

When you create a control file, use any filename and a file type of .CTL. Type each command and argument in full into the control file instead of abbreviated input. You must precede each TOPS-20 command and subcommand with an @. You must precede each program command with an *.

If you are including subcommands in a control file:

• place only one @ before a subcommand.
• place an @ before the RETURN that terminates the entire command.

You can create a BATCH.CMD file that is read by the system when your batch job is run. This file contains any TOPS-20 system commands you want executed every time you run the batch program. The BATCH.CMD file is similar to the LOGIN.CMD file the system reads every time you log in. Like the LOGIN.CMD file, a BATCH.CMD file usually contains commands such as the DEFINE command (to define logical names). Once the batch job is logged in, the system reads the BATCH.CMD file and executes the commands contained in it.

Your system manager can create a sytem-wide BATCH.CMD file. The file SYSTEM:BATCH.CMD is read by the system before reading your own BATCH.CMD file.

Do not include TERMINAL commands in a BATCH.CMD file.

The batch program does not recognize the TOPS-20 commands listed in Table 10-1. If you include them, the system issues a fatal error message. Be certain you do not include these commands in your control file, BATCH.CMD file, or COMAND.CMD file.

   Table 10-1:  Illegal Commands in Batch Jobs

     |--------------------------|
     |          ATTACH          |
     | SET CONTROL-C-CAPABILITY |
     |      SET TIME-LIMIT      |
     |           TALK           |
     |--------------------------|

To create a control file, place all the commands you usually type on your terminal into the file. The following example shows how to create a control file that runs the FILCOM program to compare two files and prints a file containing the comparisons:

        File TEST.CTL

             @FILCOM
             *SAMPLE.SCM=DATA.OLD,DATA.NEW
             @PRINT SAMPLE.SCM
             $

You can include the SEND command in your batch control file to send a message informing you when the batch job is done. Use SEND's line number argument and not the user name argument for this purpose.(Refer to Chapter 3 for more information on using the SEND command). You can also include a command to run one of the mail programs. (Refer to the TOPS-20 User Utilities Guide for information on the MAIL program or, if you are using the DECmail/MS mail program, refer to the TOPS-10/TOPS-20 DECmail/MS Manual).

To submit a control file to batch, give the SUBMIT command followed by the name of the control file. The SUBMIT command places the job in a waiting line called the batch input queue. When batch can accommodate another job, it selects one from the input queue.

The example below shows how to submit the TEST.CTL control file. Because the control file has the file type .CTL, you do not need to include the file type in the command.

        @SUBMIT (BATCH JOB) TEST
        [Job TEST Queued, Request-ID 105, Limit 0:05:00]

You can submit more than one control file to batch with the same SUBMIT command. The following example shows how to submit TEST.CTL and DATA.CTL:

        @SUBMIT (BATCH JOB) TEST,DATA
        [Job TEST Queued, Request-ID 106, Limit 0:05:00]
        [Job DATA Queued, Request-ID 107, Limit 0:05:00]

Where you place switches in a SUBMIT command line determines the files affected by the switch.

If you place a switch after the command but before you give the filenames, all the files are affected by the switch. A switch that affects all files is called a global switch. In the following example submit TEST.CTL and DATA.CTL using a global switch /AFTER:.

        @SUBMIT (BATCH JOB)/AFTER:8-Jun-88 TEST,DATA
        [Job TEST Queued, Request-ID 108, Limit 0:05:00]
        [Job DATA Queued, Request-ID 109, Limit 0:05:00]

If you type a command followed by a filename, a switch, and another filename, only the file preceding the switch is affected. A switch that affects only one file is called a local switch. The following example shows how to submit TEST.CTL using a local /AFTER: switch and DATA.CTL:

        @SUBMIT (BATCH JOB) TEST/AFTER:10-Jun-88,DATA
        [Job TEST Queued, Request-ID 110, Limit 0:05:00]
        [Job DATA Queued, Request-ID 111, Limit 0:05:00]

10.1.3.1 Setting Defaults for the SUBMIT Command - If you want the SUBMIT command to always contain certain switches, give the SET DEFAULT SUBMIT command, followed by the switch or switches. To give the /OUTPUT: switch with SUBMIT commands, place the following command in COMAND.CMD:

        @SET DEFAULT (FOR) SUBMIT /OUTPUT:NOLOG

To check the progress of the batch job, give the INFORMATION BATCH-REQUESTS command. The system prints a list of all the jobs in the batch queue and their status. Certain switches specified in the SUBMIT command appear in the queue listing. The system lists these switches if their value is not the default.

To print only the status of your job, use the /USER switch with the INFORMATION BATCH-REQUESTS command. To print the status of another user's job, use the /USER: switch, followed by the user's name.

        @INFORMATION (ABOUT) BATCH-REQUESTS

        Batch Queue:
        Job Name  Req#  Run Time            User
        --------  ----- --------  -----------------  
        * VNP20    102  00:07:00  SROBINSON                In Stream:1
            Job# 32 Running EXEC Runtime 0:00:00
        * CROSS    103  00:05:00  SROBINSON                In Stream:2
           Started at 08:31:09
          FOO        3  00:05:00  RETI                     /Proc:CALL37
          DATA     111  00:05:00  SARTINI
          GALAXY   104  00:10:00  SAMBERG
        There are 5 Jobs in the Queue (2 in Progress)

The system places the output from a batch job into a log file. A log file has a filename that is the same as the job name, and a file type of .LOG. Unless you specify otherwise, the system automatically sends the log file to the line printer, but also leaves a copy of it in your directory.

Give the DIRECTORY command to see that the log file is in your directory with the control file.

        @DIRECTORY (OF FILES) TEST

           AURORA:<HIGGINS>
           TEST.CTL.1
             .LOG.1

        Total of 2 files

The following example contains the log file from the batch job, TEST.CTL.1.

                             17-Oct-88 13:20:34

   BATCON Version  5(6057)                 GLXLIB Version  5(1247)

               Job TEST Req #88 for EMORRILL in Stream 1

           OUTPUT:  Log                            TIME-LIMIT: 0:05:00
           UNIQUE:  Yes                            BATCH-LOG:  Append
           RESTART: No                             ASSISTANCE: Yes
           ACCOUNT: 341                            SEQUENCE:   1435
           Input from => PUBLIC:<EMORRILL>TEST.CTL.1
           Output to  => PUBLIC:<EMORRILL>TEST.LOG

   13:20:36 USER    TEAL, Accounting Dept., TOPS-20 Monitor 7(7)
   13:20:36 MONTR   Job 290 on TTY246 17-Oct-88 13:20:36
   13:20:39 MONTR  [PUBLIC Mounted]
   13:20:39 MONTR
   13:20:39 MONTR  [CONNECTED TO PUBLIC:<EMORRILL>]
   13:20:39 MONTR  @FILCOM
   13:20:41 USER
   13:20:41 USER   **SAMPLE.SCM=DATA.OLD, DATA.NEW
   13:20:43 USER
   13:20:43 USER   No differences encountered
   13:20:43 USER
   13:20:43 USER   *^C
   13:20:43 MONTR  @@PRINT SAMPLE.SCM
   13:20:44 MONTR  [Printer job SAMPLE queued, request #89, limit 3]
   13:20:44 MONTR  @
   13:20:46 MONTR  Killed by OPERATOR, TTY 233
   13:20:46 MONTR  Killed Job 290, User EMORRILL, Account 341, TTY 246,
   13:20:46 MONTR    at 17-Oct-88 13:20:46,  Used 0:00:02 in 0:00:12

The system begins each line in the log file with the time the line was processed. The system prints a code following the time that indicates the job state: at TOPS-20 command level (MONTR) or at program command level (USER). Other codes may appear as well. The remainder of the line contains system output and the lines in the control file.

The system checks that the job is at TOPS-20 command level before it processes a TOPS-20 command in the control file. Since the first command in the control file is FILCOM, the job enters FILCOM command level. The next TOPS-20 command in the control file is PRINT. Because the job is at FILCOM command level, the system must give a CTRL/C to return to TOPS-20 command level before it processes the PRINT command.

For a detailed description of batch, refer to the TOPS-10/TOPS-20 Batch Reference Manual.

To change and/or add one or more switches to a previously issued SUBMIT command, give the MODIFY command. After you give the MODIFY command, type BATCH, followed by the first six letters of the jobname, or the request ID; then type the switch you want to change or add.

You can modify almost all SUBMIT command switches. To obtain a list of switches you can modify, give the MODIFY BATCH command, followed by a slash (/) and a question mark (?). The system prints a list of switches you can modify, and reprints the command line.

        @MODIFY (REQUEST TYPE) BATCH/? Switch, or parameter to modify, one 
        of the following:

         /AFTER:              /BEGIN:              /CARDS:
         /DEPENDENCY-COUNT:   /DESTINATION-NODE:   /FEET:
         /JOBNAME:            /OUTPUT:             /PAGES:
         /PRESERVE            /PRIORITY:           /PROCESSING-NODE:
         /RESTARTABLE:        /SEQUENCE:           /TIME:
         /TPLOT:              /UNIQUE:             /USER:
        @MODIFY (REQUEST TYPE) BATCH/

In the following example, modify the batch job TEST.CTL by adding the /AFTER: switch and the date August 15, 1988:

        @MODIFY (REQUEST TYPE) BATCH (ID) TEST/AFTER:15-AUG-88
        [1 Job Modified]

To remove entries you have previously placed in the batch input queue, give the CANCEL command. After you give the CANCEL command, type BATCH, followed by the first six letters of the jobname or the request ID of the job you want to remove.

Once the CANCEL command removes the entry you specify from the batch queue, the system notifies you of the removal by printing the message [1 Job Canceled]. If the system is processing the entry in the queue when you give the CANCEL command, it stops the job and prints the message, [1 Job Canceled, (1 was in progress)].

In the following example, remove the batch job TEST.CTL.

        @CANCEL (REQUEST TYPE) BATCH (ID) TEST
        [1 Job Canceled]

If you have several batch jobs running, you can cancel them all by using an *. Give the CANCEL command, followed by the request type you want to cancel; then type an * instead of a job name. The following example shows how to remove all of your batch jobs:

        @CANCEL (REQUEST TYPE) BATCH *
        [2 Jobs Canceled]