HP OpenVMS DCL Dictionary
EXIT
Terminates processing of a command procedure or subroutine and returns
control to the calling command level---either an invoking command
procedure or interactive DCL. The EXIT command also terminates an image
normally after a user enters Ctrl/Y (executing another image has the
same effect).
Format
EXIT [status-code]
Parameter
status-code
Defines a numeric value for the reserved global symbol $STATUS. You can
specify the status-code parameter as an integer or an expression
equivalent to an integer value. The value can be tested by the next
outer command level. The low-order 3 bits of the value determine the
value of the global symbol $SEVERITY.
If you specify a status code, DCL interprets the code as a condition
code. Note that even numeric values produce warning, error, and fatal
error messages, and that odd numeric values produce either no message
or a success or informational message.
If you do not specify a status code, the current value of $STATUS is
saved. When control returns to the outer command level, $STATUS
contains the status of the most recently executed command or program.
Description
The EXIT and STOP commands both provide a way to terminate the
execution of a procedure. The EXIT command terminates execution of the
current command procedure and returns control to the calling command
level. If you enter the EXIT command from a noninteractive process
(such as a batch job), at command level 0, then the process terminates.
The STOP command returns control to command level 0, regardless of the
current command level. If you execute the STOP command from a command
procedure or from a noninteractive process (such as a batch job), the
process terminates.
When a DCL command, user program, or command procedure completes
execution, the command interpreter saves the condition code value in
the global symbol $STATUS. If an EXIT command does not explicitly set a
value for $STATUS, the command interpreter uses the current value of
$STATUS to determine the error status.
The low-order 3 bits of the status value contained in $STATUS represent
the severity of the condition. The reserved global symbol $SEVERITY
contains this portion of the condition code. Severity values range from
0 to 4, as follows:
| Value |
Severity |
|
0
|
Warning
|
|
1
|
Success
|
|
2
|
Error
|
|
3
|
Information
|
|
4
|
Severe (fatal) error
|
Note that the success and information codes have odd numeric values,
and that warning and error codes have even numeric values.
When any command procedure exits and returns control to another level,
the command interpreter tests the current value of $STATUS. If $STATUS
contains an even numeric value and if its high-order bit is 0, the
command interpreter displays the system message associated with that
status code, if one exists. (If no message exists, the message NOMSG
will be displayed.) If the high-order bit is 1, the message is not
displayed.
When a command procedure exits following a warning or error condition
that has already been displayed by a DCL command, the command
interpreter sets the high-order bit of $STATUS to 1, leaving the
remainder of the value intact. This ensures that error messages are not
displayed by both the command that caused the error, and by the command
procedure.
The EXIT command, when used after you interrupt an image with Ctrl/Y,
causes a normal termination of the image that is currently executing.
If the image declared any exit-handling routines, they are given
control. This is in contrast to the STOP command, which does not
execute exit-handling routines. For this reason, the EXIT command is
generally preferable to the STOP command.
Examples
The EXIT command in this example exits to the next higher command
level, giving $STATUS and $SEVERITY a value of 1.
| #2 |
$ ON WARNING THEN EXIT
$ FORTRAN 'P1'
$ LINK 'P1'
$ RUN 'P1'
|
The EXIT command in this example is used as the target of an ON
command; this statement ensures that the command procedure terminates
whenever any warnings or errors are issued by any command in the
procedure.
The procedure exits with the status value of the command or program
that caused the termination.
| #3 |
$ START:
$ IF (P1 .EQS. "TAPE") .OR. (P1 .EQS. "DISK") THEN GOTO 'P1'
$ INQUIRE P1 "Enter device (TAPE or DISK)"
$ GOTO START
$ TAPE: ! Process tape files
.
.
.
$ EXIT
$ DISK: ! Process disk files
.
.
.
$ EXIT
|
The command procedure in this example shows how to use the EXIT command
to terminate different command paths within the procedure. To execute
the procedure, you must enter either TAPE or DISK as a parameter. The
IF command uses a logical OR to test whether either of these strings
was entered. If the result is true, the GOTO command branches to the
corresponding label. If P1 was neither TAPE nor DISK, the INQUIRE
command prompts for a correct parameter.
The commands following each of the labels TAPE and DISK provide
different paths through the procedure. The EXIT command before the
label DISK ensures that the commands after the label DISK are executed
only if the procedure explicitly branches to DISK.
Note that the EXIT command at the end of the procedure is not required
because the end of the procedure causes an implicit EXIT command. Use
of the EXIT command, however, is recommended.
| #4 |
$ IF P1. EQS. "" THEN -
INQUIRE P1 "Enter filespec (null to exit)"
$ IF P1 .EQS. "" THEN EXIT
$ PRINT 'P1'/AFTER=20:00/COPIES=50/FORMS=6
|
The command procedure in this example tests whether a parameter was
passed to it; if the parameter was not passed, the procedure prompts
for the required parameter. Then it retests the parameter P1. If a null
string, indicated by a carriage return for a line with no data, is
entered, the procedure exits; otherwise, it executes the PRINT command
with the current value of P1 as the input parameter.
| #5 |
$ IF P1 .EQS. "" THEN INQUIRE P1 "Code"
$ CODE = %X'P1'
$ EXIT CODE
|
The command procedure in this example, E.COM, illustrates how to
determine the system message, if any, associated with a hexadecimal
system status code. The procedure requires a parameter and prompts if
none is entered. Then it prefixes the value with the radix operator %X
and assigns this string to the symbol CODE. Finally, it issues the EXIT
command with the hexadecimal value. The following example uses the
procedure E.COM:
$ @E 1C
%SYSTEM-F-EXQUOTA, exceeded quota
|
When the procedure exits, the value of $STATUS is %X1C, which equates
to the EXQUOTA message. Note that you can also use the F$MESSAGE
lexical function to determine the message that corresponds to a status
code.
| #6 |
$ RUN MYPROG
[Ctrl/Y]
$ EXIT
|
In this interactive example, the RUN command initiates execution of the
image MYPROG.EXE. Then pressing Ctrl/Y interrupts the execution. The
EXIT command that follows calls any exit handlers declared by the image
before terminating MYPROG.EXE.
| 
