Error Handling System Variables

The following system variables are either set by IDL when an error condition occurs or used by IDL when displaying information about errors.

!ERR

This system variable is obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !ERR system variable will continue to function as before, but all new code should use !ERROR_STATE.CODE.

!ERROR_STATE

A structure variable which contains the status of the last error message. Whenever an error occurs, IDL sets the fields in this system variable according to the nature of the field. An IDL error is always comprised of an IDL-generated component, and may also contain an operating system-generated component. !ERROR_STATE includes the following fields:

** Structure !ERROR_STATE, 8 tags, length=112, data length=108:

   NAME            STRING    'IDL_M_SUCCESS'

   BLOCK           STRING    'IDL_MBLK_CORE'

   CODE            LONG                    0

   SYS_CODE        LONG      Array[2]

   SYS_CODE_TYPE   STRING    ''

   MSG             STRING    ''

   SYS_MSG         STRING    ''

   MSG_PREFIX      STRING    '% '

where the meaning of the fields as follows:

NAME

A read-only string variable containing the error name of the IDL-generated component of the last error message. Although the error code—as defined below in CODE—may change between IDL versions, the name will always remain the same. If an error has not occurred in the current IDL session, this field is set to IDL_M_SUCCESS.

BLOCK

A read-only string variable containing the name of the message block for the IDL-generated component of the last error message. If an error has not occurred in the current IDL session, this field is set to IDL_MBLK_CORE.

CODE

The error code of the IDL-generated component of the last error in IDL. Whenever an error occurs, IDL sets this system variable to the error code (a negative integer number) of the error. Although the error code may change between IDL versions, the name—as defined above in NAME—will always remain the same. If an error has not occurred in the current IDL session, this field is set to 0.

SYS_CODE

A long-integer variable containing the error code of the last error’s operating system-generated component, if it exists.

For historical reasons, SYS_CODE is a two-element longword array. The first element of the array (that is, SYS_CODE[0]) contains the OS-defined error code. The second element of the array is not used, and always contains zero. Either !ERROR_STATE.SYS_CODE or !ERROR_STATE.SYS_CODE[0] will return the relevant error code.

SYS_CODE_TYPE

A string describing the type of system code contained in SYS_CODE. An empty string in this field indicates that there is no system code corresponding to the current error. The possible non-NULL values are:

Value

Meaning

errno

Unix/Posix system error

win32

Microsoft Windows Win32 system error

winsock

Microsoft Windows sockets library error

MSG

A read-only string variable containing the text of the last IDL-generated error message. Whenever an error occurs, IDL sets this field to the error message (a scalar string) that corresponds to the error code. If an error has not occurred in the current IDL session, this field is set to an empty string, ' '.

SYS_MSG

A read-only string variable containing the text of the last error’s operating system-generated component, if it exists. When an operating system error occurs, IDL sets this field to the OS-defined error message string. If an error has not occurred in the current IDL session, this field is set to an empty string, ' '.

MSG_PREFIX

A string variable containing the prefix string used for the IDL-generated component of error messages. This field takes its default value from a preference. See IDL_MSG_PREFIX for details.

This system variable replaces !ERROR, !ERR_STRING, !MSG_PREFIX, !SYSERR_STRING, and !SYSERROR, and includes two new fields: error name and block name.

Using !ERROR_STATE

At the beginning of an IDL session, !ERROR_STATE contains default information. To see this information, you can either view !ERROR_STATE from the System field of the Variable Watch Window or you can enter PRINT, !ERROR_STATE at the Command Line. After an error has occurred, all of the fields of !ERROR_STATE display their updated status.

You can use MESSAGE, /RESET to reset all the fields in !ERROR_STATE to their default values.

!ERROR

This system variable is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !ERROR system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.CODE.

!ERR_STRING

This system variable is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !ERR_STRING system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.MSG.

!EXCEPT

An integer variable that controls when IDL checks for invalid mathematical computations (exceptions), such as division by zero. The three allowed values are:

0

Never report exceptions.

1

Report exceptions when the interpreter is returning to an interactive prompt (the default).

2

Report exceptions at the end of each IDL statement. Note that this slows IDL by roughly 5% compared to setting !EXCEPT=1.

The value of !EXCEPT is used by the CHECK_MATH function to determine when to return errors. See CHECK_MATH for details.

Note: In versions of IDL up to and including IDL 4.0.1, the default exception handling was functionally identical to setting !EXCEPT=2.

!EXCEPT takes its default value from a preference.

!MOUSE

A structure variable that contains the status from the last cursor read operation. !MOUSE has the following fields:

** Structure !MOUSE, 4 tags, length=16:

   X               LONG               511

   Y               LONG               252

   BUTTON          LONG                 4

   TIME            LONG        1428829775

where the meaning of the fields a are described in the following sections.

X

Contains the X location (in device coordinates) of the cursor when the mouse button was pressed.

Y

Contains the Y location (in device coordinates) of the cursor when the mouse button was pressed.

BUTTON

Contains:

TIME

Contains the number of milliseconds since a base time.

!MSG_PREFIX

This system variable is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !MSG_PREFIX system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.MSG_PREFIX.

!SYSERROR

This system variable is obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !SYSERROR system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.SYS_CODE.

!SYSERR_STRING

This system variable is obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !SYSERR_STRING system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.SYS_MSG.

!WARN

A structure variable that causes IDL to print warnings to the console or command log when obsolete IDL features are found at compile time. !WARN has the following fields:

** Structure !WARN, 3 tags, length=3:

   OBS_ROUTINES         BYTE         0

   OBS_SYSVARS          BYTE         0

   PARENS               BYTE         0

where the meaning of the fields as follows:

OBS_ROUTINES

If this field is set to 1 (one), IDL generates warnings when it encounters references to obsolete internal or library routines.

OBS_SYSVARS

If this field is set to 1 (one), IDL generates warnings when it encounters references to obsolete system variables.

PARENS

If this field is set to 1 (one), IDL generates warnings when it encounters a use of parentheses to specify an index into an array.

Note: No warnings are generated when the fields of the !WARN structure are set equal to zero (the default).