This chapter describes how to create and use indirect command files. An indirect command file is composed of a series of operating system commands that are executed by RT--11 in sequential order.

Each indirect command file typically performs a single general task, such as configuring the operating system, starting or stopping a job, configuring a virtual memory (VM) device, or performing backup operations. Also, indirect command files can be used to perform operations that involve much computer processing but do not require your supervision or intervention. For example, multiple assemblies, compilations, and data transfer (copy) operations are ideal operations for indirect command files.

You can include in the indirect command file a command to run a second indirect command file, which is called (nesting) indirect command files. You can also create indirect command files that contain only commands to run any number of other indirect command files.

This chapter contains the following information: (unnumbered) Comparison between indirect command file functionality and IND (indirect control file processor) and BATCH Creating indirect command files Running indirect command files Nesting indirect command files

Use the on-line index utility, INDEX, and see the on-line help utility, HELP, for more information on topics described in this chapter. (Comparison with IND and BATCH\indir_comp_sec)

RT--11 supports three methods for creating and running indirect files: (unnumbered) Indirect command files, described in this chapter and illustrated in various chapters in this manual IND indirect control files, described in the (sug_book) BATCH files, described in the (sum_book)

Each method has its own characteristics. While IND and BATCH provide the most functionality, they are more complex to use and are not discussed in this chapter. Indirect command files are simple to use, but contain the following limitations: (unnumbered) Process commands in only sequential order. Do not support direct user intervention once started. Do not support conditional (if, else) logic.

Those limitations do not exist with IND and BATCH. If you require indirect files without those limitations, you should also investigate IND and BATCH and in that order. The distributed file that runs automatic installation, STARTA.COM, and the system generation procedure file, SYSGEN.COM, are examples of IND files. RT--11 distributes no BATCH files. (Creating an Indirect Command File\ind_creat_sec)

Use the editor to create an indirect file as a text file. You can call the file by any file name you wish, but you should give it a file type of .COM, since this file type is the default used by the monitor to locate the file. You should choose a name for the file that suggests the task that the file performs. You should preface the commands in a file with a comment header containing the name, creation and edit dates, and a short description of the file's function.

You enter commands into the indirect file as you would on the terminal. You do not include the monitor prompt. You can include comment lines in the file, so long as each comment line begins with an exclamation mark (!).

The following rules and information apply to creating indirect command files: (unnumbered) You can use any valid command (DCL, CCL, or CSI) syntax. You can also include commands you have defined, using UCL or UCF, so long as the command is complete and requires no additional information from the terminal. You should use the /NOQUERY option (or CSI equivalent) with commands that would otherwise require a response from the terminal.

Some commands, such as BOOT, do not accept a /NOQUERY option. You cannot, for example, execute a BOOT command from within an indirect command file if the foreground is loaded. RT--11 will always request confirmation of the operation. You should, therefore, unload any foreground jobs before running the indirect command file or abort any jobs and unload the foreground from within the file before issuing the BOOT command. You can factor commands, and all rules applying to factoring commands apply. You can use wildcards, but you should be careful that wildcard operations execute in the manner you expect each time you run the indirect command file.

Remember that the system configuration and the contents of storage volumes will change, and a wildcard operation might produce unexpected results. Commands in indirect command files should be as specific as possible, so that the operation performed by the command is completely predictable. You should specify multiple operations of the same type on the same command line, allowing for command syntax restrictions. For example, the following command line: COPY DU0:(RT11XM.SYS,SWAP.SYS,DUX.SYS,VMX.SYS,MSX.SYS) VM:

executes faster than: COPY DU0:(RT11XM.SYS) VM: COPY DU0:(SWAP.SYS) VM: COPY DU0:(DUX.SYS) VM: COPY DU0:(VMX.SYS) VM: COPY DU0:(MSX.SYS) VM:

because the first command line calls the PIP utility only once to perform the COPY operation, where the second set of commands must call PIP five times. Each command in an indirect command file is placed in a memory buffer before it is executed. The indirect command file aborts if the memory buffer overflows. You can flush the buffer by including a CTRL/C periodically after a number of commands. In practice, overflowing the buffer is not a problem unless you run a large indirect command file, nest files together, or run an indirect command file that in turn calls multiple files. You can include a command to run another indirect command file. Nesting indirect command files is described, with examples, in (indir_nest_sec). You can include a command to run an IND control file. However, such a command must be the last command in the indirect command file because you cannot return to an indirect command file from an IND control file. Also, you cannot call an indirect command file from within that IND control file.

As an exercise, use the following procedure to create an example indirect command file, EXAMP.COM. The example file does the following: (unnumbered) Creates a logical disk on your default data (DK) volume named EXAMP.DSK, containing 50 blocks. Verifies that EXAMP.DSK resides on DK. Displays the status of logical disk units. Mounts EXAMP.DSK on logical disk unit LD7. Initializes LD7. Displays a directory of LD7. Dismounts LD7. Removes the file protection for EXAMP.DSK. Deletes EXAMP.DSK. Verifies that EXAMP.DSK is deleted from DK.

Note that the file has no lasting effect on the system or your storage disk; it cleans up after itself. The procedure to create the file is: (numbered) Create EXAMP.COM: (.)(EDIT/CREATE EXAMP.COM (RET)) Enter the following: (!EXAMP.COM, created dd-mmm-yy, edited dd-mmm-yy) (! Example indirect command file for Intro to RT) (CREATE EXAMP.DSK/ALL:50.) (DIRECTORY EXAMP.DSK) (SHOW SUBSET) (MOUNT LD7: EXAMP.DSK) (INITIALIZE/NOQUERY LD7:) (DIRECTORY LD7:) (DISMOUNT LD7:) (UNPROTECT EXAMP.DSK) (DELETE EXAMP.DSK) (DIRECTORY EXAMP.DSK) Close the file by exiting from the editor.

This manual contains many examples of indirect command files. If you have worked through the chapters in the (mon_part), and particularly (sysjob_ind_sec) and (sysjob_nind_sec), you have created indirect command files to start, abort, and unload a system job. If you have worked through the exercises in (int_vm_chap), you have created indirect command files to create and use a virtual memory (VM) system device. Such applications are excellent uses for indirect command files. (Running an Indirect Command File\indir_run_sec)

You can run an indirect command file by preceding the file name (the file type .COM is assumed unless you indicate otherwise) with an at sign (@) and pressing (RETURN). The following example command line runs the indirect command file INDFIL.COM: .@INDFIL (RET)

That syntax is valid so long as the keyboard monitor (KMON) remains set to interpret the (@filename) construction as being an indirect command file. That syntax becomes invalid if KMON is set using SET KMON IND to interpret the (@filename) construction as an indirect (control) file. If you precede the at sign with a dollar sign (($@filename)), KMON always interprets the file as an indirect command file. Therefore, the following construction is always valid for running indirect command files and is the recommended construction: .$@INDFIL (RET)

As an exercise, now run the indirect command file, EXAMP.COM: (.)($@EXAMP (RET))

Execution starts immediately, and the system processes commands in consecutive order. By default, each command is echoed on the terminal as it is processed. Terminal echo can be suppressed by including the SET TT QUIET command at the beginning of the file.

You can temporarily suspend the file execution by pressing (HOLD SCREEN) or by pressing (CTRL/S), and resume execution by pressing (HOLD SCREEN) again or pressing (CTRL/Q). You can abort the file execution by pressing (CTRL/C) twice.

If an error occurs during command processing, the system prints a message on the terminal and stops execution of the file from the point at which the error occurred. Therefore, it is important that you check your indirect command file for errors before you start it if you are going to run it and leave the area.

You can change the level of error that aborts an indirect command file, using the SET ERROR command. By default, an ERROR level error aborts a file. The level of error that causes an abort can be reduced to WARNING. If you are creating and testing an indirect command file and want to ensure that the file executes completely as expected, you can change the error level to WARNING: .SET ERROR WARNING (RET)

Once you have run the file and verified it executes as expected, you can, at your option, change the abort error level back to ERROR. (Nesting Indirect Command Files\indir_nest_sec)

As mentioned previously, indirect command files typically perform a single task. They are a modular tool. You can combine the tasks performed by an indirect command file by nesting one indirect command file within another. You enter the command in the file just as you would from the keyboard, using the ($@filename) construction.

RT--11 lets you nest indirect command files to three levels; you can run an indirect command file that calls another file, which in turn calls another file. Attempting to nest files beyond the third level returns a fatal level error message and aborts the third level nested file.

Assume that you have created an indirect command file, PRINT.COM, and you wish to run PRINT.COM after EXAMP.COM. You nest PRINT.COM in EXAMP.COM as follows: !EXAMP.COM, created dd-mmm-yy, edited dd-mmm-yy ! Contains nested PRINT.COM ! Example indirect command file for Intro to RT CREATE EXAMP.DSK/ALL:50. DIRECTORY EXAMP.DSK SHOW SUBSET MOUNT LD7: EXAMP.DSK INITIALIZE/NOQUERY LD7: DIRECTORY LD7: DISMOUNT LD7: UNPROTECT EXAMP.DSK DELETE EXAMP.DSK DIRECTORY EXAMP.DSK $@PRINT

There can be times when such an indirect command file is useful. You have, however, made EXAMP.COM unusable unless you also want to run PRINT.COM.

In keeping with the concept of modular indirect command files, it may be more useful to create a third file that calls both EXAMP.COM and PRINT.COM, thus keeping those files modular and usable by themselves. For example, you could create an indirect command file named WHOLE.COM and enter the following: !WHOLE.COM, created dd-mmm-yy, edited dd-mmm-yy $@EXAMP $@PRINT

Running WHOLE.COM would then run EXAMP.COM, followed by PRINT.COM.

Finally, as described in (defcom_ind_sec), you can define a command that calls an indirect command file. That file can contain commands and can call other indirect command files.