To generate an exception and cause control to return to the error handler, use the MESSAGE procedure. Calling MESSAGE generates an exception that sets the !ERROR_STATE system variable. !ERROR_STATE.MSG is set to the string used as an argument to MESSAGE.

The MESSAGE procedure is used by user procedures and functions to issue errors. It has the form:

MESSAGE, Text

where Text is a scalar string that contains the text of the error message.

The MESSAGE procedure issues error and informational messages using the same mechanism employed by built-in IDL routines. By default, the message is issued as an error, the message is output, and IDL takes the action specified by the ON_ERROR procedure.

As a side effect of issuing the error, appropriate fields of the system variable !ERROR_STATE are set; the text of the error message is placed in !ERROR_STATE.MSG, or in !ERROR_STATE.SYS_MSG for the operating system�€™s component of the error message. See !ERROR_STATE for more information.

As an example, assume the statement:

MESSAGE, 'Unexpected value encountered.'

is executed in a procedure named CALC. IDL would print:

% CALC: Unexpected value encountered.

and execution would halt.

The MESSAGE procedure accepts several keywords that modify its behavior. See MESSAGE for additional details.

Another use of MESSAGE involves re-signaling 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 aninput/output error occurs.
ON_IOERROR, EOD
 
; Read every line of the file.
WHILE 1 DO READF, UNIT, LINE
 
; An error has occurred. Cancel theinput/output error trap.
EOD: ON_IOERROR, NULL
 
; Close the file.
FREE_LUN, UNIT
 
; Reissue the error. !ERROR_STATE.MSGcontains the appropriate
; text. The IOERROR keyword causes it tobe issued as an
; input/output error. Use of NONAMEprevents MESSAGE from tacking
; the name of the current routine to thebeginning of the message
; string since !ERROR_STATE.MSG alreadycontains it.
MESSAGE, !ERROR_STATE.MSG, /NONAME,/IOERROR

Message Blocks

IDL

MESSAGE, 'Howdy, folks'

at the IDL command line

% $MAIN$: Howdy, folks
% Execution halted at: $MAIN$

indicating that the message was issued from within the IDL $MAIN$ program.

A message block is a collection of messages that are loaded into IDL as a single unit. At startup, IDL contains a single internal message block named IDL_MBLK_CORE, which contains the standard messages required by the IDL system. By default, MESSAGE throws the IDL_M_USER_ERR message from the IDL_MBLK_CORE message block, producing output similar to that shown above.

Dynamically loadable modules (DLMs) usually define additional message blocks for their own needs when they are loaded, and you can provide something other than the default error message for your own IDL.