Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


  >  Docs Center  >  ENVI API  >  Manage Errors

ENVI

Manage Errors

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
  3. Compile and run example3.pro.

Results:

  • The program fully executes, and the IDL Console reports "File Does not exist."
  • The !ERROR_STATE variable is populated with the error message.
  • A log file (envitempfile*.dat) is created in the system's temporary directory, and the error message appears at the bottom of the file.
  • The raster variable is undefined.

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
  3. Compile and run example1.pro.

Results:

  • The program fully executes, and the IDL Console reports "File Does not exist."
  • The IDL system variable !ERROR_STATE is null.
  • A log file (envitempfile*.dat) is created in the system's temporary directory, and the error message appears at the bottom of the file.
  • The raster variable is null.

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
  3. Compile and run example2.pro.

Results:

  • The program stops on the offending line and halts execution.
  • The IDL system variable !ERROR_STATE is populated with the error message. You can view the contents of !ERROR_STATE from the System field of the Variable Watch Window. Or, type the following at the IDL command line to view the error message:
    PRINT, !ERROR_STATE.MSG

    See IDL Help for more information on !ERROR_STATE.

  • The IDL Console reports the following:
    File Does not exist.
    Execution halted at: EXAMPLE2...$MAIN$
  • A log file (envitempfile*.dat) is created in the system's temporary directory, and the error message appears at the bottom of the file.
  • The raster variable is undefined.

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
  3. Compile and run example4.pro.

Results:

  • The program fully executes.
  • An Information dialog appears that says, "Please provide a valid file."
  • If your Enable System Logging preference is set to True, the error message is also written to the system log file, located in your home directory.
  • The raster variable is undefined.



© 2018 Harris Geospatial Solutions, Inc. |  Privacy Policy
My Account    |    Store    |    Contact Us