Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]

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.

Note
See Library Authoring for information on naming routines to avoid conflicts with IDL routine names. It is important to implement and consistently use a naming scheme from the earliest stages of code development.

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:

  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. Under UNIX, the suffix should be in lowercase letters.

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 named with lowercase.

Warning
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 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) 

Note
Declaring a function that will be merged into IDL via the LINKIMAGE command with the FORWARD_FUNCTION statement will not have the desired effect. Routines merged via LINKIMAGE are considered by IDL to be built-in routines, and thus need no compilation or declaration. They must, however, be merged with IDL before any routines that call them are compiled.


Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]