ON ERROR defines the type of branch used and the service routine line when an error occurs. The branch type can be a GOTO, a GOSUB, a CALL, or a RECOVER. If no error handler is defined, the error message is displayed and the program is paused. For example:
ON ERROR GOSUB 200
ON ERROR GOTO Fix_it
ON ERROR RECOVER 1510
ON ERROR CALL Handler
An ON ERROR statement is canceled by an OFF ERROR statement and is not disabled by the DISABLE statement.
The destination of a GOTO or GOSUB must be a program line in the present context. If the error occurs while execution is in a different context, the ON ERROR definition is ignored, the error message is displayed, and the program is PAUSEd.
The destination of a RECOVER must also be a program line in the present context. However, if the error occurs while execution is in a different context, then SUBEXITs are automatically performed until control is returned to the proper context.
The destination of a CALL must be a SUB context that defines no parameters. When the error occurs, a CALL is performed to the SUB context.
An ON ERROR can interrupt any event service routine since it has a priority of 17 which is higher than any event branch. It cannot be set or changed with the SYSTEM PRIORITY statement. If another ERROR occurs while the system is at this priority (a "double fault"), then the program is PAUSEd even though an ON ERROR definition is in effect.
Error Handler Routines
If the branch type is a CALL or GOSUB, then when the error is serviced the system priority is changed to 17.
When a SUBEXIT or RETURN is executed, the system priority is restored to its value before the error was serviced. If the branch type is a GOTO, the system priority is not changed. If the branch type is a RECOVER, the automatic SUBEXITs restore the system priority to the value it was when the defining context invoked another context.
If an error occurs in the service routine:
ON ERROR GOSUB or CALL reports the error and pauses the program.
ON ERROR GOTO or RECOVER can cause an infinite loop between the error line and the error routine.
The error handler routine can use the value of the error number (ERRN) and the error line number (ERRLN). If no error has occurred since start-up or SCRATCH A, then a zero is returned. The ERRL function returns a one if ERRLN is equal to the specified line and a zero otherwise. The specified line must be in the current context. The ERRL function is not keyboard executable. The ERRN, ERRLN, and ERRL functions may be used in IF statements to direct program flow in error handler routines.
ERRM$ returns the line number (ERRLN), the error number (ERRN), and the associated error message string. An empty string is returned if no error has been generated since start-up, LOAD, GET, SCRATCH, or CLEAR ERROR.
TRANSFER errors are not reported until the associated I/O path variable is accessed. In this case ERRLN is the number of the program line referencing the I/O path, not the TRANSFER statement. Also, ERRN is not updated.
CLEAR ERROR resets ERRL, ERRLN, ERRM$, and ERRN to their default start-up values.
If an error handler ends (by RETURN, SUBEND, or SUBEXIT) without correcting the cause of the error, the error line will re-execute and occur again causing an infinite loop until it is corrected. Subroutines ending with ERROR RETURN and subprograms ending with ERROR SUBEXIT do not re-execute the line in error because they return to the line following the line that caused the error. For example:
100 ON ERROR GOSUB 500
. . .
. . .
500 INPUT "Value too Large. Try again: ",N
510 ERROR RETURN
CAUSE ERROR allows you to test your error handlers by generating the error specified as if it actually occurred and the normal error functions: ERRL, ERRLN, ERRM$, and ERRN are updated.
