Error Signaling
Use the MESSAGE procedure in user-written procedures and functions to issue errors. It has the form:
MESSAGE, text
where text is a scalar string describing the error.
MESSAGE issues error and informational messages using the same mechanism employed by built-in routines. By default, the message is issued as an error, the message is output, and PV-WAVE takes the action specified by the ON_ERROR procedure. As a side effect of issuing the error, the system variables !Err and !Error are set and the text of the error message is placed in the system variable !Err_String.
As an example, assume the statement:
MESSAGE, 'Unexpected value encountered.'
is executed in a procedure named CALC. The result would be the following:
% CALC: Unexpected value encountered.
MESSAGE accepts several keywords which modify its behavior. See the description of MESSAGE in the PV‑WAVE Reference for additional details.
Another use for MESSAGE involves resignaling trapped errors. For example the following code uses ON_IOERROR to read from a file until an error (presumably end of file) occurs. It then closes the file and reissues the error:
; Open the data file.
OPENR, UNIT, 'data.dat', /Get_Lun
; Arrange for jump to label eod when an I/O error occurs.
ON_IOERROR, eod
; Read every line of the file.
TOP: READF, UNIT, LINE
; Go read the next line.
GOTO, TOP
; An error has occurred. Cancel the I/O error trap.
eod: ON_IOERROR, NULL
; Close the file.
Free_Lun, UNIT
; Reissue the error. !Err_string contains the appropriate text.
; The keyword causes it to be issued as an I/O error. Use of
; Noname prevents MESSAGE from tacking the name of the current
; routine to the beginning of the message string, since
; !Err_String already contains it.
MESSAGE, !Err_string, /Noname, /Ioerror
Obtaining Traceback Information
It is sometimes useful for a procedure or function to obtain information about its caller(s). The INFO procedure returns, in a string array, the contents of the procedure stack, when the Calls keyword parameter is specified. The first element of the resulting array contains the module name, source file name and line number of the current level. The second element contains the same information for the caller of the current level, and so on back to the level of the main program.
For example, the following code fragment prints the name of its caller, followed by the source file name and line number of the call:
INFO, CALLS = a
; Print 2nd element.
PRINT, 'Called from: ', a(1)
Resulting in a message of the following form:
Called from: DIST <wave/lib/dist.pro (27)>
For this example, the commands were entered on a UNIX system; on a Windows system the pathname will appear differently.
Programs can readily parse the traceback information to extract the source file name and line number.
