When used in interactive mode (in the IDL Workbench, a command shell session, or anywhere you see the IDL> prompt) IDL automatically compiles and executes a user-written function or procedure when it is first referenced if:

  1. The source code of the function is in the current working directory or in a directory in the IDL search path defined by the system variable !PATH.
  2. The name of the file containing the function is the same as the function name suffixed by .pro or .sav. The suffix should be in lowercase letters.

IDL does not search for files to compile or restore in runtime mode. When using the IDL Virtual Machine or any other runtime mechanism, all routines required by the application must either be restored when the application is initially loaded, or restored explicitly by the application code.

Note: IDL is case-insensitive. However, for some operating systems, IDL only checks for the lowercase filename based on the name of the procedure or function. We recommend that all filenames be lowercase letters.

Note: User-written functions must be defined before they are referenced, unless they meet the above conditions for automatic compilation, or the function name has been reserved by using the FORWARD_FUNCTION statement described below. This restriction is necessary in order to distinguish between function calls and subscripted variable references.

For more information on how to access routines, see Running Named Programs .

A Note on Files with Duplicate Names

If multiple .pro or .sav files with the same base name exist in the directories specified by the !PATH system variable, IDL will compile or restore the first file it finds, according to the following rules:

  1. IDL begins by searching in the current directory.
  2. If a .pro file whose base name matches the routine specified exists in the directory being searched, IDL compiles it, runs the routine, and stops searching.
  3. If a .sav file whose base name matches the routine specified exists in the directory being searched, IDL restores it, runs the routine, and stops searching.
  4. IDL proceeds to the first directory specified by the !PATH system variable and begins testing again with step 2. If no match is found, IDL proceeds to check each of the directories specified by the !PATH system variable in the order they appear in !PATH.
  5. If no file whose base name matches the routine specified is found in the directories specified by the !PATH system variable, IDL issues an Attempt to call undefined procedure/function error, and halts execution.

About Calling and Compiling Functions

Versions of IDL prior to version 5.0 used parentheses to indicate array subscripts. Because function calls use parentheses as well, the IDL compiler is not able to distinguish between arrays and functions by examining the statement syntax.

User-defined functions, with the exception of those contained in directories specified by the IDL system variable !PATH, must be compiled before the first reference to the function is encountered. This is necessary because the IDL compiler is unable to distinguish between a reference to a variable subscripted with parentheses and a call to a presently undefined user function with the same name. For example, in the statement:

A = XYZ(5)

it is impossible to tell by context alone if XYZ is an array or a function.

Note: In versions of IDL prior to version 5.0, parentheses were used to enclose array subscripts. While using parentheses to enclose array subscripts will continue to work as in previous version of IDL, we strongly suggest that you use brackets in all new code. See Array Subscript Syntax: [ ] vs. ( ) for additional details.

When IDL encounters references that may be either a function call or a subscripted variable, it searches the current directory, then the directories specified by !PATH, for files with names that match the unknown function or variable name. If one or more files matching the unknown name exist, IDL compiles them before attempting to evaluate the expression. If no function or variable with the given name exists, IDL displays an error message.

There are several ways to avoid this problem:

  • Compile the lowest-level functions (those that call no other functions) first, then higher-level functions, and finally procedures.
  • Place the function in a file with the same name as the function, and place that file in one of the directories specified by !PATH.
  • Use the FORWARD_FUNCTION definition statement to inform IDL that a given name refers to a function rather than a variable. See FORWARD_FUNCTION.
  • Manually compile all functions before any reference, or use RESOLVE_ROUTINE or RESOLVE_ALL to compile functions.