The MESSAGE procedure is used by user procedures and functions to issue errors. It has the form:
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
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 an input/output error occurs. ON_IOERROR, EOD ;Read every line of the file. WHILE 1 DO READF, UNIT, LINE ;An error has occurred. Cancel the input/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 to be issued as an ; input/output error. Use of NONAME prevents MESSAGE from tacking ; the name of the current routine to the beginning of the message ; string since !ERROR_STATE.MSGalready contains it. MESSAGE, !ERROR_STATE.MSG,/NONAME, /IOERROR
IDL messages include text and formatting information which, when combined with text supplied in the call to MESSAGE, provide information to the program's user about the error that occurred. For example, entering
MESSAGE, 'Howdy, folks'
at the IDL command line produces the following output:
% $MAIN$: Howdy, folks % Execution halted at: $MAIN$
indicating that the message was issued from within the IDL
$MAIN$ program. Everything displayed, except for the word "test," is part of the IDL message definition.
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. In addition, if you wish to provide something other than the default error message for your own IDL programs, you can define your own message blocks and error messages. See DEFINE_MSGBLK and DEFINE_MSGBLK_FROM_FILE for additional details. Specify the BLOCK and NAME keywords to the MESSAGE procedure to issue a message from a message block you have defined.