Classic ENVI Programming: Adapting user functions for use in ENVI without IDL

Note that the following information applies to the classic ENVI programming interface, and not to the new Application Programming Interface introduced with ENVI 5.

User functions can still be added to classic ENVI even when access to IDL is prohibited by the license. However, because ENVI without IDL can't compile ASCII .pro files, the compiled user function routines must be provided in binary .sav files. Because of the way that IDL Run Time operates, the user function code may need some important modifications before making the save file in IDL.

Add a Compile_Opt statement to your code

Because the ENVI library functions are unknown to the IDL compiler, any references to them will be erroneously interpreted as variable names. To avoid this error, include a Compile_Opt statement within all of the user function's routines. The Compile_Opt statement must specify the STRICTARR argument to instruct the compiler to force all variable dereferencing syntax to require square brackets. If you are still using parantheses to dereference variables (which was standard many years ago, prior to the release of IDL 5.0/ENVI 3.0), then you must correct this syntax prior to compiling your code.

Use RESOLVE_ALL to compile dependent routines

Many common IDL procedures aren't actually built into IDL (as part of the binary IDL application) but are included in the IDL library (or lib) as .pro code. For example, XMANAGER, CONGRID, and SWAP_ENDIAN are all IDL lib routines. When working in ordinary IDL or ENVI you usually don't notice if a routine is built-in or part of the lib because IDL automatically compiles needed routines whenever necessary. However, remember that ENVI RT can't compile any .pro code, so if your user function includes any lib routines they must be compiled in the IDL session before making the save file. Because this situation occurs quite often, IDL provides a special routine called Resolve_All to find and compile all dependent routines in any compiled procedure.

However, using Resolve_All on ENVI user functions is a bit different than using it on ordinary IDL procedures. Resolve_All will only find and compile dependent routines whose filenames allow auto-compilation to work (i.e., they must be stored in a file whose name is the same as the routine's name). None of the ENVI routines follow this naming convention, except for the routine called envi -- which should actually be excluded from the save file. Therefore, two keywords must be used when calling Resolve_All. The first is Continue_On_Error, which allows Resolve_All to continue working even after it fails to find an ENVI routine (usually it halts execution to report this problem). The second is Skip_Routines, which must be set to the string 'envi', which tells Resolve_All to ignore any references to routines with this name (otherwise, envi would be compiled into your save file, which could prevent execution of your user function, and would also create a very large save file).


Step by step instructions for making the save file

1. Immediately following the procedure definition statement in the user function code add the compile_opt STRICTARR statement.
   
   Remember that the compile_opt instruction is only active within the procedure where it is included (see the IDL Online Help for more details), so if your user function consists of multiple procedures (for example, a widget creation routine and various event handlers) then you should add the compile_opt statement after each procedure definition statement.
2. Save the modified user function code, overwriting the original file.
   
   
3. Start a new IDL session.
   
   
4. Compile the modified user function code in the new IDL session.
   
   At this point, if you receive any syntax errors upon compilation you have probably used the wrong variable dereferencing syntax (you must use square brackets). You must correct these errors before proceeding.
   
   
5. Call Resolve_All to compile all dependent procedures in the code:
   
   
   IDL> Resolve_All, /continue_on_error, skip_routines='envi'

   If your user function uses any ENVI library routines, expect to see several error messages printed to the Command Log.

6. Make the save file by calling the SAVE procedure with the routines keyword set:
   
   
   IDL> SAVE, file='my_user_function.sav', /routines

Review 5/16/14 PS