BATCH SYSTEM USER'S GUIDE BATCH SYSTEM VERSION 2.47 JULY 1982 BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 2 INTRODUCTION Introduction ------------ The batch system is a means by which a program may be put into a queue of jobs waiting for execution. Jobs in the queue are executed as needed resources become available. This system provides reduced terminal use and better turnround for users running long jobs. To use the batch system, a user enters a list of commands to be processed into a file called the "job description file". A simple job description file might contain only a single RUN command. These commands can then be queued for execution by the batch system. A later section details how to construct your job description files, with examples. To enable users to run programs on the batch system in the same form as they are run on any terminal in the normal fashion, the batch system employs a special software construct called the "virtual terminal". As the name implies, this involves setting up the software so that the RSX-11M Operating System thinks that it is doing I/O to a real terminal, when in fact there is no hardware involved. To do this involves having a virtual terminal driver in the system which intercepts all requests that would normally be sent to the usual terminal driver. The virtual terminal driver's details of operation will normally be of no concern to the user using the batch system, since its intervention is completely transparent to the user. However, having no terminal keyboard involved means that it becomes a little difficult to enter terminal input. To overcome this, the STACK command is provided. This command puts a batch job into direct connection with the virtual terminal driver for the purposes of entering the equivalent of normal terminal input. The STACK command is easy to use, and is described in detail in a later section. When a batch job is started by the batch system, the user is logged on to the virtual terminal (using parameters given by the user when the job was submitted) in the same fashion as if the user had logged on at a normal terminal. The commands contained in the job description file are then executed one by one until the last command has finished processing. The user is then logged off the virtual terminal, and the next user in the batch queue is logged on for his job to run. System accounting remains the same as at normal terminals, with the exception that since there is no hardware involved, there is no charge for connect time. While the batch job is executing, all the output that would normally have gone to the terminal is stored on disk by the batch system in the "log file". The log file is created by the batch system with a filetype of LOG and a version number equal to the number of the batch job (see later). The name of the log file will be the same as the name of the job description file. When the batch job is complete, the log file is automatically listed on the line printer. The batch system allows very long jobs to run in short segments by resubmitting themselves, so that long programs can run for several days with no user intervention. This sort of scheme provides a much better turnround for these users, since the job can execute BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 3 INTRODUCTION without tying up a terminal for long periods. Hence, long jobs can run during the daytime instead of just at night, which has previously been the case. Any command that is legal at a normal terminal is allowed in a batch job, with a few minor exceptions. For example, the SET commands that can be used to set terminal characteristics, such as SET /LINES=TI:, SET /BUF etc., will be accepted but will have no effect. The BYE command must *never* appear in a job description file. All logoff processing is performed automatically by the batch system. If BATMAN detects that a BYE command has been issued from within a batch job, all further processing for that account will be halted. Also, a virtual terminal should never be explicitly referred to in a batch job. All input/output requests for the 'terminal' should be directed to the pseudo device TI:, as at a normal terminal. The user has no control over which batch stream a job will eventually execute in, and so explicit use of a virtual terminal device name and unit number may be regarded as a privilege violation by the virtual terminal driver if it happens to be a different one to which the job is running on. System load is lower when a job is run in the batch system since a virtual terminal provides no interrupts that have to be serviced by the Executive, unlike a normal terminal. Although the operation of the batch system appears to be very simple to the user, it is in fact rather complex internally. The system consists of several components: (i) The BATCH command. This is a normal MCR command that allows users at an interactive terminal to submit jobs into the batch queue, and to manipulate them at later times if necessary. The BATCH command is the normal user interface to the batch system. (ii) The Batch System Queue Manager Program (BATMAN). This is a system program which is permanently executing. Its function is to supervise the operation of the batch system, to start up jobs and to generally check that all is well. Although always running, it adds very low overhead to normal system operations. Another function of BATMAN is to supervise the construction of log files for each running batch job. It does this by issuing a read to the virtual terminal driver. When a line of output is received by the driver from a batch job, an Asynchronous System Trap (AST) is effected within BATMAN, which then writes the line of output received into the appropriate log file. This AST mechanism is used to allow BATMAN to simultaneously write log files and to start/finish jobs on multiple job queues. The inner details of BATMAN will not normally be of concern to the user of the batch system. It should be noted that the Batch System Queue Manager is a different program and has no connection with the Print Spooler Queue Manager program (QMG...) described in the RSX-11M documentation. (iii) The virtual terminal driver itself, and the associated BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 4 INTRODUCTION data structures. The virtual terminal driver was written specially for the batch system, and has no connection with the virtual terminal driver described in the RSX11-M I/O Driver's manual. (iv) The STACK command, as mentioned above. (v) The TAPE command, which allows a batch system job to load a magnetic tape for processing. The TAPE command is discussed in a later section. The current structure allows for up to four batch jobs to be executing concurrently, that is, there are four virtual terminals available to the batch system onto which it may log users and run their jobs simultaneously. If there are more than four jobs in the queue, the additional jobs wait until one of the executing jobs finishes before the batch system will attempt to log it on to one of the virtual terminals. Different batch streams have different scheduling limits which may vary according to the time of day. A list of the current values is usually posted on the computer room wall. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 5 INTRODUCTION The BATCH command --- ----- ------- To submit a request to the batch system, the user issues a command of the form BATCH command-line where "command-line" is a command line containing BAT commands (see below), and represents a carriage return. Only the first three letters of the command name are necessary; the final "CH" is optional. Alternatively, if several commands are to be issued, the following form of the command can be used BAT BAT>command-line BAT>command-line BAT>^Z BAT exits when a CTRL/Z is typed in a similar manner to other system utility programs (PIP, F77, TKB etc.). CTRL/Z is echoed at the terminal as ^Z. The prompt "BAT>" is typed out by BAT to solicit input. A line of input may begin with a semi-colon, when it is treated as a comment and ignored. Blank lines (entered by pressing RETURN alone) are also ignored. BAT may also be activated by issuing the command RUN ...BAT In this case, the prompt is produced and BAT waits for input. A user may want to issue the same sequence of BAT commands on a number of different occasions, for example, to submit the same job description file for processing on different days. To permit this, BAT allows commands of the form BAT @filespec where "filespec" is a standard RSX-11M file specification giving the name of a file which contains BAT commands. For example, suppose a user wanted to list the batch queue, submit a job, and then list the batch queue again. The following might be an example of the commands issued BAT /LI BAT BATJOB/PA:PSWD BAT /LI Equivalent to this would be BAT BAT>/LI BAT>BATJOB/PA:PSWD BAT>/LI BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 6 THE BATCH COMMAND BAT>^Z The latter form is recommended for multiple command requests. (Note that in the above example, there would have been output from BAT after each command; this has been omitted in this example for clarity.) If the file MOBILE.CMD contained the lines /LI BATJOB/PA:PSWD /LI then an equivalent procedure to the above example would have been BAT @MOBILE Comments may be included in indirect command files by prefixing them with a semicolon in column 1. An indirect command file specifier is also allowed as input to the BAT> prompt; it is not restricted to the MCR command line as in the example above. In using indirect command files in this manner, the following points should be noted: 1. If a device is not specified with the "filespec" parameter, BAT assumes that the file is to be found on the user's SY: disk (the system disk in most cases). 2. If a directory is not specified, BAT searches the directory currently in use as the default for the specified file. 3. There is no default for the name of the file. 4. The filetype defaults to CMD if not specified. 5. If a version number is not specified, the latest version of the file is used. 6. Indirect command files may only be nested to a depth of one; that is, an indirect command file cannot contain another indirect command file specifier. An error message is produced and the current scan is terminated if an indirect command file at a nesting depth of two is detected. An error message is generated if the specified file can't be found, or if there is a syntax error in the command line. Because of the relative complexity of the batch system, there are a large number of different error messages that can be produced. These are all grouped together in a later section together with an explanation of their meaning and probable cause. For example, if the user was running under a UIC of [304,67], and the latest version of file MOBILE.CMD was 17, then BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 7 THE BATCH COMMAND BAT @MOBILE is equivalent to BAT @SY0:[304,67]MOBILE.CMD;17 The commands accepted by BAT fall into six classes: 1. Commands that submit a job for execution in the batch system. The job is added to the list of jobs waiting for execution according to the options specified in the command line. 2. Commands that remove a previously submitted job from the batch queue, or cancel a batch job that is already executing. 3. Commands to list the contents of the batch queue. 4. Commands that can release a previously submitted job from hold status, if it was put in a hold condition when it was submitted. 5. A further class of commands is available which can only be used by a system operator. These are used to perform various queue maintenance functions. There is only one command in this class that is available to the general user; this is the /ID command which is described in a later section. The remaining commands in this class are not documented in this manual. It is not permitted to include commands from more than one class in the same command line; doing this results in the command being flagged as ambiguous, and ignored. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 8 JOB SUBMISSION COMMANDS Job Submission Commands --- ---------- -------- To submit a single job for execution by the batch system, the BAT command takes the form BAT filespec/sw1/sw2... where "filespec" is the file specification of the job description file, and /sw1 and /sw2 are switches chosen from the list given below. The same defaults apply to the job description file as to an indirect command file, with the execption that there is a default filename of "BATCH". There are also considerations pertaining to the use of the version number (see the description of the /EV switch below). At least one switch must be specified. Each switch consists of a slash followed by two characters. Certain switches allow their actions to be nullified by negating the switch. To negate a switch, two forms may be used, for example, /NOSW or /-SW are both negated forms of the switch /SW. The switches that can be negated in this fashion are identified below. The following is a list of the switches that can be used to control the submission of a job: /TL:n Specify the time limit of the job. Here "n" is a number which gives the time limit in minutes. It is octal radix by default; to specify decimal, the number should be followed by a decimal point. The time involved is the CPU time used by the job, which means that the job will probably stay executing for a period of clock time that exceeds this amount. If the /TL switch is not used to specify the time limit, a default of 30 minutes will be used. No job will be accepted with a time limit greater than 10 hours (that is, /TL:600. or /TL:1130). The /TL switch cannot be negated. /LN:n Specify the output limit of the job, that is, the number of lines that can be written to the log file. The system will not adhere to this figure exactly; a job may be permitted to exceed it slightly but will never be aborted before the limit is reached. The line count "n" is octal radix by default; to specify decimal, the number should be followed by a decimal point. If the /LN switch is not used to specify the BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 9 JOB SUBMISSION COMMANDS line limit, a default of 2048. lines (approximately 34 pages) will be used. No job will be accepted with a line limit greater than 6144. (approximately 102 pages). The /LN switch cannot be negated. /PA:pswd This switch is used to supply the password that will be used to log on your batch job. If you do not wish to display your password on the terminal, omit this switch. In this case, BAT will prompt you for the password by typing ENTER PASSWORD: You can then type in your password. It will not appear on the terminal, as BAT does a read-with-no-echo, just like the HELLO command. If BAT is to be used from within a batch job to submit another batch job, you can use the special form /PA:*. This is an indication to BAT to use the same password as was used to submit the batch job in which BAT is currently running. This avoids having listings of the batch job log files that have your password displayed on them. The form /PA:* is legal only when used in a batch job. If you are using the form of BAT where multiple commands can be typed in in response to a prompt, then it is only necessary to enter the password for the first job that you submit; BAT uses the first password you enter as the password for all the batch jobs. It is still legal to specify /PA again if you wish, although the new password that you supply will be used to submit all further jobs. This can be useful if you mis-spell your password the first time round. Note that BAT does not access the system account file to check your password (there would be no need to type it in if it did), so if you enter a wrong password, the batch job will fail! The /PA switch can not be negated. /EV This switch is used to specify an explicit version for the job description file. If this file specification did not contain a version number, then this switch can be used to specify that the latest version of the job description file AS THE DISK CURRENTLY EXISTS is the one to be used to run the batch job. If you do not specify this switch, then the job will be started with the latest version of the job description file AS THE DISK EXISTS WHEN THE JOB IS STARTED. This provides the ability to edit the file between submission and execution time and still have the right one executed. An explicit version number on the job description file specification in the command line is equivalent to specifying /EV, that is, it will be the version used to run the job however many edits of the job description file you may do. The /EV switch may be negated, and the default is /-EV. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 10 JOB SUBMISSION COMMANDS /TR Trace job description file execution. This switch has the same meaning as the /TR switch used on indirect command files normally (see the Operator's Procedures Manual for a description). This switch may be negated, and the default is /-TR. /DE Specifying this switch will cause the job description file to be deleted when the job has finished running, providing that it does not terminate abnormally. This switch can be negated, and the default is /-DE. /HF:n This switch is used to put the job into hold for the specified number of minutes. The default radix for "n" is octal. To specify decimal, append a decimal point. Any positive value less than 32,767 (decimal) may be specified. The special values -1 to -7 can be used to put the job into hold for the specified number of days (any other negative value is illegal). For example, /HF:-2 is equivalent to /HF:2880. (or /HF:5500). A job in hold is not eligible for starting until the specified time has elapsed, even if the queue is idle. This switch may be negated only in special circumstances (see below). By default a job is not put into a hold state, that is, it is immediately eligible for execution, when submitted from a normal interactive terminal. When a job is submitted from within another batch job, the default is /HF:1, that is, the job is not eligible for execution for one minute after submission. The intent of this is to avoid a great deal of short jobs from preventing the long ones from ever starting. /HU:hh:mm This switch is used to put the job into hold until the next occurrence of the specified time of day. The values are assumed to be decimal, and any omitted value defaults to zero. For example, /HU holds the job until midnight (as does /HU::), /HU::27 holds until 00.27 am, /HU:14 holds until 2 pm, and /HU:17:46 holds until 5.46 pm. This switch may be negated in special circumstances, when any switch values are ignored. Obviously it is illegal to use both /HF and /HU to submit the same job. For both /HU and /HF, the batch job will be removed from the hold queue and placed into the eligible-for-execution queue within 15 seconds of the specified time elapsing. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 11 JOB SUBMISSION COMMANDS /EX This switch identifies the job as an "express job". Such jobs are immediately eligible for execution (subject to the queue being available) regardless of time limit, providing that the job has not also been put into a hold condition. Express jobs are executed in the order in which they are submitted. They are intended for system maintenance use only, and can only be submitted by privileged users. If you have work to do which is very urgent, it can be arranged for you to submit jobs into the express class to obtain the best possible turnround. This switch can be negated, and its default is /-EX. /RS This switch can be used to specify that the batch job is restartable. Any job with the restartable attribute will be re-run *from the beginning* should the system crash while the job is running. If the job has less than approximately 18.2 minutes left to run this switch will have no effect, that is, the job will not be considered restartable (the 18.2 minute limit is equivalent to 2**16-1 ticks of a 60-cycle clock). Before using this switch, you should be aware of the possible effects on your files if a job duplicates any previous operations. The /RS switch can be negated, and the default is /-RS, that is, by default a batch job is not restartable. Any job that is in the queue but is not yet running will always be restored to the queue in the event of a crash, regardless of its time limit or /RS setting. In the event of a queue restore after a crash, you should be aware that your job will be given a different job number than it originally had. There are some considerations pertaining to the use of parameter lists (see below) in restartable jobs; these are discussed in the section on writing your job description files. /PM:parm1:parm2:parm3:parm4 This switch allows you to specify up to four "parameters" for your batch job. A "parameter" in this context is a string of up to 10 characters that can be substituted at any desired points in the job description file when the job is run; this capability is discussed in more detail in the section on writing job description files. It allows great flexibility in constructing job description files dynamically at job submission time. Up to four parameters may be specified, and any printable characters (except commas and obviously colons; spaces are ignored also) are allowed in each parameter. Any characters specified in a parameter beyond the 10th are ignored with no warning. If any parameter field is blank, then it is ignored and any following parameters are left shifted to take their BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 12 JOB SUBMISSION COMMANDS place. For example, the switch /PM::STRING1?:STRING2! is equivalent to /PM:STRING1?:STRING2! and specifies two parameters, "STRING1?" and "STRING2!". Since all spaces are removed from the command line by BAT before it is analysed, it is not possible to specify a blank parameter using the /PM switch. The /PM switch can be negated, and its default is /-PM, that is, no parameters will be passed to the job. You should see the section on writing job description files for information on using parameter lists with restartable (/RS) jobs. /KE If this switch is specified at job submission time, the log file will be created and written in the directory corresponding to the logon UIC of the user who submitted the job. After the job has finished and the log file has been printed by the system (see also /NO below), the log file will not be deleted, but will remain in your directory for whatever functions you wish to perform on it. The default for this switch is /-KE, which implies that the log file will be created in a system directory, and will be deleted when it has been printed. It is the users' responsibility to ensure that a log file that is being written in that users' directory is not tampered with in any way while the job is running. Corruption of the log file in this way is a certain way of losing any further output from the batch job, and it does not guarantee that the job will finish running either. The system directory currently in use by the batch system is [1,71], but BATMAN sets the protection masks of log files so that users will not be granted access to their log files if they are to be written to this directory. /NO If this switch is specified the batch job's log file will not be listed on the line printer when the job has finished running. It makes sense to use this switch only in conjunction with the /KE switch, since users will not have access to active log files in the system directory. If /NO is specified and /KE is not, it will be ignored with a warning message. The /NO switch can be negated, and its default is /-NO. /IM This switch puts the BAT command into "immediate mode". A new version of the job description file is created (it need not exist already). If a version number is specified and the file does not exist, the specified version is created. If the specified version of the file already exists, it is overwritten. BAT then asks for input by typing BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 13 JOB SUBMISSION COMMANDS ENTER COMMANDS: * You may enter commands in response to the * prompt. The line of input goes into the file as part of the new job. On receiving a blank line (RETURN only), BAT closes the file and submits the job in the normal fashion. If an I/O error occurs, the file is deleted, the user is informed of what has happened, and job submission is not attempted. This can also be achieved by typing CTRL/Z in response to the * prompt. If the job could not be submitted for other reasons, for example, the job queue was full, the file is not deleted and remains on the disk to be submitted at a later time. When a file is created by BAT, it is given an initial size of 1 block, and its size is extended by 1 block increments if necessary. This is a space saving device, since most job description files are small and the usual initial allocation for a new file is 5 blocks. The /IM switch is illegal from within a batch job. It can be negated, and the default is /-IM. When a job is submitted successfully, the batch system assigns it a unique "job number". The job number is the means by which the batch system identifies the job, and it must be known by the user in order to cancel the job or remove it from hold. A successful job submission is followed by the message BAT -- JOB 27 ACCEPTED where the job number assigned is given (it is octal). If you forget the number of your batch job(s), the batch queue listing commands (see later) can be used to find out the numbers of jobs that you have in the queue. Multiple jobs can be submitted in a single command line by following the first submission command with a list of other job descriptions files, separated by commas. For example, the command BAT JOB1/PA:pswd,JOB2,JOB3 submits three jobs, JOB1.CMD, JOB2.CMD and JOB3.CMD. Any switches that are specified must follow the first job description file specification. If the above command had been written BAT JOB1,JOB2,JOB3/PA:pswd then it would have been rejected with a command syntax error message, since there were no switches on the first job description file to specify its disposition (BAT scans the command line from left to right). Any conditions that are set up by switches, such as time limit, hold, delete, etc. apply to all other job description files specified in the same command line (but not in BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 14 JOB SUBMISSION COMMANDS subsequent command lines) unless the switch is explicitly used again to alter those conditions. If a switch is used again on a command line in this manner, then the conditions implied by it also apply to any jobs following it on the command line. For example BAT JOB1/PA:pswd,JOB2/TL:45.,JOB3 This command submits three jobs: JOB1.CMD with a time limit of 30 minutes (since /TL was not used on the first job description file specification), and JOB2.CMD and JOB3.CMD, both with time limits of 45 minutes. A more complex example is BAT TEMP1/IM/DE/PA:pswd,JOB3/-IM/PM:XYZ,JOB5/-DE/TL:45./-PM/RS Here the BAT command prompts for commands that are to be entered in the file TEMP1.CMD. This job will be submitted, and the file TEMP1.CMD will be deleted when the job has run. Since immediate mode is nullified on the second job by virtue of the presence of the /-IM switch, the file JOB3.CMD, which already exists (hopefully) is used to submit a second job. This file will also be deleted when the job has run, since /DE was used for the first job and this condition still holds for the second job. The third job submitted is JOB5.CMD, and this is neither an immediate mode command, nor will the job file be deleted when the job has run. JOB5.CMD has a time limit of 45 minutes. Both TEMP1.CMD and JOB3.CMD have the default time limit of 30 minutes. One parameter ("XYZ") will be passed to JOB3; the other jobs will have no parameters passed. The restartable attribute is attached to JOB5. The above example is equivalent to BAT BAT>TEMP1/PA:pswd/IM/DE BAT>JOB3/DE/PM:XYZ BAT>JOB5/TL:45./RS BAT>^Z The number of parameters passed to each job in a multiple submission command line is determined by the first /PM switch. For example, the command BAT JOB1/PM:ONE:TWO:THREE,JOB2/PM:FOUR:FIVE,JOB3/PM:SIX passes three parameters to each job, and is equivalent to BAT BAT>JOB1/PM:ONE:TWO:THREE BAT>JOB2/PM:FOUR:FIVE:THREE BAT>JOB3/PM:SIX:FIVE:THREE BAT>^Z If you want to pass a different number of parameters to each job, they must be submitted on different command lines. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 15 JOB SUBMISSION COMMANDS If one job is submitted using /HF, and a second job is submitted on the same command line using /HU, or vice versa, the first hold condition must be nullified to avoid having the command flagged as ambiguous. For example, the command BAT JOB1/HF:5,JOB2/-HF/HU:13:30,JOB3/-HU/TL:100 is equivalent to the sequence BAT BAT>JOB1/HF:5 BAT>JOB2/HU:13:30 BAT>JOB3/TL:100 BAT>^Z Note that in this example, BAT would prompt for the password, since it was not specified on the command line. Also, the third job will be submitted with a time limit of 64 minutes, since octal radix was implied for the time limit by the missing decimal point. If the /HU or /HF switches are negated as in this example, then any values that may accompany them are ignored. The number of jobs that can be submitted on one command line is limited only by its length (79(10) characters maximum). For example, the command BAT CRUNCH.P64/TL:20./PA:pswd,,,,,DODISJOB.MAN/TL:45. will submit the job CRUNCH.P64 once, the job BATCH.CMD four times, and the job DODISJOB.MAN once. The first five jobs will have a time limit of 20(10) minutes, and the sixth job will have a time limit of 45(10) minutes. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 16 JOB CANCEL COMMANDS To remove a job from the batch queue, use the /CA switch in the form BAT /CA:n where "n" is the number of the job to be removed from the queue. The job number is octal by default; this is the radix that the job number is given in when the job was submitted. No filename need (or should) be specified. If the job is already running, the above command alone will not cancel the job. In this case you need to include the /AB subswitch, for example, BAT /CA:n/AB The default is /-AB, that is, the job will not be aborted if it is running. The two switches can be specified in either order, and it is illegal to use /AB alone without /CA, since /AB does not accept the job number as a switch value. If the job is running and a request is made to abort it in this way, the actual aborting of the job should occur within a period of about 30 seconds. The user will be logged off the virtual terminal, and the log file will be printed in the normal manner. Note that it may take BATMAN a while to completely terminate the job if it is running at a low priority or if system load is high. The /AB switch will have no effect if the job is not running; it will be ignored. To cancel several jobs, either several commands of the above form can be issued, or the following form can be used (note the separating commas) BAT /CA:n,/CA:m,/CA:p,... etc. If /AB is used on any switch in the above list, it also applies to all later switches, for example, BAT /CA:16/AB,/CA:21,/CA:37 is equivalent to BAT BAT>/CA:16/AB BAT>/CA:21/AB BAT>/CA:37/AB BAT>^Z while BAT /CA:16/AB,/CA:21/-AB,/CA:37 is equivalent to BAT BAT>/CA:16/AB BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 17 JOB CANCEL COMMANDS BAT>/CA:21 BAT>/CA:37 BAT>^Z A privileged user can cancel or abort any job in the system. A non-privileged user can only cancel or abort jobs that were submitted by him. If any errors are detected in the command line, such as an illegal job number, all commands following the illegal one in the same command line are ignored. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 18 JOB RELEASE COMMANDS Job Release Commands --- ------- -------- To remove a previously submitted batch job from hold status, use the /RL switch in the form BAT /RL:n where "n" is the job number. The default radix for the job number is octal; to specify decimal (which should not normally be necessary), append a decimal point. Note that this command only deletes the hold status; the job is inserted into the queue of jobs that are eligible to run according to its time limit and they may still be a delay in execution while all jobs of a shorter time limit are executed. If there are no other jobs in the queue that are eligible to run, or the just-released job has a shorter time limit than any other job in the queue, then the job will be the next one started. If a batch stream is available to run the job, then the just-released job should begin executing within 20 seconds and typically 10 seconds. Several jobs can be released from hold in one command line: BAT /RL:n,/RL:m,/RL:p A privileged user can delete the hold status of any batch job in the system. A non-privileged user can delete the hold status of only those jobs submitted by him. If an error is detected in the command line, such as an illegal job number, all remaining release commands on that command line (if any) are ignored. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 19 QUEUE LISTING COMMANDS Queue Listing Commands ----- ------- -------- The contents of the batch queue can be listed by issuing the command BAT /LI The format of the output produced is described below. The listing switch, which cannot be negated, takes two subswitches, /FU and /AL, both of which can be negated. The /FU switch provides a fuller listing, and can be used on its own, that is, BAT /LI/FU and BAT /FU are equivalent, while BAT /LI/-FU and BAT /LI are equivalent. The /AL switch is described below. If there are no jobs in the queue (either executing or waiting for execution), BAT displays the message BAT -- QUEUE IS EMPTY otherwise the queue listing is preceded by the text JOBS IN QUEUE: n. where "n" is the decimal number of jobs in the queue, including those job(s) that are executing. If the commannd then displays the line QUEUE IS IN RUNDOWN then the queue has been put into the "rundown state" by an operator, that is, the currently executing jobs will be allowed to finish, but no further jobs will be started. This is used, for example, when the system is being shut down for maintenance. A message may also appear indicating that no new jobs are being accepted. In this case, you will not be able to submit any jobs into the queue, but all those currently waiting will be allowed to execute. Following the initial message(s), there is a line typed out for each job of the form BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 20 QUEUE LISTING COMMANDS 4. 41 [33,37] DM0:[33,37]BATJOB.CMD;0 The first number typed out is the (decimal) queue member number. This number gives the position within the queue for starting eligibility. A zero will appear in this field for any jobs that are currently executing, and futhermore these jobs will appear at the head of the listing. Jobs that may be in hold are not immediately eligible for execution, and so appear at the end of the listing. Thus a hold job may move several places up the queue when its hold condition expires, depending on its time limit. Jobs that are in hold are not displayed in order of their time limit, but rather in the order that they were submitted. Internal reordering of hold jobs in the queue occurs when the hold condition expires. The second number displayed is the (octal) job number assigned to the job when it was submitted. This is the number that *must* be used to alter the status of any job in the queue, if necessary. The third field displayed is the User Identification Code (UIC) that will be used to log the user on to the virtual terminal when the job is run. The password that is associated with this UIC is never displayed by the listing commands. The logon UIC will usually, but not always, be the same as the directory in which the job description file is to be found. The fourth field is the complete file specification for the job description file. If the version number appears as zero (as in the example above), then the latest version of the file as the disk exists when the job is started will be the one used to run the job. If the version number is non-zero, then either an explicit version number was given when the job was submitted, or the /EV switch was used. In this case, this version of the job description file will be used to run the job. If the version number displayed is zero and you have more than one version of the job description file, then you can find out which one is running by issuing the command PIP filespec/TR where "filespec" is the file specification of the job description file with a wild card (*) specified in the version number field. PIP will issue a file open error message for the file that is currently open by the batch system to run the job. If the /FU switch was used, all the above information appears, but several fields are appended to the end of the line. The extra information that appears is dependent on the current state of the job, and may be spread over more than one line, depending on the line width of the terminal. If the job is executing, then the additional text is similar to T=n.M (USED m.mM) VTn: BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 21 QUEUE LISTING COMMANDS The text "VTn:" indicates which batch stream the job is running in ("n" is the unit number of the virtual terminal), and the remaining text gives the original time limit of the job in minutes and the amount of CPU time used by the job so far, in minutes rounded down. If the job is not running, this additional field is of the form T=n.M H=n.nnH EXPR where T=n.M gives the job's time limit in minutes, as specified when the job was submitted, H=n.nnH gives the wall clock time in hours to one-hundredth of an hour that will elapse before the hold condition expires, and EXPR indicates that the job is in the express class. If either of the last two fields do not apply (the job may not be express or it may not be in hold), then they do not appear. For jobs not in execution, the parameter list appears in the form: PM=(parm1,parm2,parm3,parm4) This field does not appear if no parameters were passed to the job when it was submitted. The line limit and count appears in the form: LINES=n. LINES=(n./m.) Here "n" is the decimal line limit given to the job when it was submitted, and "m" is the number of lines of output already done. Of course, the first form appears for jobs that are waiting for execution, and the second form appears for jobs that are executing. The following points should be borne in mind when listing the batch queue: (i) At a non-privileged terminal, the listing produced will only include those jobs submitted by the user who is issuing the listing command. The initial message that gives the number of jobs in the queue is always, however, the total number of jobs in the queue, and may be the only output produced if the user does not have any jobs in the queue. A non-privileged user may display the whole queue by using the subswitch /AL, for example, BAT /FU/AL, or BAT /LI/AL. (ii) At a privileged terminal, the listing produced will include all the jobs in the queue. If a privileged user wishes to display only jobs submitted by him, then the /-AL subswitch can be used (for example /LI/-AL or /FU/-AL) to display only jobs submitted by the user. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 22 QUEUE LISTING COMMANDS (iii) If you wish to find out the job numbers of jobs that you have in the queue, use /LI. To check further the status of jobs in the queue, use /FU. (iv) The output from a listing command can be cancelled any time after the initial message by typing CTRL/O. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 23 PROGRAM IDENTIFICATION COMMAND Program Identification Command ------- -------------- ------- The /ID switch, used on its own as a single command, provides the version number of the BAT processor currently in use. The output provided is of the form BAT -- BATCH VERSION V2.47 When new features are added to the system, this version number will be incremented. Users can use this command to find out if new features have been implemented. All new features and the associated version number of the processor will be described in user notices. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 24 BATCH TEXT MESSAGES Batch Text Messages ----- ---- -------- This section contains a list of the informational messages that are produced by BAT and generally accompany the successful execution of a command. Error messages follow in the next section. Each message is of the form BAT -- message text The following is a list of the possible strings that may appear in the "message text" field. Most are self explanatory, but short descriptions of their meanings are included. (1) JOB n REMOVED FROM HOLD Job number "n" (octal) was successfully removed from hold status by means of the /RL switch and has been entered into the relevant job queue. It is now eligible for execution. (2) JOB n MARKED FOR ABORT Job number "n" (octal) has been marked for abort by means of the command /CA:n/AB. The job will actually be aborted by BATMAN within about 15 seconds of the issuance of this message (but see the comments on this under the description of the cancel command). (3) JOB n ACCEPTED This message accompanies the successful submission of a job, and informs the user of the job number that has been assigned to the job by the batch system. (4) QUEUE IS EMPTY A listing command was issued, but there were no jobs in the queue, either executing or waiting for execution. (5) QUEUE IS IN RUNDOWN or NO NEW JOBS WILL BE ACCEPTED The first message indicates that the system may be shutting down for maintenance. Currently executing jobs will be allowed to finish. New jobs will be accepted, but none will be started until the rundown condition is cleared by an operator. The second message indicates that no new jobs will be accepted by the system, but that all jobs in the queue will be allowed to run, including those that are currently waiting. (6) JOB n CANCELLED Job number "n" (octal) has been deleted from the batch queue by means of the /CA:n command. The batch system will have no further knowledge of the existence of this job. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 25 BATCH TEXT MESSAGES (1) ** BATCH -- ABORTED BY REQUEST ** BATMAN inserts this message in your log file when you have requested the aborting of your job using /CA:n/AB. The actual program abort message will contain the text "ABORTED BY BATCH SYSTEM", rather than the usual "ABORTED BY DIRECTIVE OR MCR". If the latter text does appear, then the ABO command from a privileged terminal was responsible for the aborting of your program. (2) ** BATCH -- TIME LIMIT EXCEEDED ** No prizes for guessing what this means. (3) ** BATCH -- SPAWN ERROR ** This message indicates that an error condition caused a failure when BATMAN tried to execute a command on behalf of the user. Usually this message will be the only output produced, and indicated a logon failure that the job had no control over. Try submitting the job again if you get this message. It will not appear under normal circumstances. (4) ** BATCH -- OUTPUT LIMIT EXCEEDED ** The job wrote more output lines to the log file than the /LN switch (or the default) allowed. The line count is increased to 30,000 when this happens so that the job can exit in a tidy fashion without the automatic logoff sequence being output-limited. Note that these messages may appear more than once, depending on how long it takes BATMAN to abort the job. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 26 BATCH ERROR MESSAGES Batch Error Messages ----- ----- -------- This section contains a list of the error messages that may be produced by BAT, together with a description of their possible cause. Each message is preceded by the text BAT -- If the erroneous command was obtained by BAT from within an indirect command file, then certain of the messages, notably those pertaining to an illegal command line format, are also accompanied by a message giving the command line, or portion of the command line, that is in error. The possible error messages are: (1) COMMAND INPUT ERROR: CODE n This message indicates that BAT encountered an error when trying to get a new command line. If the code "n" is zero or unity, then the error is probably connected with an illegal indirect command file specification, such as extra text beyond a valid command. If the error code is negative, it is related to the file system. An explanation of the meaning of the error code can be found by looking in the list of standard FCS error codes found in the back of the I/O Operations Manual, Appendix I, or the FORTRAN 4-PLUS User's Guide, Appendix C. (2) CAN'T OPEN COMMAND FILE: FCS n An error was detected when BAT tried to open an indirect command file. The meaning of the error code (which will be a negative decimal number) can be found in the list of FCS error codes. The values that will probably be encountered most often are -26. (command file does not exist) and -38. (file is locked due to improper closure). Check that you have correctly spelt the name of the command file. (3) MAXIMUM NESTING DEPTH EXCEEDED An indirect command file specifier was detected within a command file. BAT does not allow command file nesting of this sort. The solution to this is to rewrite the command file. If this would be inconvenient on several occasions, make it known: the maximum allowable nesting depth of BAT is easily changed, at the expense of about 400 words of core. (4) COMMAND FILE SPECIFICATION ERROR The file specification given for an indirect command file did not conform to the standard RSX-11M format given at the beginning of this document. Check that all the fields have been entered correctly, and retype the command line. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 27 BATCH ERROR MESSAGES (5) COMMAND SYNTAX ERROR The format of the entered command did not conform to those allowed by BAT. An example of this sort of error is when a digit 8 is used in a switch value where an octal value was expected (a decimal point may be missing). This sort of error is usually obvious on examination of the command line. (6) INVALID JOB NUMBER Either a job number was missing from a switch which requires a job number to be specified, or a zero or negative value was given. (7) CANCEL SWITCH MISSING The /AB switch was used on its own without /CA. This is illegal since there is no way to specify a job number with /AB. (8) QUEUE IS FULL The job that the user is trying to submit cannot be accepted at the moment because the batch system has reached the limit on the number of jobs that can be in the queue at any one time. Try submitting the job later. If the job in question was created using the /IM switch, the newly created job file remains on the disk; it is not deleted. The maximum allowable job queue size can be changed by a system command while the system is running, so if it is important that you have your job in the queue, please enquire in the computer room. (9) INVALID TIME LIMIT Either the /TL switch was used without a switch value, or the value given was zero or negative. Specifying a time limit greater than the allowed maximum also causes this message to be displayed. (10) BAD PASSWORD The password specified (either by /PA or by the input typed in response to the ENTER PASSWORD: prompt) was illegal in some way. Check your password and re-enter the command line. (11) COMMAND IS AMBIGUOUS This message results either when commands from more than one class (see earlier) are mixed on the command line, or the /HF and /HU switches were both used to try to submit the same job. Enter the command line again in the proper format. (12) INVALID HOLD SPECIFICATION For the /HF switch, this message means that either a zero or negative value (other than -1 to -7) was specified. For the /HU BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 28 BATCH ERROR MESSAGES switch, this message means that the specified time of day doesn't exist on the 24 hour clock, for example, /HU:25:30 or /HU:16:-1. (13) PRIVILEGED COMMAND This message means that a non-privileged user tried to submit an express job. Only privileged users can submit express jobs. This message will also appear if a non-privileged user tries to issue one of the batch system queue maintenance commands (not documented in this manual). (14) NODES EXHAUSTED This message means that BAT could not obtain a necessary memory packet from the dynamic storage region (pool) because there was insufficient space available. This is probably a system overload condition, so you are advised not to issue any more commands of any sort for a while until the overload has eased. Don't be surprised if the system crashes shortly after getting this message! Under normal circumstances this situation should not occur. (15) BAD DIRECTORY STRING This message indicates an internal failure in BAT, and should never occur. If you get this message, please make it known! (16) This error message number reserved for possible future use. (17) ONLY A BATCH JOB CAN DEFAULT THE PASSWORD You tried to default the password on a job submission by using /PA:*. This is meaningful only from within a batch job, and cannot be used from a normal interactive terminal. (18) CAN'T OPEN JOB DESCRIPTION FILE: FCS n The job description file specified for the submission of a job was corrupted in some way, or it did not exist. The detailed nature of the error can be found by consulting a list of FCS error codes. The most frequently obtained code will be -26., which means that the specified file did not exist. (19) IMMEDIATE MODE ILLEGAL WITHIN A BATCH JOB You attempted to put BAT into immediate mode from within a batch job by using the /IM switch. This is illegal. This message only occurs during batch jobs. (20) I/O ERROR - FILE DELETED: FCS n While compiling a job description file in immediate mode, BAT detected a file-system related error. The FCS error code gives the BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 29 BATCH ERROR MESSAGES specific cause of the error. If you decided to cancel an immediate mode job by typing CTRL/Z in response to the * prompt, then this message indicates that the procedure has been cancelled. The FCS error code in this case will be -10 (end of file). If this is not the case, retry the function. Please enquire in the computer room if the problem persists. (21) JOB n IS RUNNING You issued a /RL:n,/TU:n or a /CA:n command (without the /AB subswitch) for a job that was already executing. These functions are not meaningful for jobs that are executing. If you really want to abort an executing job, try the command again and specify /AB. (22) JOB n NOT IN QUEUE You issued a /RL:n command, /TU:n command, or either form of the /CA:n command and specified a job number that did not match any of the jobs in the queue. Check the job number again, possibly by listing the queue with /LI. If you are sure that you have the job number right, but the job does not appear in the queue, then it has already finished running. (23) JOB n IS NOT IN HOLD You tried to release a job from hold by using /RL:n, and the job was not in hold, although it was found in the job queue. (24) PRIVILEGE VIOLATION This message indicates that a non-privileged user tried to cancel, abort or remove from hold a job that he did not submit. A non-privileged user can only alter the status of jobs in this way if he is the submitting user, that is, he is logged on to the same account that was used to submit the job. (25) This error message withdrwan. (26) WARNING - /NO SWITCH WILL BE IGNORED You attempted to submit a job and specified the /NO switch without specifying the /KE switch. You can only prevent spooling of the log file if it is written into your own directory. The /NO switch is ignored and job submission continues. If you really intended the /NO function, cancel the job and resubmit it, specifying /KE also. (27) UNABLE TO CONSTRUCT PARAMETER LIST This message will only appear if you specified a parameter list by means of the /PM switch when submitting a job. It means that BAT was unable to get enough dynamic memory to construct a parameter list, and is probably due to a system overload. BAT will BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 30 BATCH ERROR MESSAGES not submit the job in this instance. You can try the command again later. If the message persists, it is not only fatal to your job submission, but to the healthy running of the whole system! (28) CAN'T ACCEPT JOB - SYSTEM CLOSING DOWN The batch system is not accepting any more jobs for the time being. Any jobs already in the queue will be allowed to run. Note that this is a different condition to the 'rundown' condition described above. (29) INVALID LINE COUNT SPECIFICATION The /LN switch was used and the switch value given is either larger than the allowed maximum, is zero or negative or is not specified. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 31 THE STACK COMMAND The STACK Command --- ----- ------- The STACK command is used to enter the equivalent of terminal input in a batch job. It is recommended that all users of the batch system read any input that they might need from disk files. However, if this is not possible, or the required program modifications are not easy, the STACK command can be used. The operation of STACK (which can be abbreviated to STA) is best described by means of an example. Suppose that you had a simple FORTRAN program to add two integers together: ACCEPT *,I,J TYPE *,I+J STOP END If you were running this program at a normal interactive terminal, you might type: F77 PROG=PROG TKB PROG=PROG RUN PROG/TASK=PROG The program will then pause and wait for you to type in two integers. In a batch job, you obviously cannot type in the required input since there is no hardware terminal involved in the batch system. Instead, in *advance* of the program's requirements, the STACK command is used to inform the virtual terminal driver that here is a line of input that the batch job will want to read as the equivalent of terminal input some time in the future. The virtual terminal driver stores the specified data, and transfers it directly to the task when it issues a terminal read request. The job description file for running this simple job in the batch system would look something like F77 PROG=PROG TKB PROG=PROG STACK 18,57 RUN PROG/TASK=PROG When this program executes the ACCEPT statement, the numbers 18 and 57 will be transferred to the program as the variables I and J. Another example (although this is not recommended practice) is in the editing of a file in a batch job. Suppose that you wanted to change all occurrences of ABC to XYZ in the file TESTEDIT.FTN. A batch job description file to do this would look like STACK TESTEDIT.FTN STACK BLOCK OFF&T&PA/ABC/XYZ/ STACK EX EDI BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 32 THE STACK COMMAND or, alternatively, STACK TESTEDIT.FTN STACK BLOCK OFF STACK T STACK PA/ABC/XYZ/ STACK EX EDI These examples should serve to illustrate the use of the STACK command. If you should want to delete the stack at any point within your job (you might want to construct a new stack depending on conditions detected by the job), issue the command PIP NL:=TI:. This command deletes the entire stack. The same effect can be accomplished from within a FORTRAN program by the statements 999 READ(LUN,2000,END=1000) DUMMY 2000 FORMAT(A1) GO TO 999 1000 CONTINUE where the variable DUMMY is of type BYTE or LOGICAL*1, and the logical unit LUN has been assigned to TI:. At the end of every batch job, the stack is automatically purged by BATMAN, so it is not possible to enter data in a stack in one job and expect it to be there in a following job. If a program in a batch job asks for terminal input and the stack is empty, then the virtual terminal driver sends an end-of-file indication to the task, just as if the user typed CTRL/Z. Since typing CTRL/Z in edit mode is equivalent to typing EX, and is also used to terminate utilities, this can be used to advantage. For example, consider the following FORTRAN program 10 READ(5,*,END=20) I,J TYPE *,I+J GO TO 10 20 STOP END This program reads a set of integer pairs from the terminal, and types out their sum. It then loops and repeats the operation until CTRL/Z is typed. A job description file to run this job in the batch system might look like STACK 18,57 STACK 91,567 STACK 614,-91 RUN PROG In this case the looping of the program exhausts the job's stack, and the end-of-file indication returned by the virtual terminal driver causes a graceful job exit. This example BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 33 THE STACK COMMAND illustrates that there was no real need to stack the final EX command in the editing example above, since running off the end of the stack would accomplish the same result. You are encouraged to use this feature if possible. The following points should be borne in mind when using the STACK command: (i) Only one line can be stacked with a single STACK command. Also, because the command is directed to the system via the Monitor Console Routine (MCR), the length of the total command line is limited to 80 characters. Any characters that exist on the command line beyond this are ignored, although they will appear in the job's log file up to a maximum of 132 characters. At least one character must be present in every STACK command line. Hence it is not currently possible to STACK a blank line. (ii) Since MCR edits out any redundant tabs and spaces, all tabs will be converted to a space and all occurences of multiple spaces together will be compressed to a single space. (iii) A limit must be imposed on the size of any job's stack in order to avoid a possible condition where a program looping on a STACK command could destroy the system. This limit is currently set at 132 characters, and so it is guaranteed that a single STACK command will never cause a stack overflow. If you should want to read in more data that the maximum stack size will allow, you should read in this data via a disk file. The maximum stack size can be changed if it proves awkward to users. (iv) The STACK command is obviously only legal within a batch job. (v) Any combination of printable characters is allowed as the parameter to a STACK command. (vi) Any input that a program desires to read from the stack should be read on a unit which is assigned to TI:. (vii) If an error condition is detected by the STACK command (see below), a fatal error exit status of 4 is returned. You can detect this and take action accordingly by means of a construction similar to STACK I WANT TO STACK THIS LINE .IF EQ 4 .EXIT The STACK command can produce four error messages: (1) COMMAND INPUT ERROR This message means that either STACK was started by a RUN command (RUN ...STA or RUN $STACK), in which case there is no BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 34 THE STACK COMMAND command line to transfer to the stack, or the user attempted to stack a blank line. (2) ILLEGAL CONTEXT This message is produced when the STACK command is used at a normal interactive terminal. This context is illegal, since a stack is maintained by the virtual terminal driver only for batch jobs. (3) INSUFFICIENT STACK LEFT FOR THIS REQUEST This message is produced whenever a STACK command would cause the stack to exceed its maximum allowable size if the data were to be accepted. The command, and any other STACK commands that may follow in the same job, is not accepted. (4) MEMORY ALLOCATION FAILURE This message should not normally appear, but it indicates a system pool overload condition such that enough memory could not be obtained for the length of data specified to link into the job's stack list. Allocation failures of this sort are usually followed by system hangs. The STACK command will not be accepted in this case. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 35 WRITING JOB DESCRIPTION FILES Writing Job Description Files ------- --- ----------- ----- A job description file is essentially an indirect command file. The indirect file processor (...AT.) is described in the MCR Operations Manual, and all the facilities described there can be used in the batch system. This section contains a few examples of how job description files can be constructed. A batch job proceeds in a similar way to a normal terminal session; login (HELLO) and logout (BYE) are performed automatically by the batch system, and any commands that you might normally issue in between are what go into the job description file. You should take care, however, to ensure that any command sequences you write will work in the batch system, since there is no way of seeing the output from the job until it has finished. A command file can be given a test run on a normal terminal before submission to batch by issuing a command of the form @filespec/TR where "filespec" is the file specification of the job description file and the /TR switch implies that the command file execution should be traced, that is, commands specific to the indirect file processor will be typed out as they are executed. When testing your command files at a terminal, you may need to skip certain command sequences that would normally only execute in the batch system, for example, STACK commands. A system program, VT, is provided for this purpose. VT exits with a exit status of zero if it is run on a normal interactive terminal, and with an exit status of (n+5) if run in the batch system, where n is the unit number of the virtual terminal. The VT program is stored in UFD [10,25] and is used with a RUN command. For example, you could use it as follows: ; FIND OUT IF WE ARE IN A BATCH JOB .SETT BATCH RUN [10,25]VT .IF < 5 .SETF BATCH ; SYMBOL "BATCH" WILL BE TRUE IF WE ARE RUNNING IN BATCH, ; AND FALSE OTHERWISE. .IFT BATCH STACK FIRST STACKED LINE .IFT BATCH STACK SECOND STACKED LINE The task VT can be used in this manner at any point in your job description files to make them completely independent of terminal type (real or virtual). The simplest form of job is the running of a program which has already been compiled and task-built. The job description file in this case would consist of a single RUN command: RUN PROGRAM BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 36 WRITING JOB DESCRIPTION FILES STACK commands can be added to this job to supply any terminal input that the program may require. If you wanted to run a number of different programs in this way, you could either write a job description file for each one, or you can use the parameter substitution facility provided by the /PM switch of BAT. For example, suppose a job is designed to read in two numbers from the terminal and produce some output. You could write a job description file (MYJOB.CMD) containing the commands STACK 18,46 RUN PROGRAM and submit the job with a command such as BAT MYJOB/PA:pswd or you could write the job description file using parameter substitution: .ENABLE SUBSTITUTION STACK 'P1','P2' .SETS NAME "PROGRAM" .IF P3 NE "" .SETS NAME "'P3'" RUN 'P3' The same job could then be submitted as BAT MYJOB/PA:pswd/PM:18:46 In this example, wherever the string 'P1' appears, the first parameter supplied by the /PM switch is substituted (providing the job starts with .ENABLE SUBSTITUTION), and similarly for 'P2','P3' etc. Any parameters which the job uses which were not supplied by /PM (like the third parameter in this example) default to zero length strings. More flexibility is given to the above job by using the third parameter. If the job was submitted with the command BAT MYJOB/PA:pswd/PM:67:-5:NEXTPROG then the commands actually executed would be STACK 67,-5 RUN NEXTPROG Thus the method of parameter substitution can be used to submit a variety of different jobs which all use the same job description file, but which accomplish different functions. More complex jobs can be written using the .IF directives available to the indirect file processor to make decisions within the job based on parameters supplied at submission time. The above job is a simple example of this. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 37 WRITING JOB DESCRIPTION FILES Jobs can easily be written to perform a sequence of steps and then resubmit themselves to perform further calculation. This can be used when the maximum allowable job time is not enough to complete a calculation, or if you want to use a short time limit to get better turnround. Suppose you have a program which can perform 500 iterations on a set of data within a certain time, but you want to run the calculation to 5000 iterations. The program could be something like OPEN(UNIT=1,NAME='DATA.DAT',TYPE='OLD',FORM= 1 'FORMATTED') C READ IN ITERATION COUNT AND VARIABLES READ(1,*) N,X1,X2,X3,X4 . . perform 500, iterations . . N=N+500 REWIND 1 WRITE(1,*) N,X1,X2,X3,X4 CLOSE(UNIT=1) IF(N.GE.4999)STOP CALL EXST(66) END This program reads in the data it needs from a disk file, performs 500 iterations on it, writes the new count back to the data file and closes it. If there are still less than 5000 iterations done, the program exits with an exit status of 66, otherwise it will simply STOP (the same as exiting with an exit status of 1) if the maximum number of iterations has been performed. You could then submit the job with a normal BAT command. The job description file might look like RUN PROGRAM .IF EQ 66. BAT MYJOB/PA:*/TL:120. The special variable is given the value of the exit status of the last program run. In this example, when the exit status is 66., the batch job resubmits itself with a time limit of 2 hours. This submission/resubmission cycle will continue until 5000 iterations have been performed, when no further jobs will be submitted. The subroutine EXST used in this example is described on page 6-63 of the RSX-11M V3.2 Executive Reference Manual. Don't forget to close your files before you use it! There are some points to bear in mind when passing parameters to a batch job that has been given the restartable attribute, as mentioned above. When a job is first started, BATMAN passes the parameters to the job and then deletes the parameter list. If the system crashes while the job is running, a copy of all of physical memory as it existed at the time of the crash is written to a BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 38 WRITING JOB DESCRIPTION FILES magnetic tape. The batch system has a Crash Queue Restore program (CQR) which reads this magnetic tape and restores the job queues to the point that they were when the crash occurred. Because BATMAN will have deleted the parameter list, a restartable job will be restarted without any parameters, since BATMAN will not know what they were. Consequently, the execution of the job will be uncertain, and will probably fail. You can check for job restart by including commands like .IF P1 EQ "" .STOP at the head of your job description file. This command will cause the job to terminate if the first parameter is null, which would be the case if a job that originally had parameters was restarted. You could also use this command to ensure that a job won't do anything disastrous at its initial startup if you forgot to specify parameters for a job that was expecting some. Normally, a job should not be marked as restartable if parameters are passed to it, but the batch system will accept jobs of this sort so that you can take alternative action in the job description file if a restart was made, for example, file cleanup. When a job is restarted by the system after a crash, it will have its have its original time limit. There are some other points to note in connection with system crashes: (i) The batch job may have done some more output between the time that BATMAN last saved the log file and when the crash occurred. You should not assume that all that appears in the log file is all that the job did. Any output that may be missing from the log file as a result of the crash will always be less than one page in length. (ii) If you wanted to keep the log file (/KE) and also wanted it spooled (/NO was absent), the log file will not be spooled when the system is restored after a crash. (iii) Log files written to the system directory will be spooled at system restart, but with a different flag page. Don't try to submit jobs which attempt to do maximum processing by simply running off the end of their time limit. If BATMAN detects this and aborts your job while it is writing data to a file, you lose the file! BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 39 THE TAPE COMMAND The TAPE Command --- ---- ------- The TAPE command is issued in a batch job to request an operator to load a magnetic tape for use by the job. It is used in place of the usual Allocate/Mount sequence that is used at a normal interactive terminal. The TAPE command is an indirect command file, and its input (the command line) is read from the job's stack. To use the command, place the sequence STACK command-line @LB:[10,25]TAPE in the job description file at a point before the tape is required. The "command-line" is a line of input giving the tape parameters to TAPE.CMD, and you should ensure that there is nothing else on the job's stack when you issue the above sequence. The command line format is: label/keyword1/keyword2... where "label" is the one to six character label of the tape to be loaded, and "keyword1","keyword2" etc are keywords used to specify other tape parameters. The label parameter is always required, except in the case where a scratch tape is to be loaded (see the /SCRATCH keyword below). The valid keywords that may be used are (all of the specified characters are required): /DENS=1600 The tape is to be processed at a density of 1600 bpi. If this keyword is not specified, a density of 800 bpi is used by default. This keyword is always legal in a TAPE command. /NEW This keyword specifies that the tape "label" does not exist already and that a blank tape is to be loaded. The new tape will be initialised and mounted ready for use, and at the end of the job the tape will be placed in the permanent tape library. Thus it is not necessary to initialise a tape interactively in readiness for a batch job if this keyword is used. The label specified in the command will be used to initialise and mount the tape. /NEW is not a default condition. BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 40 THE TAPE COMMAND /SCRATCH This keyword specifies that a scratch tape is required for the duration of the batch job only. A tape label need not be specified in this case since it is irrelevant. If a label is used, it will be the one used to initialise the tape, else the default label "SCRATC" will be used. Data written on scratch tapes is lost at the end of a batch job. This keyword is not a default, and also it may not be specified in the same command as /NEW. /READONLY If this keyword is specified, the tape will be mounted without a write-enable ring, so that write access to the tape is not allowed. By default a tape will be mounted *with* a write-enable ring. For obvious reasons, it is illegal to use this keyword with either /NEW or /SCRATCH. /NOMOUNT This keyword specifies that the tape is not to be mounted. It is normally used for privileged system jobs, such as those that perform a disk backup. This keyword cannot be used with /NEW or /SCRATCH. It is also legal to specify a tape label longer than 6 characters when this keyword is used, since the label is then only a means to identify the tape reel. The algorithm used by TAPE when requesting a tape is as follows: (i) If there are any errors in the command line, such as invalid keywords or a label missing where one is required, the batch job will be terminated immediately with an appropriate error message. Any commands following TAPE in the job description file will not be executed. (ii) TAPE tries to allocate the tape drive for private use by the batch job. If the drive was already allocated to the job by means of an earlier TAPE command, this will be immediately successful, as will also be the case if the drive was available. If the tape drive was allocated to another terminal or batch job at the time, TAPE will cause the batch job to wait until the current user of the drive has deallocated it; the batch job will then proceed as normal. If the drive does not become available within 60 minutes, TAPE will cause the job to terminate. (iii) Once the drive has become the private device of the batch job, TAPE will issue a command to the operator's console for the tape to be loaded. The batch job will then wait for the drive to become online to the system. It can only be in this state when a tape is loaded. Note that is is also possible for the wait limit BATCH SYSTEM USER'S GUIDE MARCH 1980 PAGE 41 THE TAPE COMMAND to expire at this point; you might have run the job in the middle of the night when there was nobody around to load the tape. (iv) When the tape is loaded, the tape will be initialised if /NEW or /SCRATCH was specified and mounted (if /NOMOUNT was absent). TAPE then exits and passes control back to the batch job, which can then go ahead and use the tape. If there are any errors at this point, for example, the wrong tape was loaded or a hardware error occurs, the batch job is terminated. The tape drive is automatically deallocated and dismounted at the end of the job. If you wish to issue more than one TAPE command within each job, you should dismount the tape (using DMO) before the second TAPE command. APPENDIX A INDEX INDEX PAGE A-2 /AB . . . . . . . . . . . . . 16 /AL . . . . . . . . . . . . . 19 /CA . . . . . . . . . . . . . 16 /DE . . . . . . . . . . . . . 10 /EV . . . . . . . . . . . . . 9 /EX . . . . . . . . . . . . . 11 /FU . . . . . . . . . . . . . 19 /HF . . . . . . . . . . . . . 10 /HU . . . . . . . . . . . . . 10 /ID . . . . . . . . . . . . . 23 /IM . . . . . . . . . . . . . 12 /KE . . . . . . . . . . . . . 12 /LI . . . . . . . . . . . . . 19 /LN . . . . . . . . . . . . . 8 /NO . . . . . . . . . . . . . 12 /PA . . . . . . . . . . . . . 9 /PM . . . . . . . . . . . . . 11 /RL . . . . . . . . . . . . . 18 /RS . . . . . . . . . . . . . 11 /TL . . . . . . . . . . . . . 8 /TR . . . . . . . . . . . . . 10 Abort Job Switch . . . . . . . 16 BATCH Command . . . . . . . . 3, 5 Batch Error Messages . . . . . 26 Batch System Id . . . . . . . 23 Batch Text Messages . . . . . 24 Cancel Job Switch . . . . . . 16 Error Messages . . . . . . . . 26 Explicit Version Switch . . . 9 Express Job Switch . . . . . . 11 Hold For Time Switch . . . . . 10 Hold Until Time Switch . . . . 10 Immediate Mode Switch . . . . 12 Indirect Files . . . . . . . . 6 Job Cancel Commands . . . . . 16 Job Description Files . . . . 35 Job Parameters . . . . . . . . 14 Job Release Commands . . . . . 18 Job Submission . . . . . . . . 8 Line Limit Switch . . . . . . 8 List All Jobs Switch . . . . . 19 List Full Queue Switch . . . . 19 List Queue Switch . . . . . . 19 Log File Delete Switch . . . . 10 INDEX PAGE A-3 Log File List Switch . . . . . 12 Log File Retention Switch . . 12 Multiple Job Submission . . . 13 Parameter Switch . . . . . . . 11 Password Switch . . . . . . . 9 Queue Listing Commands . . . . 19 Release Job Switch . . . . . . 18 Restartable Job Switch . . . . 11 STACK Command . . . . . . . . 2, 4, 31 STACK Error Messages . . . . . 33 TAPE Command . . . . . . . . . 4, 39 Terminal Input . . . . . . . . 31 Text Messages . . . . . . . . 24 Time Limit Switch . . . . . . 8 Trace Job Switch . . . . . . . 10 Virtual Terminal . . . . . . . 2, 3 VT . . . . . . . . . . . . . . 35