Defining a Function

A function is a program unit containing one or more IDL statements that returns a value. This unit executes independently of its caller. It has its own local variables and execution environment. Once a function has been defined, references to the function cause the program unit to be executed. All functions return a function value which is given as a parameter in the RETURN statement used to exit the function. Function names can be up to 128 characters long.

The general format of a function definition is as follows:

FUNCTION Name, Parameter1, ..., Parametern 
    Statement1 
    Statement2 
    ... 
    ... 
    RETURN, Expression 
END 

Example

To define a function called AVERAGE, which returns the average value of an array, use the following statements:

FUNCTION AVERAGE, arr 
    RETURN, TOTAL(arr)/N_ELEMENTS(arr) 
END 

Once the function AVERAGE has been defined, it is executed by entering the function name followed by its arguments enclosed in parentheses. Assuming the variable X contains an array, the statement,

PRINT, AVERAGE(X^2) 

squares the array X, passes this result to the AVERAGE function, and prints the result. Parameters passed to functions are identified by their position or by a keyword. See Using Keyword Parameters.

Automatic Execution

IDL automatically compiles and executes a user-written function or procedure when it is first referenced if:

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

Forward Function Definition

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.

This problem has been addressed beginning with IDL version 5.0 by the use of square brackets "[ ]" instead of parentheses to specify array subscripts. See Array Subscript Syntax: [ ] vs. ( ) for a discussion of the IDL version 5.0 and later syntax. However, because parentheses are still allowed in array subscripting statements, the need for a mechanism by which the programmer can "reserve" a name for a function that has not yet been defined remains. The FORWARD_FUNCTION statement addresses this need.

As mentioned above, ambiguities can arise between function calls and array references when a function has not yet been compiled, or there is no file with the same name as the function found in the IDL path.

For example, attempting to compile the IDL statement:

A = xyz(1, COLOR=1) 

will cause an error if the user-written function XYZ has not been compiled and the filename xyz.pro is not found in the IDL path. IDL reports a syntax error, because xyz is interpreted as an array variable instead of a function name.

This problem can be eliminated by using the FORWARD_FUNCTION statement. This statement has the following syntax:

FORWARD_FUNCTION Name1, Name2, ..., NameN 

where Name is the name of a function that has not yet been compiled. Any names declared as forward-defined functions will be interpreted as functions (instead of as variable names) for the duration of the IDL session.

For example, we can resolve the ambiguity in the previous example by adding a FORWARD_FUNCTION definition:

;Define XYZ as the name of a function that has not yet been  
;compiled. 
FORWARD_FUNCTION XYZ 
 
;IDL now understands this statement to be a function call instead  
;of a bad variable reference. 
a = XYZ(1, COLOR=1)