Compiling Your Program
Before a procedure or function can be executed, it must be compiled. When a system routine (a function or procedure built into IDL, such as iPLOT) is called, either from the command line or from another procedure, IDL already knows about this routine and compiles it automatically. When a user-defined function or procedure is called, IDL must find the routine and then compile it. Compilation can be either automatic or manual, as described below.
Warning
User-written functions must be defined before they are referenced, unless they:
1) Exist in the IDL !PATH.
2) Exist in a .pro file named the same as the function.
3) Are reserved using the FORWARD_FUNCTION statement.
This restriction is necessary in order to distinguish between function calls and subscripted variable references. See About Calling and Compiling Functions for details.
Automatic Compilation
When you enter the name of an uncompiled user-defined routine at the command line or call the routine from another routine, IDL searches the current directory for filename.pro, thenfilename.sav, where filename is the name of the specified routine. If no file is found in the current directory, IDL searches each directory specified by !PATH. (For more on the IDL path, see!PATH.)
If no file matching the routine name is found, IDL issues an error:
% Attempt to call undefined procedure/function: 'routine'
where routine is the name of the routine you specified.
If a file is found, IDL automatically compiles the contents of the file up to the routine whose name matches the name of the file (excluding the suffix), and then executes the routine. If the file does not contain the definition of a routine whose name matches the name of the file, IDL issues the same error as when the no file with the correct name is found.
For example, suppose a file named proc1.pro contains the following procedure definitions:
PRO proc1 PRINT, 'This is proc1' END PRO proc2 PRINT, 'This is proc2' END PRO proc3 PRINT, 'This is proc3' END
If you enter proc1 at the IDL command line, only the proc1 procedure will be compiled and executed. If you enter proc2 or proc3 at the command line, you will get an error informing you that you attempted to call an undefined procedure.
In general, the name of the IDL program file should be the same as the name of the last routine within the file. This last routine is usually the main routine, which calls all the other routines within the IDL program file (or, in the case of object classes, the class definition). Using this convention for your IDL program files ensures that all the related routines within the file are compiled before being called by the last main routine.
Program files within the IDL distribution use this formatting style. For example, open the program file for the XLOADCT procedure, xloadct.pro, in the IDL Editor. This file is in the lib/utilitiessubdirectory of the IDL distribution. This file contains several routines. The main routine (XLOADCT) is at the bottom of the file. When this file is compiled, the IDL Output Log notes all the routines within this file that are compiled:
IDL> .COMPILE XLOADCT % Compiled module: XLCT_PSAVE. % Compiled module: XLCT_ALERT_CALLER. % Compiled module: XLCT_SHOW. % Compiled module: XLCT_DRAW_CPS. % Compiled module: XLCT_TRANSFER. % Compiled module: XLOADCT_EVENT. % Compiled module: XLOADCT.
Note that the main XLOADCT procedure is compiled last.
Tip
When editing a program file containing multiple functions and/or procedures in the IDL Editor, you can easily move to the desired function or procedure by selecting its name from the Functions/Procedures Menu. See Navigating Among Procedures and Functions for more information.
Manual Compilation
There are several ways to manually compile a procedure or function.
Use the .COMPILE executive command at the IDL command line:
.COMPILE myFile
where myFile is the name of a .pro file located either in IDL's current working directory or in one of the directories specified by !PATH. All the routines included in the specified file will be compiled, but none will be executed automatically. If you are using the IDL Development Environment, the .pro file will also be opened in the IDL Editor.
If the file is open in the IDL Editor, select Run Compile or click the Compile button on the toolbar. All routines within the file will be compiled, but none will be executed automatically.
Use the .RUN or .RNEW executive command at the IDL command line:
.RUN myFile
where myFile is the name of a .pro file located either in IDL's current working directory or in one of the directories specified by !PATH. All the routines included in the specified file will be compiled, and any $MAIN$ level programs will be executed automatically. If you are using the IDL Development Environment, the .pro file will also be opened in the IDL Editor.
Use the .RUN, .RNEW, or .COMPILE executive command with no filename argument. Invoking any of these executive commands with no filename allows you to interactively create and compile a $MAIN$ level program. See Creating $MAIN$ Programs for additional details.
Note
Only .pro files can be compiled using the manual compilation mechanisms. Attempting to compile a SAVE (.sav) file using one of these mechanisms will result in an error.
In the "Hello World" example shown in Compiling Your Program, we have a user-defined procedure that contains a call to a user-defined function. If you enter the name of the user-defined procedure, hello_main, at the command line, IDL will compile and execute the hello_main procedure. After you provide the requested input, a call to the hello_who function is made. IDL searches forhello_who.pro, and compiles and executes the function.
Compilation Errors
If an error occurs during compilation, the error is reported in the Output Log of the IDLDE. For example, because the END statement is commented out, the following user-defined procedure will result in a compilation error:
PRO procedure_without_END PRINT, 'Hello World' ;END
When trying to compile this procedure (after saving it into a file namedprocedure_without_END.pro), you will receive the following error in the IDL Output Log:
IDL> .COMPILE procedure_without_END % End of file encountered before end of program. % 1 Compilation errors in module PROCEDURE_WITHOUT_END.
Note
Under Microsoft Windows, the IDL Editor window displays a red dot to the left of each line that contains an error.
Setting Compilation Options
The COMPILE_OPT statement allows you to give the IDL compiler information that changes some of the default rules for compiling the function or procedure within which the COMPILE_OPT statement appears. The syntax of COMPILE_OPT is as follows:
COMPILE_OPT opt1 [,opt2, ..., optn]
where optn is any of the available options documented in COMPILE_OPT. These options allow you to change default values of true and false, hide routines from HELP, and reserve the use of parentheses for functions. See COMPILE_OPT for complete details.
