Debugging Problems in the IDL Search Path

The IDL Search Path is a critical resource for IDL whenever a program gets to a line of code that contains the name of an as-yet uncompiled procedure or function. IDL reads the name of the routine and looks first in the current working directory that IDL starts up in, then in all the directories stored in the IDL environment variable !path. The current setting of your search path can be displayed with the command

print, !path

There are several things that can go wrong in the set-up or specification of an IDL Search Path. When it is not working right, errors can be triggered like:

IDL> MY_PROCEDURE, 'Hello', 100.0
Attempt to call undefined procedure/function: 'MY_PROCEDURE'.
Execution halted at: $MAIN$

... or:

IDL> x = MY_FUNCTION('Hello', 100.0)
Variable is undefined: MY_FUNCTION.
Execution halted at: $MAIN$

... or even, during compilation:

IDL> x = MY_FUNCTION('Hello', ANY_KEYWORD=100.0)
                                          ^
Syntax error.

This Help Article is designed to help you debug problems like that and to configure your IDL Search Path in an optimal way.

[I should warn that this Help Article is confined to discussing the above errors when the procedure or function in question has its own same-named '.pro' file. That is, this Help Article assumes that MY_PROCEDURE and MY_FUNCTION are in files named 'my_procedure.pro' and 'my_function.pro', resp. If the above errors are just being thrown by a routine that is stored in a file that does not share the routine's name, then the problem is probably not with your IDL search path.]

The algorithm for setting IDL's search path is:

1. Detect whether there is an environment variable named "IDL_PATH" in the system or shell that is starting the 'idl' or 'idlde' process. If yes, ignore all other path settings that come either from user preference configuration files or from IDL defaults.
2. If there is no IDL_PATH variable defined in the system or shell that is starting IDL, then the IDL Search Path will be exactly what is visible in the 'Search path' list displayed in the 'File -> Preferences... -> Path tab page' dialog
3. Assuming case 1, there is an IDL_PATH environment variable definition: If there is a token named "" wrapped in double-quotes in such an IDL_PATH environment variable, include this IDL version's 'lib' and 'examples' directories in the IDL Search Path and all their subdirectories.
4. If there is no "" token in the IDL_PATH, or if it is not wrapped in double-quotes, include only the user-specified directory paths in the IDL Search Path. This means that all of IDL's 'lib' and 'examples' .pro's will be unfindable by this IDL session. (This same problem would occur where there is no IDL_PATH in the picture, if there were no "" item showing in the 'Search path' list on the 'File -> Preferences... ->Path tab page' dialog.
5. In a system/shell environment IDL_PATH variable definition, the prepending of a '+' character to any user-specified directory path will insure that all subdirectories at all levels under that user-specified directory will be appended to the IDL Search Path.
6. Regardless of any of the above, if IDL's internal environment variable !PATH is set during startup, e.g. by a startup script specified by the IDL_STARTUP system/shell environment variable or in IDLDE's 'File -> Preferences... -> Startup tab page -> Startup File field', that !PATH definition will be the sole IDL Search Path used at the beginning of the user's IDL session. It will override all other settings attempted by the user.

Obviously, the best way to start debugging IDL Search Path problems is to inspect the state of !PATH right after a fresh IDL initialization. Here is the simplest command to view this:

print, !path

If you do not find a large number of directories from the '.../idl.../lib/' or '.../idl.../examples/' directory trees in the output of the above command, then you probably have troubles with item 4 or item 6 of the IDL searching algorithm discussed above. That is, is probably not properly specified in your internal IDL or your external system/shell environment.

The first place to troubleshoot this problem is in your IDLDE's 'File->Preferences...' dialog. If you see that there is no "" token showing in the 'Search path' list, then your search for the problem is probably over. You simply click on the 'Insert Standard Libraries' button and hit 'OK' on the Preferences... dialog, and your IDL Search Path is automatically updated. Command-line IDL lovers could accomplish the same by entering:

currentEnvPath = pref_get('IDL_PATH')
newEnvPath = '"" + path_sep(/SEARCH_PATH) + $
    currentEnvPath
pref_set, 'IDL_PATH', newEnvPath, /COMMIT

Alternatively, you may discover that the IDLDE's Preferences... Path tab page is grayed out and disabled ... or that the PREF_SET command is returning the error "PREF_SET: Preference value is read only because it has a current effective source (environment variable) with a higher priority than the user preference file: IDL_PATH." This should lead you next to looking for an IDL_PATH variable on your UNIX shell or in your Windows system. At the UNIX shell that started IDL you would find this by typing "echo $IDL_PATH". In Windows you would check to see if IDL_PATH is defined in the 'Start -> Control Panel -> System icon -> Advanced tab page -> Environment Variables...' dialog.

If you find that variable defined, and you find it defined without an "" token, then you have two choices: a) you can delete that environment variable, or b) you can redefine it to include the "" token. If you are part of a larger network, then you might have troubles getting rid of the current IDL_PATH definition; it may be defined somewhere on your network out of your control, or it may be a System variable over which you have no control. In this case, you can simply redefine it in your own user environment. On UNIX , your options to delete would be to insert in your local '.cshrc' or '.bashrc' shell resource files "unsetenv IDL_PATH" (csh syntax) or "unset IDL_PATH" (bash syntax). Your options to modify would be "setenv IDL_PATH "":$IDL_PATH" (csh syntax) or "export IDL_PATH="":$IDL_PATH" (bash syntax). On Windows your option would be to define IDL_PATH as a User Envrionment Variable in the Control Panel's Environment Variables dialog.

If neither setting user preferences in IDL's 'Preferences...' dialog (or via PREF_SET) nor setting the IDL_PATH system/shell environment variable is fixing the problem, then your problem is probably with an IDL_STARTUP file. The following two commands would detect the presence of an IDL_STARTUP file:
- "print, pref_get('IDL_STARTUP')" would find any startup file defined in your internal IDL environment.
- "print, getenv('IDL_STARTUP')" would find a higher-precedent IDL_STARTUP file located in your external system/shell environment. If you find either or both such files, you would need to inspect them for assignment statements referencing the IDL environment variable "!path".

If, in the end, you cannot find a solution through any of the above methods, you can always make your own personal IDL_STARTUP file with your own !path definition. One weakness to this approach, however, is that !path assignments cannot interpret or expand the simple tokens "" or "+". Thus, this kind of assignment does not work:

!path = '"

Rather, you have to have an explicit assignment that contains a long string that would look something like this (example from Mac OS X):

!path = $
'/Applications/rsi/idl_6.3/lib/bridges:' + $
'/Applications/rsi/idl_6.3/lib/dicomex:' + $
'/Applications/rsi/idl_6.3/lib/hook:' + $
'/Applications/rsi/idl_6.3/lib/itools/components:' + $
'/Applications/rsi/idl_6.3/lib/itools/framework:' + $
'/Applications/rsi/idl_6.3/lib/itools/ui_widgets:' + $
'/Applications/rsi/idl_6.3/lib/itools:' + $
'/Applications/rsi/idl_6.3/lib/obsolete:' + $
'/Applications/rsi/idl_6.3/lib/utilities:' + $
'/Applications/rsi/idl_6.3/lib/wavelet/source:' + $
'/Applications/rsi/idl_6.3/lib:' + $
'/Applications/rsi/idl_6.3/examples/data:' + $
'/Applications/rsi/idl_6.3/examples/demo/demodata:' + $
'/Applications/rsi/idl_6.3/examples/demo/' + $
'demoslideshows/slideshowsrc:' + $
'/Applications/rsi/idl_6.3/examples/demo/demosrc:' + $
'/Applications/rsi/idl_6.3/examples/demo:' + $
'/Applications/rsi/idl_6.3/examples/doc/bridges:' + $
'/Applications/rsi/idl_6.3/examples/doc/dicom:' + $
'/Applications/rsi/idl_6.3/examples/doc/file_io:' + $
'/Applications/rsi/idl_6.3/examples/doc/image:' + $
'/Applications/rsi/idl_6.3/examples/doc/itools:' + $
'/Applications/rsi/idl_6.3/examples/doc/language:' + $
'/Applications/rsi/idl_6.3/examples/doc/objects:' + $
'/Applications/rsi/idl_6.3/examples/doc/plot:' + $
'/Applications/rsi/idl_6.3/examples/doc/project:' + $
'/Applications/rsi/idl_6.3/examples/doc/sdf:' + $
'/Applications/rsi/idl_6.3/examples/doc/signal:' + $
'/Applications/rsi/idl_6.3/examples/doc/utilities:' + $
'/Applications/rsi/idl_6.3/examples/doc/widgets:' + $
'/Applications/rsi/idl_6.3/examples/HP_TIFF:' + $
'/Applications/rsi/idl_6.3/examples/imsl:' + $
'/Applications/rsi/idl_6.3/examples/misc:' + $
'/Applications/rsi/idl_6.3/examples/mjpeg2000:' + $
'/Applications/rsi/idl_6.3/examples/widgets/wexmast:' + $
'/Applications/rsi/idl_6.3/examples/widgets:' + $
'/Applications/rsi/idl_6.3/examples:' + $
'/Users/johndoe'