The CRUN and DRUN commands allow TSS to take your interactive commands and responses from a file instead of from the terminal. This is done in such a way that the commands being used do not know that they are not using the terminal. While in command file mode, output to the terminal is collected. When command file mode ends, input and output are either printed on the terminal or placed in another file, just as if you had done it yourself.
To run a command file "while you wait", use
CRUN input-file[;output-file;option-1;option-2;...]
If you do not give an output file (e.g. CRUN input-file[;;options]), the "terminal log" is directed to the terminal. You may use CRUN only from command level.
To run a set of commands "detached" from the terminal, use
DRUN input-file;output-file[;option-1;option-2;...]
DRUN detaches the task from the terminal and may defer processing of the command file until the time and date specified in the options field. The input file may optionally contain line numbers. You MUST specify an output file. If you don't want it, give an output file name of "*null". If you specify a filename of "*id", DRUN will generate an output file whose name is the job number (nnnnD) of the DRUN. Thus you might type "drun drunfile;*id" or "drun drunfile;/cat/*id".
It is possible for a command file to have its output file and/or options specified on a line which begins with "##" and which is the first line of the file. Since the output file name is a positional parameter, it must be shown as null if it is not wanted. Here are two examples:
##otfile;restart;(file1) (output specified) ##;restart;(file1) (output null)
If an output file, substitutable argument, or option is supplied in both the first line of the file and in the command which invoked the file, the one in the first line is ignored.
By now you may have realized that command files are not going to be the simplest thing in the world to pick up. This explain file can really only give you a rough idea of what can be done. You might also have a look at the GCOS8 manual, but your best bet is to try things out by writing simple little examples to do what you want to do and go to the manual or the consultant when you run into difficulty.
Up to eight arguments may be supplied, each consisting of 1-12 characters. The characters permitted include: all alphanumerics, period, dash, colon, slash, dollar sign, number sign and asterisk. Blanks included in a character string are retained and all alphanumerics are forced to upper case.
If such an argument contains a question mark, the argument is typed to prompt the user, requesting him to enter the actual value of the argument.
If you need to preserve case or use characters which are not otherwise permitted, you may supply an argument of up to ten characters, enclosed in double quotation marks. An argument supplied in this manner may contain any ASCII characters and is substituted as it appears, e.g.
drun infile;otfile;("/cat/fil,r","(10,100)")
An argument consisting of one to six number signs ('#') is obtained by converting the lower half of the Switch Word to decimal, dropping higher order digits if necessary. Note that a command file is passed the Switch Word of the initiator.
Finally, there is a set of "special" arguments, as follows:
Arg Meaning Format --- ------- ------ #DATE current date yy/mm/dd #TIME current time hh.mmm #USERID logon userid 1-12 characters #ACCOUNT charge number 1-12 characters #CHANNEL channel number four digits #SNUMB latest snumb snumb
These special arguments are abbreviated by the first character of their name (#DATE is abbreviated as #D). The values are established at the time the command file starts to run.
file1 contains: mail to #1 m="hi there" s="" mail to #2 m="good bye" s=""
The session is initiated by the command
drun file1;file2;(fbaggins,name?)
The user will be prompted for the second argument, like so:
name? prabbit -- your response written like this
After the session, file2 will look like:
*mail to FBAGGINS m="hi there" s="" Message sent to fbaggins *mail to PRABBIT m="good bye" s="" Message sent to prabbit
mail to x1 m="hi there" s="" mail to x2 m="good bye" s=""
If given to a CRUN, these options are ignored.
If you have jobs scheduled to run at a later date/time, you can force them to be rescheduled to run as soon as possible by using the following form of the DRUN command:
DRUN #job-id-1;job-id-2;...;job-id-n (for specific jobs) DRUN #all (for all jobs)
To check on the status of your jobs, use DSTA (see "expl dsta"). To cancel a DRUN after submission use "DABT nnnnD" to cancel a specific job, or "DABT ALL" to kill all of your DRUNS. If the list of completed jobs given by DSTA becomes intolerably long, use "DABT REMO" to force deletion of completed jobs.
$*$USER=what is your account number?
$*$MARK now on line five
issues the message "now on line five" to the user's terminal when the line is encountered in the command file.
Two special names are defined to permit break and abort handling by a command file. Each time the break key is depressed during a CRUN, control passes to the label called "..BREAK", if it is defined. Similarly, the occurrence of any error which would result in abnormal termination of a DRUN or CRUN causes control to be passed to the line associated with a label called "..ABORT" if it is defined. When termination occurs after going to ..ABORT, either due to normal termination or due to another error, control goes to the ..ABORT line of the previous level of nesting or else the whole thing is terminated. For more on the abort codes, see the discussion of CMOD below.
As an example, a typical TSS session might look like:
*b bsrc >bgo
B 6
*go:bgo >/output
*acce af /output
*slis /output
*logo
Session charges as of 26/May/82 at 15:35:38:
Fixed charge $ 0.10
Connect time $ 8.67
Keyboard I/O $ 1.73
Disk I/O $ 4.25
Processor/Memory $ 14.38
_______
Total $ 29.13 + $3.74 = $32.87 (16.4%)
The command file to run this session might look like:
##outfile;(obj?) b bsrc >#1 go:#1 >/output acce af /output $*$SYST slis /output logo
The "##" on the first line of a command file signifies that the line is part of the command line. One needs only to say "drun input-file", since the output-file and options are specified on the first line of the input-file. Any declarations supplied on the actual command line override similar declarations on the "##" line. The argument in brackets is subtituted for "#1". Because there is a question mark after the argument, the user receives this as a prompt, and provides the file name from the terminal. For example,
*drun drunfile
obj? bgo
The $*$SYST line checks to see if the last output prompt was in fact the "*" prompt. If not (i.e. ACCESS types an error message, then asks "FUNCTION ?"), the session aborts.
If the session is quite short, it can be run without an input file. This is done by placing the commands, separated by a backslash or an ampersand, inside double quotes; for example,
crun "b bsrc >bgo&go:bgo >/output&slis /output"
When you type in a line whose first four characters do not match anything in a list of commands in the TSS executive, a subsystem called the command loader is called to extend the search.
If the first string ending in a blank contains a slash, like "/filename" or "/cat/filename", the command loader tries to access the indicated file. Otherwise it takes the first four characters or the first string less than four characters ending on a blank, and tries to access "CMDLIB/xxxx". If this fails, it tries for file "xxxx" under your userid, where "xxxx" is the string of four characters or less found by the procedure just mentioned.
If the command loader is succcessful in accessing a file, it then determines if the file is random or sequential. If random, it tries to start execution of the load module presumed to be on the file. If sequential, it will normally issue an error message. However, if the file is permanent and if it has a subsystem name of "CRUN", the command loader will pass the file to the CRUN command to run it as a command file. To place a subsystem name of CRUN on a file, use
access mf /filename,use/crun/
where "/filename" is the name of the file in question. Similarly, if a sequential file has the subsystem name "exec", it will be passed to the EXEC command (see "expl exec").
If you want to pass options and arguments to the command file, you use a command line that is the same as the equivalent CRUN command, but you omit the CRUN part and you do not have to specify permissions for the input file (read is the default). Thus you might type
/cmdfile;otfile;restart;(arg1,arg2)
Alternatively, if you only want to specify substitutable arguments, you can type the filename, then a space, then the arguments separated by commas or semi-colons, as in
/cmdfile arg1,arg2
This command permits all output accumulated since the beginning of the TSS session or since the last COUT to be directed to the user's terminal, or to a file if one is designated. For example,
COUT outfile
sends accumulated output to "outfile".
The CMOD and CPOS commands are not restricted to command files but they are intended for use in command files and provide some limited "programming" ability in the command file.
The CMOD command allows modification of the lower half (bits 18-35) of the program switch word (PSW). The form of the command is:
CMOD operation-1;operation-2;...;operation-n
Operation Meaning Restrictions n set bits 18-35 of PSW to n n<262144 +n add n to bits 18-35 of PSW n<262144 -n subtract n from bits 18-35 of PSW n<262144 Si set bit i 18 <= i < 36 Si-j set bits i through j 18 <= i < j < 36 Ri reset bit i 18 <= i < 36 Ri-j reset bits i through j 18 <= i < j < 36 Ni negate bit i 18 <= i < 36 Ni-j negate bits i through j 18 <= i < j < 36 D display bits 0-35 of PSW E place abort code in PSW bits 18-35
Possible error codes and their meanings are as follows (in decimal):
code meaning ---- ------- 1 command file nonexistent 2 command file I/O error 3 command file format error 4 excessive output generated 5 invalid use of DRL T.CFIO 6 user error #nnn detected by TSS 7 ppt start or line switch attempted 10 processor time limit exceeded 11 input line length too long 12 command file input exhausted 13 terminated by DABT while executing 14 error detected in <name> command processing 15 command level synchronization error 16 $*$function not permitted
Allows conditional execution of commands based on the contents of the user's program switch word. The form of the command is:
CPOS expression;operation
When the expression is true, the implied operation is performed.
Expression True When Restrictions
i bit i of the PSW is on 0 <= i < 36
LTn bits 18-35 of PSW < n n < 262144
LEn bits 18-35 of PSW <= n n < 262144
GTn bits 18-35 of PSW > n n < 262144
GEn bits 18-35 of PSW >= n n < 262144
EQn bits 18-35 of PSW = n n < 262144
NEn bits 18-35 of PSW are not = n n < 262144
Operators permitted in the expressions are + (or), * (and), - (exclusive or), and / (not). Although / normally takes only one operand, A/B is taken to mean A*/B, by convention. The expression is evaluated strictly from left to right and TRUE or FALSE is displayed.
The operation can be either a command or a branch to a command indicated by +n or n, meaning jump forward n lines, or -n meaning to go back n lines. When the forward spacing requested exceeds the number of lines in the command file, the session is terminated normally. As an example,
CPOS 18+GE5*LT10;+2
means "if bit 18 of the PSW is on or the magnitude of its lower half is greater than 5 and less than 10, then skip the command immediately following the CPOS".
When the expression is absent, the operation is always performed.
Both CMOD and CPOS request continuation of input when the last character on the line is a semi-colon. A null response to such a request means completion. When a CRUN or DRUN is not accompanied by the necessary parameters, the query "FILE NAMES?" is issued. The user must input the required information at this time. For example, a CRUN input file might look like:
##file2 CMOD 10;D CPOS LT8;wmi CPOS EQ10;+3 mail to japrat m="hi george" s="" slis b.out crun $*$user lsta j319t $*$MARK all done!
The session would be run as:
*/file1
FILE NAMES? infile;outfile;(fbaggins) all done!
In this case, infile is another command file and it is initiated by the processing of file1. "infile" looks like:
aft u=#1
After the command file processing, outfile looks like:
*aft u=fbaggins 3 Files sy** 2 r tn *cfq 60 r t *cfp 60 r t
And file2 looks like:
*CMOD 10;D SW=002000 000012 *CPOS LT8;wmi FALSE. *CPOS EQ10;+3 TRUE. *crun FILE NAMES? *lsta j319t
P# Snumb-A# Urgc Type Size Lal Userid Line Used Left Status 15 j319t-01 5 geload 16 154 fbaggins <j8> 7 42 exec *cout
Both DRUN and CRUN are processed by the same load module. They are handled the same, except that DRUN commands are placed in a queue first. If the command is a DRUN, the initial ## parameter lines are collected from the file, if present, to form a complete command line. DRUN requests TSS to create a queue file entry and place in it the job identifier, userid, start date, start time, processor time limit, input and output filenames and substitutable arguments. In addition to creating the new queue entry, DRUN also checks the queue file and tells TSS the job-id, userid and earliest start date/time of the next job to be initiated. If you didn't specify a start time or date, the job would normally be scheduled by TSS immediately. Note that such a DRUN might be forced to wait a bit, since this site permits only a few DRUNs to be active at any time.
When TSS is ready, it creates a UST (User status Table - everyone signed on has one) for the session, then invokes DRUN, with flags showing that it is to initiate a deferred session. DRUN retrieves the queue entry and begins preparation of the command file. At this point, processing is the same for both CRUN and DRUN. A random temp file called *CFP is created and the input file is copied into it, one line per hardware sector (64 words). Initial ## lines and $*$REM lines are thrown away. Argument collection, substitution and removal of DEL characters takes place at this time. An initial and final sector is generated on *CFP, bordering the sectors developed from the input file lines. The initial sector contains the userid of the session originator and is utilized by the logon subsystem. The final sector contains a COUT command accompanied by the output file name if given.
If the job is a DRUN, the queue entry is updated to show it is executing and TSS is again notified of the next candidate for execution. "Command file mode" is enabled and control passes to the LOGON subsystem, which signs on the deferred user.
In "command file mode", the TSS executive obtains each user response by reading the appropriate *CFP sector and directs all terminal output to *CFP starting at the sector after the generated COUT command. Normal termination occurs when the terminating COUT command is processed or if a BYE or LOGOFF or OFF command is given. If a file was given in the terminating COUT command, it is created if necessary and allocated. Note that only at this time will it be determined whether or not you have enough file space to hold the output; if you don't, it disappears forever. For obvious reasons, DRUN requires and creates a permanent file. With CRUN, if you use a quick access name (less than 8 characters, no '$', '/' or '"') the program will use conventions similar to those of FRED. If the EXCLUDE option was set, only the output segment of *CFP is sent to the terminal or output file. Otherwise, input and output are collated to produce the file; this is made possible by referencing the sector number of an input line in each output sector.
If the job is a DRUN, the queue entry is updated to show normal termination. Abnormal termination can occur for a variety of reasons, detected either by TSS or by DRUN/CRUN. Every attempt is made to produce as much of the output as possible and in all cases the reason code for the abort is saved in the queue entry for DSTS.
DRUNs and CRUNs may be nested to a maximum depth of four levels. The effect of encountering a CRUN during a DRUN or CRUN is to suspend processing until the new CRUN terminates. When an error occurs at one level, output for all levels is generated and the whole thing is terminated.
Each level of command file processing requires a file in the AFT, identified by the names *CFP through *CFT. NEWUSER processing preserves these files for the user, allowing a CRUN to change userids at will. Both userid and password must follow the NEWU command in the CRUN file.
A CRUN may normally terminate only at command level. If you try it under any other condition (such as in FRED), you will get the message "COMMAND FILE INPUT EXHAUSTED" and will be "blown" out of what you were doing. Naturally, the same conditions apply if you start the CRUN indirectly through the command loader. You can get around this problem by placing a $*$QUIT at the end of the command file, but if you do so and you want to get your output, make sure you put a COUT command just prior to the $*$QUIT.
Explain files exist for the commands DRUN, CRUN, CMOD, CPOS, and COUT. Bull describes command files in chapters six and seven of the TSS General Information Manual, order number DD22.
Copyright © 1996, Thinkage Ltd.