Error Handling

When writing programs to customize ENVI or to perform an automated task, you should add some error-handling code to catch potential errors.

The first three examples in this topic demonstrate error handling in batch programs, which are used to process data without any user interface or user interaction. Errors are handled the same way in batch programs as with Toolbox extensions (where you can interact with the user interface), but with Toolbox extensions you can display error dialogs and customize their messages. Example 4 shows how to do this.

See the following sections:

Log Files

Log files are used primarily in batch programs to summarize processing results, to report the status of key processing events, and to list any errors issued when running ENVI routines.

Use the LOG_FILE property in the ENVI routine to specify a full path and filename for a log file. To disable error logging, you can choose to not set LOG_FILE at all, or set it to a null string (''). Each time you set LOG_FILE, a new log file is started, overwriting any existing files with the same name.

The log file that ENVI creates will contain the date and time of processing events, your system specifications, and any errors that were encountered. Use the ENVI::LogMessage method to write a custom message to this log file if needed. You can insert the LogMessage method multiple times in your code, for example, to indicate successful completion of a process so that you can review the log file later.

The first three batch examples demonstrate the use of log files.

Example 1: Use a CATCH Block in a Batch Program

You can manage any errors yourself by inserting a block of code in your script that contains the IDL CATCH routine. See the IDL Help for a complete description of CATCH.

CATCH is a generic error handler that prevents program execution from halting when an unexpected error condition occurs, and it sends the error message to the IDL system variable !ERROR_STATE. A CATCH block should be responsible for cleaning up any global resources allocated within the scope of the routine, including resources that would leak during an unexpected error.

  1. Copy and paste the following code into a new IDL Editor window and save it as example3.pro:

    2. PRO EXAMPLE3

    COMPILE_OPT IDL2

     

    ; Check error state

    CATCH, err

    IF err NE 0 THEN BEGIN

       CATCH, /CANCEL

       PRINT, !ERROR_STATE.MSG

       e.Close

       RETURN

    ENDIF

     

    ; Open a raster with the wrong filename

    e = ENVI(/HEADLESS)

    e.LOG_FILE = e.GetTemporaryFilename()

    file = 'doesnotexist.dat'

    raster = e.OpenRaster(file)

    END

  2. Compile and run example3.pro.

Results:

Example 2: Set the ERROR Keyword in a Batch Program

The ENVI routine and most methods have an ERROR keyword that catches errors in your code. Whenever you issue a command where an error could occur, set ERROR to a named variable that will contain the system error message. If no error occurs, the ERROR variable will be set to a null string ('').

The following code shows an error scenario where the ENVI::OpenRaster method is invoked with a file that does not exist.

  1. Copy and paste this code into a new IDL Editor window and save it as example1.pro:

    2. PRO EXAMPLE1

    COMPILE_OPT IDL2

    ; Launch the application with a log file

    e = ENVI(/HEADLESS)

    e.LOG_FILE = e.GetTemporaryFilename()

     

    ; Open the file

    file = 'doesnotexist.dat'

    raster = e.OpenRaster(file, ERROR = err)

     

    ; Check error state

    IF err THEN BEGIN

      PRINT,err

      e.Close

      RETURN

    ENDIF

    END

  2. Compile and run example1.pro.

Results:

Example 3: Omit the ERROR Keyword in a Batch Program

The following code shows an example of opening a file without the required filename (and the ERROR keyword was not specified). This is not a recommended method; you should always set the ERROR keyword or write a CATCH block (see Example 3) to catch potential errors.

  1. Copy and paste this code into a new IDL Editor window and save it as example2.pro:

    2. PRO EXAMPLE2

    COMPILE_OPT IDL2

    ; Launch the application with a log file

    e = ENVI(/HEADLESS)

    e.LOG_FILE = e.GetTemporaryFilename()

     

    ; Open the file

    file = 'doesnotexist.dat'

    raster = e.OpenRaster(file)

    END

  2. Compile and run example2.pro.

Results:

An alternative to using the !ERROR_STATE variable is to issue the following command, which shows the full stack trace to the error:

HELP, /LAST_MESSAGE, OUTPUT = lastError

PRINT, lastError

Example 4: Write a Custom Error Message in a Toolbox Extension

When writing Toolbox extensions, you can use the ERROR keyword or insert a CATCH block in the same manner as writing batch programs, but rather than displaying IDL's default error messages (contained in the !ERROR_STATE variable), you can write your own custom error message using the ENVI::ReportError method. To issue information or warning dialogs instead of error messages, set the INFORMATION or WARNING keywords, respectively. See Write and Deploy Toolbox Extensions for example code that uses the ReportError method.

The following is a simple example that checks for a valid input file.

  1. Copy and paste the following code into a new IDL Editor window and save it as example4.pro:

    2. PRO EXAMPLE4

    COMPILE_OPT IDL2

    ; Start the application

    e = ENVI()

    raster = e.OpenRaster(doesnotexist, ERROR = error)

    IF error THEN e.ReportError, 'Please provide a valid file.', /INFORMATION

    END

  2. Compile and run example4.pro.

Results: