Description of Error Handling Routines

PV-WAVE divides execution errors into three categories: input/output, math, and all others. ON_ERROR gives control over how regular errors are handled. The ON_IOERROR procedure allows you to change the default way in which I/O errors are handled. FINITE, and CHECK_MATH give control over math errors.

In the default case, whenever an error is detected by PV-WAVE during the execution of a program, program execution stops and an error message is printed. The variable context is that of the program unit, (procedure, function, or main program), in which the error occurred.

As explained in "Error Handling in Procedures", novices are frequently dismayed to find that all their variables have seemingly disappeared after an error occurs inside a procedure or function. The misunderstood subtlety is that after the error occurs, the context is that of the called procedure or function, not the main level. All variables in procedures and functions, with the exception of parameters and common variables, are local in scope.

Sometimes it is possible to recover from an error by manually entering statements to correct the problem. Possibilities include setting the values of variables, closing files, etc., and then entering the .CON executive command, which will resume execution at the beginning of the statement that caused the error.

As an example, if an error stop occurs because an undefined variable is referenced, simply define the variable from the keyboard and then continue execution with .CON.

The procedures ON_ERROR and ON_ERROR_GOTO determine the action to take when an error is detected in a procedure or function. This section provides an introduction to these procedures. For more details on these procedures, see their descriptions in the PV‑WAVE Reference.

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.

The ON_ERROR procedure specifies an action to take after an error occurs inside a procedure or function. The following table lists the basic options for error recovery. These options specify an action and cause program execution to stop.

Table 11-1: Options for Error Recovery
Value	Action
0	Stop immediately in the context of the procedure or function that caused the error. This is the default action.
1	Return to the main program level and stop.
2	Return to the caller of the program unit that called ON_ERROR and stop.
3	Return to the program unit that called ON_ERROR and stop.

Additional options, specified in conjunction with the Continue keyword, specify an action to take and allow the program to continue executing after the action. These options are listed in Options for Error Recovery and Program Continuation:

Table 11-2: Options for Error Recovery and Program Continuation
Value	Action
0	Continue in the procedure that caused the error.
1	Return to $MAIN$ and continue.
2	Return to the caller that established the ON_ERROR condition and continue.
3	Return to the program unit that established the ON_ERROR condition and continue.

One useful option is to use ON_ERROR to cause control to be returned to the caller of a procedure in the event of an error. The statement:

placed at the beginning of a procedure will have this effect. It is a good idea to include this statement in library procedures, and any routines that will be used by others, but only after debugging is completed. Debugging a routine after using the ON_ERROR procedure is made more difficult because the routine is exited as soon as an error occurs.

The ON_ERROR_GOTO procedure transfers program control to a specified statement label after an error occurs. A is an identifier followed by a colon. A label may exist on a line by itself.

WAVE Widgets procedures normally try to continue executing after an error has occurred. WAVE Widgets procedures report the error and traceback information, and return a value indicating a failure has occurred. Usually, the value 0L is returned as the widget ID. It is the programmer’s responsibility to check returned values and take appropriate action.

WAVE Widgets callbacks, event and input handlers, timers, and work procedures by default return from the given procedure first and then continue execution after an error. When an error is detected, execution is continued at the statement specified by the input parameter of the last ON_ERROR call or by the ON_ERROR_GOTO statement in the given callback, handler, timer, or work procedure routine.

It is the programmer’s responsibility to set ON_ERROR or ON_ERROR_GOTO appropriately. To override the default error handling behavior of callbacks, handlers, timers, or work procedures, set:

note	If a WAVE Widgets application stops during execution, you can use the RETALL procedure to stop all the currently running WAVE Widgets applications and return to the main program level.

The default action for handling input/output errors is to treat them exactly like regular errors and follow the error handling strategy set by ON_ERROR. You can alter the default handling of I/O errors using the ON_IOERROR procedure to specify the label of a statement to which execution should jump if an I/O error occurs. When PV-WAVE detects an
I/O error and an error handling statement has been established, control passes directly to the given statement without stopping program execution. In this case, no error messages are printed.

When writing procedures and functions that are to be used by others, it is good practice to anticipate and gracefully handle errors caused by the user. For example, the following procedure segment, which opens a file specified by the user, handles the case of a non-existent file or read error:

The important things to note are that the Free_Lun procedure is always called, even in the event of an error, and that this procedure always returns to its caller. It returns an undefined value if an error occurred, causing its caller to encounter the error.