ON_ERROR Procedure

Determines the action taken when an error is detected inside a user-written procedure or function.

Usage

Input Parameters

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
ON_ERROR, 0

; Invoke the ON_ERROR procedure at this point.

IF (j MOD 2) EQ 0 THEN BEGIN

PROC3, j

ENDIF ELSE BEGIN

PROC4, j

ENDELSE
END
PRO PROC3, k
PAINT, k, ' is even.'

; The call to a nonexistent procedure, PAINT, occurs here.

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
       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
% 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.

Error Condition 1

If the call to ON_ERROR in PROC2 is changed from

ON_ERROR, 0

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
      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

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
       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
% 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

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
            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

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
            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

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
            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
ON_ERROR, 0

; Invoke the ON_ERROR procedure at this point.

IF (j MOD 2) EQ 0 THEN BEGIN

PROC3, j

ENDIF ELSE BEGIN

PROC4, j

ENDELSE
END
PRO PROC3, k
PAINT, k, ' is even.'

; The call to a nonexistent procedure, PAINT, occurs here.

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
       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
% 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

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
      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

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
       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
% 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.

ON_ERROR Procedure

Usage

Input Parameters

Keywords

Example

Error Condition 0

Error Condition 1

Error Condition 3

Error Condition 0 with Continuation

Error Condition 1 with Continuation

Error Condition 2 with Continuation

See Also