HP OpenVMS Systems Documentation
OpenVMS User's Manual
The following restrictions apply when executing command procedures:
13.6.4 Executing Command Procedures Interactively
To execute a command procedure interactively, enter an execute procedure command (@) followed by the file specification of the command procedure.
For example, this command executes the procedure SETD.COM in the [MAINT.PROCEDURES] directory on the WORKDISK: disk:
You can define a symbol name to represent long command lines. You can then use the symbol to execute a command procedure.
To use a symbol to execute the command procedure shown in the previous example, include this line in your login command procedure:
Then, to execute the procedure SETD.COM, enter the symbol name as you would any command:
By default, when you execute a command procedure interactively, the operating system displays output at your terminal. However, you can redirect output to a file by using the /OUTPUT qualifier to the execute command.
When you redirect command procedure output to a file, the procedure sends any error messages to the terminal and to the file that is receiving the output.
This command writes the output from SETD.COM to the file RESULTS.TXT instead of to the terminal:
Always place the /OUTPUT qualifier immediately after the command
procedure name, with no intervening spaces. Otherwise, DCL interprets
the qualifier as a parameter to be passed to the procedure.
If you use command procedures that require lengthy processing time (for example, compiling or assembling large programs), submitting these procedures as batch jobs will allow you to continue using your terminal interactively.
To execute a command procedure in batch mode, submit your command procedure to a batch queue (a list of batch jobs waiting to execute) by entering the DCL command SUBMIT. When you submit a job, it is directed to the default batch queue SYS$BATCH where it is added to the end of the queue of jobs waiting to be executed. When the jobs preceding yours are completed, your job is executed. On OpenVMS systems, the number of batch jobs that can execute simultaneously is specified when the batch queue is created by the system manager.
The following example shows how to execute the command procedure named JOB1.COM. The SUBMIT command uses the default file type .COM; therefore you do not have to enter the file type if your command procedure has the file type .COM:
188.8.131.52 Remote Batch Jobs
If your system is part of a network, you can submit a command procedure
as a batch job on a remote node. Within a command procedure, you can
use DCL commands to open and close files on remote notes and to read
and write records in those files, using the same commands and
qualifiers for local files.
By default, if the system fails before the job is finished, batch jobs are reexecuted beginning with the first line. However, you can use the following symbols in your command procedure to specify a different restarting point:
The following procedure describes how to use the $RESTART and the BATCH$RESTART symbols:
The following command procedure extracts a number of modules from a library, concatenates those modules, and then sorts the resulting file:
If this command procedure aborts, it reexecutes from the beginning of
the file, from the statement labeled CONCATENATE_LIBRARIES, or from the
statement labeled SORT_FILE, depending on the value of BATCH$RESTART.
If you were extracting a number of separate modules, you could make
each extraction a separate section.
The following sections describe how to execute command procedures on
disk and tape volumes.
When you submit a command procedure with the SUBMIT command, you cannot
access files on allocated devices. You can, however, execute a command
procedure that is located on a private disk that is mounted with the
You can execute command procedures that reside on tape volumes if:
If either of these conditions occur, you can execute the command procedure by doing the following:
13.7 Exiting and Interrupting Command Procedures
A command level is an input stream for the DCL level
interpreter. When you enter commands at your terminal, you are entering
commands at command level 0. A simple interactive command procedure
(such as CLEANUP.COM) executes at command level 1. When the procedure
terminates and the DCL prompt reappears on your screen, you are back at
command level 0.
There are three ways to exit from a command procedure while it is executing:
If an exit is caused by the end of the procedure or an EXIT command, control returns to the next higher command level. You can return a status value to the next higher command level by specifying the value as the parameter of the EXIT command.
If you invoke the command procedure called SUB at the DCL level and SUB calls the subroutine SUB1, the following occurs:
If an exit is caused by a STOP command, control always returns to DCL command level, regardless of the command level in which the STOP command executes.
If you execute the STOP command in a batch job, the batch job terminates.
You can interrupt a command procedure by pressing Ctrl/Y and then using the EXIT or STOP command to terminate the procedure. In this case, both the EXIT and STOP command return you to the DCL level.
In the following example, the TESTALL procedure is interrupted by pressing Ctrl/Y. The EXIT command terminates processing of the procedure and returns you to DCL level. (Note that you can also enter the STOP command after you interrupt the procedure.)
13.7.2 Exit-Handling Routines
When you interrupt a command procedure, if the command (or image) that
you interrupt declares any exit-handling routines, the EXIT command
gives these routines control. However, the STOP command does not
execute these routines.
By default, the command interpreter executes an EXIT command when a command results in an error or severe error. This causes the procedure to exit to the previous command level. For other severity levels (success, warning, and informational), the command procedure continues.
There is one exception to the way that the command interpreter handles errors. If you reference a label in a command procedure and the label does not exist (for example, if you include the command GOTO ERR1 and ERR1 is not used as a label in the procedure), the GOTO command issues a warning and the command procedure exits.
When the system issues an EXIT command as part of an error-handling routine, it passes the value of $STATUS back to the previous command level, with one change. The command interpreter sets the high-order digit of $STATUS to 1 so that the command interpreter does not redisplay the message associated with the status value.
In the following example, the command procedure TEST.COM contains an error in the output file specification:
When you execute this procedure, the CREATE command returns an error in $STATUS and displays the corresponding message. The command interpreter then examines the value of $STATUS, determines that an error occurred, issues an EXIT command, and returns the value of $STATUS. When the procedure exits, the error message is not redisplayed because the CREATE command already displayed the message once. At DCL command level, you can see that $STATUS contains the error message but the high-order digit has been set to 1. For example:
13.8.1 Default Error Actions
The following table describes the default action taken when an error condition or a Ctrl/Y interruption occurs while a command procedure is executing. You can override these default actions with the ON, SET [NO]ON, and SET [NO]CONTROL=Y commands.
13.9 Other Methods of Error Handling
The following sections describe other methods of handling errors.
The ON command specifies an action to be performed if an error of a certain severity or greater severity occurs. If such an error occurs, the system takes the following actions:
An ON command action is executed only once. Therefore, after a command procedure performs the action specified in an ON command, the default error action is reset.
The action specified by an ON command applies only within the command level in which the command is executed. Therefore, if you execute an ON command in a procedure that invokes another procedure, the ON command action does not apply to the nested procedure.
The format of the ON command is as follows:
Where "condition" is one of the following keywords:
If an ON command action is established for a specific severity level, the command interpreter performs the specified action when errors of the same or worse severity occur. When less severe errors occur, the command interpreter continues processing the file.
This command can be used to override the default error handling so that a procedure exits when warnings, errors, or severe errors occur:
If your command procedure includes this command, the command procedure executes normally until an error or severe error occurs:
If such an error occurs, then the procedure resumes executing at ERR1. $STATUS and $SEVERITY are set to success and the default error action is reset. If a second error occurs before another ON or SET NOON command is executed, the procedure exits to the previous command level. The action specified by an ON command applies only within the command level in which the command is executed. Therefore, if you execute an ON command in a procedure that invokes another procedure, the ON command action does not apply to the nested procedure.
Figure 13-1 illustrates ON command actions.
Figure 13-1 ON Command Actions
You can prevent the command interpreter from checking the status returned from commands by using the SET NOON command in your command procedure, which sets the ON command to NO status. When you use the SET NOON command, the command interpreter continues to place values in $STATUS and $SEVERITY but does not perform any error checking. You can restore error checking with the SET ON command or with an ON command.
When a procedure disables error checking, it can explicitly check the value of $STATUS following the execution of a command or program.
In the following example, the SET NOON command preceding the RUN commands ensures that the command procedure continues if either of the programs TESTA or TESTB return an error condition. The SET ON command restores the default error checking by the command interpreter.
In the following example, the first IF command checks whether $STATUS has a true value (that is, if it is an odd numeric value). If so, the FORTRAN command was successful and the LINK command executes. After the LINK command executes, $STATUS is tested again. If $STATUS is odd, the RUN command executes; otherwise, the RUN command does not execute. The SET ON command restores the current ON condition action; that is, whatever condition was in effect before the SET NOON command was executed:
The SET ON or SET NOON command applies only at the current command
level; that is, the command level at which the command is executed. If
you use the SET NOON command in a command procedure that calls another
command procedure, the default error-checking mechanism will be in
effect within the nested procedure. Note that SET NOON has no meaning
when entered interactively at DCL level.
By default, when you press Ctrl/Y while a command procedure is executing, the command interpreter prompts for command input at a special command level called Ctrl/Y command level. From Ctrl/Y command level, you can enter DCL commands that are executed within the command interpreter and then resume execution of the command procedure with the CONTINUE command. In addition, you can stop the procedure by entering a DCL command that forces the command procedure to stop executing.
This section describes methods of overriding the way that command
procedures process Ctrl/Y interruptions by using the ON command.
You can interrupt a command procedure that is executing interactively by pressing Ctrl/Y. When you press Ctrl/Y, the command interpreter establishes a new command level, called the Ctrl/Y level, and prompts for command input. When the interruption occurs depends on the command or program that is executing:
At the Ctrl/Y level, the command interpreter stores the status of all previously established command levels so that it can restore the correct status after any Ctrl/Y interrupt.
After you interrupt a procedure, you can do the following: