HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

Performs a specified action when a command or program executed within a command procedure encounters an error condition or is interrupted by Ctrl/Y. The specified actions are performed only if the command interpreter is enabled for error checking or Ctrl/Y interrupts (the default conditions). Use the ON command only in a command procedure.

Format

ON condition THEN [$] command

Parameters

condition

Specifies either the severity level of an error or a Ctrl/Y interrupt. Specify one of the following keywords, which may be abbreviated to one or more characters:

WARNING	Return status of warning occurs ($SEVERITY equals 0).
ERROR	Return status of error occurs ($SEVERITY equals 2).
SEVERE_ERROR	Return status of error occurs ($SEVERITY equals 4).
CONTROL_Y	Ctrl/Y character occurs on SYS$INPUT.

The default error condition is ON ERROR THEN EXIT.

command

Specifies the DCL command line to be executed. Optionally, you can precede the command line with a dollar sign ($).

If you specified an error condition as the condition parameter, the action is taken when errors equal to or greater than the specified level of error occur.

Description

During the execution of a command procedure, the command interpreter checks the condition code returned from each command or program that executes. With the ON command, you can establish a course of action for the command interpreter to take based on the result of the check.

The system places condition codes in the global symbol $STATUS. The severity of the condition code is represented in the first 3 low-order bits of $STATUS. This severity level is also represented by the global symbol $SEVERITY. See the description of the EXIT command for information on severity level values.

If an ON command action specifies the severity level of an error, the command interpreter executes the ON command action for errors at the specified severity level or greater. For example, the following command causes a procedure to exit on warnings, errors, or severe errors:

$ ON WARNING THEN EXIT

The default action is as follows:

$ ON ERROR THEN EXIT

That is, the command interpreter continues when a warning occurs, and executes an EXIT command when an error or severe error occurs. An ON command action that specifies a severity level is executed only once; after the ON command action is taken, the default ON action is reset. There is an exception to the default ON action. If you use the CALL, GOSUB, or GOTO command and specify a label that does not exist in the current command procedure, the procedure issues a warning message and exits.

The action specified by an ON command applies only within the command procedure in which the command is executed; therefore, if you execute an ON command in a procedure that calls another procedure, the ON command action does not apply to the nested procedure. An ON command executed at any command procedure level does not affect the error condition handling of procedures at any other level.

To disable error checking with the ON command, use the SET NOON command. You can enable error checking with the SET ON command, or by entering another ON command.

The ON command also provides a way to define an action routine for a Ctrl/Y interrupt that occurs during execution of a command procedure. The default (Ctrl/Y) action is to prompt for command input at the Ctrl/Y command level. The Ctrl/Y command level is a special command level where you can enter DCL commands. If you enter a command that is executed within the command interpreter, you can resume execution of the procedure with the CONTINUE command. (For a list of commands that are executed within the command interpreter, see the OpenVMS User's Manual.)

If you enter any other DCL command, the command interpreter returns to command level 0 and executes the image invoked by the command. If you interrupt the command procedure while it is executing an image that contains an exit handler, the exit handler is allowed to execute before the new command (image) is executed. (However, if you enter the STOP command after you interrupt a command procedure by pressing Ctrl/Y, exit handlers declared by the interrupted image are not executed.)

You can use the ON command to change the default action for a Ctrl/Y interrupt. If you change the default Ctrl/Y action, the execution of a Ctrl/Y interrupt does not automatically reset the default Ctrl/Y action. A Ctrl/Y action remains in effect until one of the following occurs:

• The procedure terminates (as a result of an EXIT or STOP command, or as a result of a default error condition handling action).
• Another ON CONTROL_Y command is executed.
• The procedure executes the SET NOCONTROL=Y command.

A Ctrl/Y action can be specified for each active command level; the Ctrl/Y action specified for the currently executing command level overrides actions specified for previous levels.

Note The ON CONTROL_Y and SET NOCONTROL=Y commands are intended for special applications. HP does not recommend, in general, that you disable Ctrl/Y interrupts. For example, if a procedure that disables Ctrl/Y interrupts begins to loop uncontrollably, you cannot gain control to stop the procedure from your terminal.

Examples

$ ON SEVERE_ERROR THEN CONTINUE
      

A command procedure that contains this statement continues to execute normally when a warning or error occurs during execution. When a severe error occurs, the ON statement signals the procedure to execute the next statement anyway. Once the statement has been executed as a result of the severe error condition, the default action (ON ERROR THEN EXIT) is reinstated.

$ ON ERROR THEN GOTO BYPASS
$ RUN A
$ RUN B
   .
   .
   .
$ EXIT
$ BYPASS:
$      RUN C

      

If either program A or program B returns a status code with a severity level of error or severe error, control is transferred to the statement labeled BYPASS and program C is run.

$ ON WARNING THEN EXIT
   .
   .
   .
$ SET NOON
$ RUN [SSTEST]LIBRA
$ SET ON
   .
   .
   .

      

The ON command requests that the procedure exit when any warning, error, or severe error occurs. Later, the SET NOON command disables error checking before executing the RUN command. Regardless of any status code returned by the program LIBRA.EXE, the procedure continues. The next command, SET ON, reenables error checking and reestablishes the most recent ON condition.

$ ON CONTROL_Y THEN GOTO CTRL_EXIT
   .
   .
   .
$ CTRL_EXIT:
$ CLOSE INFILE
$ CLOSE OUTFILE
$ EXIT

      

The ON command specifies action to be taken when Ctrl/Y is pressed during the execution of this procedure: the GOTO command transfers control to the line labeled CTRL_EXIT. At CTRL_EXIT, the procedure performs cleanup operations (in this example, closing files and exiting).