ON_ERROR Procedure

Reference Guide > O Routines > ON_ERROR Procedure

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.