ON_ERROR Procedure
Determines the action taken when an error is detected inside a user-written procedure or function.
note | If both ON_ERROR and ON_ERROR_GOTO appear before the line in the code that creates the error condition, the ON_ERROR_GOTO takes precedence. |
Usage
ON_ERROR, n
Input Parameters
n—An integer that specifies the action to take. Valid values are:
0—Stop at the statement in the procedure that caused the error. (This is the default action.)1—Return all the way back to the main program level.2—Return to the caller of the program unit which established the ON_ERROR condition.3—Return to the program unit which established the ON_ERROR condition.Keywords
Continue—If specified and nonzero, program execution resumes at the statement specified by one of the following input parameters:
0—Continue in the procedure that caused the error.1—Return to the main program level $MAIN$ and continue.2—Return to the calling routine that established the ON_ERROR condition and continue.3—Return to the program unit that established the ON_ERROR condition and continue.Example
In this example, a procedure named PROC1 calls a procedure, PROC2, which conditionally calls either procedure PROC3 or PROC4. Procedure PROC3 contains an error. A call to PRINT from within PROC3 is intended, but a typographical error results in a nonexistent procedure, PAINT, being called. The ON_ERROR procedure, which is called from PROC2, is passed different input parameter values in this example to exhibit the action taken when the error in PROC3 is encountered.
The following is a listing of the procedures used in this example:
PRO PROC1
FOR i = 1, 4 DO BEGIN
PROC2, i
ENDFOR
END
PRO PROC2, j
; Invoke the ON_ERROR procedure at this point.
ON_ERROR, 0
IF (j MOD 2) EQ 0 THEN BEGIN
PROC3, j
ENDIF ELSE BEGIN
PROC4, j
ENDELSE
END
PRO PROC3, k
; The call to a nonexistent procedure, PAINT, occurs here.
PAINT, k, ' is even.'
END
PRO PROC4, m
PRINT, m, ' is odd.'
END
Note that ON_ERROR has the input parameter 0 in PROC2. If the procedures are placed in the file errex.pro in your working directory, all of them can be compiled with the following command:
.RUN errex
Error Condition 0
Next, run the PROC1 procedure and examine the results:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Execution halted at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
Examine which procedure PV-WAVE returned to by looking at the current nesting of procedures and functions with the INFO command:
INFO, /Traceback
; Results in the following:
% At PROC3 <errex.pro(22)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
PV‑WAVE stopped at the PROC3 procedure, where the error occurred.
Error Condition 1
If the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 0
to:
ON_ERROR, 1
then the commands:
RETALL
.RUN errex
need to be executed to return to the main program level and recompile the file containing the example procedures.
To execute PROC1 again and check where PV‑WAVE returns after the error in PROC3, issue the following command:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Execution halted at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
INFO, /Traceback
% At $MAIN$.
Note that PV-WAVE returned to the main program level.
Error Condition 3
Next, the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 1
to:
ON_ERROR, 3
and the file containing the example procedures is recompiled and executed with the commands:
RETALL
.RUN errex
Issue the following command to execute PROC1 again:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Execution halted at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
To see where PV-WAVE has returned, issue the following command:
INFO, /Traceback
; Results in the following:
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
Note that this time, PV-WAVE returned to PROC2, which is the program unit that made the call to ON_ERROR.
Error Condition 0 with Continuation
Next, the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 3
to:
ON_ERROR, 0, /Continue
and the file containing the example procedures is recompiled and executed with the commands:
RETALL
.RUN errex
Issue the following command to execute PROC1 again:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Error occurred at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
3 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Error occurred at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
To see where PV-WAVE has returned, issue the following command:
INFO, /Traceback
% At $MAIN$.
Note that PV-WAVE has returned to the main program level.
Error Condition 1 with Continuation
If the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 0, /Continue
to:
ON_ERROR, 1, /Continue
and the file containing the example procedures is recompiled and executed with the commands:
RETALL
.RUN errex
Issue the following command to execute PROC1 again:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Error occurred at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
To see where PV-WAVE has returned, issue the following command:
INFO, /Traceback
% At $MAIN$.
Note that execution continued on the main program level.
Error Condition 2 with Continuation
Finally, the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 1, /Continue
to:
ON_ERROR, 2, /Continue
and the file containing the example procedures is recompiled and executed with the commands:
RETALL
.RUN errex
Issue the following command to execute PROC1 again:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Error occurred at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
3 is odd.
To see where PV-WAVE has returned, issue the following command:
INFO, /Traceback
% Called from $MAIN$.
note | In this example, execution continued in PROC3 after the error, and PROC1 finished executing. |
PRO PROC1
FOR i = 1, 4 DO BEGIN
PROC2, i
ENDFOR
END
PRO PROC2, j
; Invoke the ON_ERROR procedure at this point.
ON_ERROR, 0
IF (j MOD 2) EQ 0 THEN BEGIN
PROC3, j
ENDIF ELSE BEGIN
PROC4, j
ENDELSE
END
PRO PROC3, k
; The call to a nonexistent procedure, PAINT, occurs here.
PAINT, k, ' is even.'
END
PRO PROC4, m
PRINT, m, ' is odd.'
END
Note that ON_ERROR has the argument 0 in PROC2. If the procedures are placed in the file errex.pro in your working directory, all of them can be compiled with the following command:
.RUN errex
Next, invoke the top-level procedure and examine the results:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Execution halted at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
Examine which procedure PV-WAVE returned to by looking at the current nesting of procedures and functions with the INFO command:
INFO, /Traceback
; Results in the following:
% At PROC3 <errex.pro(22)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
PV-WAVE stopped at the PROC3 procedure, where the error occurred. This is where PV-WAVE would have stopped if ON_ERROR had not been called.
If the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 0
to:
ON_ERROR, 1
then the commands:
RETALL
.RUN errex
need to be executed to return to the main program level and recompile the file containing the example procedures.
To execute PROC1 again and check where PV-WAVE returns after the error in PROC3, issue the following command:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Execution halted at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
INFO, /Traceback
% Called from $MAIN$.
Note that PV-WAVE returned to the main program level.
As a final example, the call to ON_ERROR in PROC2 is changed from:
ON_ERROR, 1
to:
ON_ERROR, 3
and the file containing the example procedures is recompiled and executed with the commands:
RETALL
.RUN errex
Issue the following command to execute PROC1 again:
PROC1
; Results in the following:
1 is odd.
% Attempt to call undefined
% procedure/function: PAINT.
% Execution halted at PROC3 <errex.pro(21)>.
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
To see where PV-WAVE returned, issue the following command:
INFO, /Traceback
; Results in the following:
% Called from PROC2 <errex.pro(13)>.
% Called from PROC1 <errex.pro(5)>.
% Called from $MAIN$.
Note that this time, PV-WAVE returned to PROC2, which is the program unit that made the call to ON_ERROR.
See Also
For more information, see the PV‑WAVE Programmer’s Guide.
