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
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,
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.
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.
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)