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.
- Copy and paste the following code into a new IDL Editor window and save it as example3.pro:
PRO EXAMPLE3
COMPILE_OPT IDL2
CATCH, err
IF err NE 0 THEN BEGIN
CATCH, /CANCEL
PRINT, !ERROR_STATE.MSG
e.Close
RETURN
ENDIF
e = ENVI(/HEADLESS)
e.LOG_FILE = e.GetTemporaryFilename()
file = 'doesnotexist.dat'
raster = e.OpenRaster(file)
END
- 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.
- Copy and paste this code into a new IDL Editor window and save it as example1.pro:
PRO EXAMPLE1
COMPILE_OPT IDL2
e = ENVI(/HEADLESS)
e.LOG_FILE = e.GetTemporaryFilename()
file = 'doesnotexist.dat'
raster = e.OpenRaster(file, ERROR = err)
IF err THEN BEGIN
PRINT,err
e.Close
RETURN
ENDIF
END
- 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.
- Copy and paste this code into a new IDL Editor window and save it as example2.pro:
PRO EXAMPLE2
COMPILE_OPT IDL2
e = ENVI(/HEADLESS)
e.LOG_FILE = e.GetTemporaryFilename()
file = 'doesnotexist.dat'
raster = e.OpenRaster(file)
END
- 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.
- Copy and paste the following code into a new IDL Editor window and save it as example4.pro:
PRO EXAMPLE4
COMPILE_OPT IDL2
e = ENVI()
raster = e.OpenRaster(doesnotexist, ERROR = error)
IF error THEN e.ReportError, 'Please provide a valid file.', /INFORMATION
END
- 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.