wave_error
Reports an error condition for the Option to PV‑WAVE.
C Usage
void wave_error(error_number, string, print, trace, on_ioerror)
long error_number;char *string;long print, trace, on_ioerror;
FORTRAN Usage
Not available.
Input Parameters
error_number—A value to use to set !Err.
string—A string to use to set !Err_String.
print—If nonzero the error message is printed.
trace—In nonzero trace information will be printed.
on_ioerror—If nonzero, the action taken after the error will be determined from the ON_IOERROR state of the currently active PV‑WAVE procedure or function.
Discussion
The wave_error function allows the Option procedure or function to tell the PV‑WAVE kernel that it should proceed as if the Option procedure or function failed. When the Option procedure or function returns to the calling interpreter, the interpretation of the current PV‑WAVE command will be immediately terminated and PV‑WAVE will continue based on the ON_ERROR or ON_IOERROR state of the currently active PV‑WAVE procedure or function.
note | The wave_error function should not be called if the system procedure or function is exiting because an OPI_DO_NOT_PROCEED status was returned from another OPI function. The OPI function will have already set the proper error conditions in the PV‑WAVE kernel. Unsuccessful OPI functions return to the Option procedure or function for one reason only; to allow the Option procedure or function to clean up malloc’d memory before returning to the PV‑WAVE kernel. |
If the wave_error function is not called before an Option procedure or function returns, the PV‑WAVE kernel will proceed as if there were no errors.
When the PV‑WAVE interpreter detects an error condition, it normally prints an error message string, sets the !Err system variable to a number associated with the error, sets the !Err_String system variable to a text string associated with the error, prints a traceback message and then proceeds according to whether the error was an I/O error or regular error.
The Option procedure or function can control how PV‑WAVE reacts to its errors with the arguments to the wave_error function, as follows:
The error_number argument is the value to which !Err will be set. The string argument is the text string that will appear in the printed error message and in the !Err_String system variable. If the print argument is FALSE, the error message will not be printed; only the system variables will be set. If the trace argument is FALSE, the traceback message will not be printed. If the on_ioerror argument is TRUE, the action taken after the error will be determined from the ON_IOERROR state of the currently active PV‑WAVE procedure or function. Otherwise, the action taken after the error will be determined from the ON_ERROR state of the currently active PV‑WAVE procedure or function. The PV‑WAVE !Err system variable will be set to the value of error_number and the string argument will be copied to the PV‑WAVE !Err_String system variable. The PV‑WAVE kernel actually copies the string and does not free it. If the trace argument is TRUE, the PV‑WAVE kernel will print out the traceback information that commonly accompanies PV‑WAVE errors. If the print argument is TRUE, the string will also be printed to stderr just as kernel error messages are printed. If print is FALSE, only the system variables will be updated. That is, no traceback or error message will be printed. If your Option needs to return any other status information to the PV‑WAVE user, it should be written as a system function and return a PV‑WAVE variable that contains the status information unique to your function.
