16.3 Using the ON ERROR Statements
BASIC supports ON ERROR statements as an alternative
to WHEN blocks primarily for compatibility with existing
programs. WHEN ERROR blocks are similar to declara-
tive statements in that they do not depend on run-time flow
of control. The ON ERROR statements, however, affect er-
ror handling only if the statements execute at run time. For
example, if a GOTO statement precedes an ON ERROR
statement, the ON ERROR statement will not have any effect
because it does not execute.
WHEN ERROR blocks let you handle errors that occur in
a specific range of statements. ON ERROR statements let
you specify a general error handler that is in effect until
you specify another ON ERROR statement or until you pass
control to the BASIC error handler.
The ON ERROR statements are documented in the DEC
BASIC and VAX BASIC for OpenVMS Systems Reference
Manual . This section briefly describes the main features of
the ON ERROR statements.
The ON ERROR statements can be used to transfer con-
trol to a labeled block of error handling code. If you have
executed an ON ERROR statement and an error occurs,
the ON ERROR statement immediately transfers control to
the label or line number that starts the error handling code.
Otherwise, the ON ERROR statement specifies the branch to
be taken in the event of an error.
There are three forms of the ON ERROR statement:
The ON ERROR GOTO 0 statement reverts control to
BASIC default error handling in one of two ways:
The ON ERROR GOTO target statement reverts control
to the target when subsequent errors occur that are not
handled by WHEN block handlers.
.
ON ERROR GO BACK
The ON ERROR GO BACK statement transfers control
to the calling program's error handler if an error oc-
curs in the subprogram or DEF function. If you use ON
ERROR GO BACK in a PROGRAM unit (outside of a
DEF function) and no other outer protected region ex-
ists, it is equivalent to ON ERROR GOTO 0 and BASIC
default error handling is in effect. With ON ERROR GO
BACK, if an error occurs in the execution of a function
or subprogram, the error is passed to either the error
handler of the surrounding program module (in the case
of a DEF function definition) or to the error handler of
the calling program (in the case of a separately compiled
subprogram).
An error handler in the DEF function does not perma-
nently override an error handler in the main program.
BASIC saves the error handler in the main program
when you transfer into a DEF, and restores it when you
return.
The ON ERROR GOTO statement is usually placed before
any other executable statements. The following example
clears end-of-file errors and passes all other errors back to
the BASIC default error handling procedures:
5 ON ERROR GOTO Error_handler
.
.
.
Error_handler:
!Trap end of file on device
IF ERR = 11
THEN
RESUME 1000
ELSE
ON ERROR GO BACK
END IF
The ON ERROR GOTO statement remains in effect after
your program successfully handles an error. When the sys-
tem signals another error, control once again transfers to the
specified error handler.
Every ON ERROR error handler must end with one of the
following statements:
.
RESUME [ target ]
.
ON ERROR GOTO 0
.
ON ERROR GO BACK
If none of these statements is present, the BASIC error han-
dler aborts your program with the fatal error ``Error trap
needs RESUME'' as soon as an END, END SUB, END DEF,
END FUNCTION, END PROGRAM, or END PICTURE
statement is encountered. The RESUME statement, like
the RETRY and CONTINUE statements, clears the error
condition.
You can resume execution at any line number or label that is
in the same module as the RESUME statement, unless that
line or target is inside a DEF function, a WHEN ERROR
protected region, or a handler. In general, RESUME with-
out a target transfers control to the beginning of the program
block where the error occurred.
.
If you resume execution at a multistatement line, execu-
tion begins at the first statement after the line number or
label-not necessarily at the statement that generated the
error.
.
If an entire loop block is associated with a single line
number or label and an error occurs within the loop,
RESUME with no target transfers control to the state-
ment immediately after the FOR, WHILE, or UNTIL
statement, not to the line number or label.
For more information about the RESUME statement, see
the DEC BASIC and VAX BASIC for OpenVMS Systems
Reference Manual .
Digital does not recommend using both ON ERROR state-
ments and WHEN ERROR constructs in the same program.
However, when this is the case, the order of handler priorities
is as follows:
1. Control passes to the handler associated with the inner-
most WHEN ERROR block.
2. If protected regions are nested, the pending error is han-
dled by the handler associated with the next outer WHEN
ERROR block.
3. When no outer protected regions can handle the er-
ror, and if an ON ERROR statement is in effect, control
transfers to the target of the next outer ON ERROR
statement (if one is present).
4. If no outer handler is available or can handle the er-
ror, the error is passed to BASIC default error handling.
Default error handling is equivalent to ON ERROR
GOTO 0 for main procedures, and ON ERROR GO
BACK for SUBs, FUNCTIONs, and DEFs.
For information about specific run-time errors, see Appendix
B.