Named Programs: Procedures and Functions

Procedures and functions are collectively referred to as routines. Both are modular programs that can be run individually and called from other programs. A program can include multiple procedures and functions and call as many other programs as necessary.

Automatic Compilation

IDL automatically compiles code when you run a named routine; you do not need to manually compile beforehand. When several routines are saved in the same program file, all routines are compiled (given that the rules below are followed).

If a program calls different routines, whether they are in separate files or in the same file, all routines are compiled when the program is run.

IDL requires code to follow these conventions for automatic compilation:

File naming—a program file must be named the same as the main routine. For example, a program named myroutine.pro must contain a primary routine named myroutine.

Note
Routine names can be uppercase or lowercase except in UNIX, which requires file names to be lowercase.

Primary routine must be the last in the file— When you run a program, IDL compiles all routines in the file until it encounters the routine with the same name as the file. If any routines occur after that, they are not automatically compiled. For example, the program named myroutine.pro may contain multiple routines, but the main routine, myroutine, must be in the last position in the file.

Must be in IDL's path—Named programs must be saved in a directory that is in the IDL path, as defined by the !PATH system variable. (See About IDL's Path.)

Passing Data to a Routine: Arguments and Keywords

In IDL, data is passed to routines using parameters; arguments or keywords. Arguments are generally required and must be in a specified order, while keywords are often optional and can be in any order.

An argument is a positional parameter. They are called positional parameters because their position or order relative to the command name is significant. If a routine has positional arguments and you choose to use them, they must be in the correct order.

A keyword parameter is also referred to as a key-value pair, because it is written as a pair, one on each side of the equal sign. For example, keyword syntax is:

keyword = "value"

IDL recognizes a special keyword syntax using an initial slash character. Putting a slash in front of the keyword name is the same as setting the keyword equal to one. for example, the command CURSOR, X, Y, /NORMAL sets the cursor in a graphics program to return the cursor position in normalized coordinates.

Note that keyword names can be abbreviated to the shortest unambiguous string. For example, the keyword GEOMETRY could be abbreviated to GEO.

Note
Because keywords can be abbreviated, keywords within routines must have unique names that do not start with the name of another keyword from the same routine. For example, an error will result from using a keyword named mykeyword and another named mykeyword1.

The following example first defines the data in the variable D and issues a PLOT command that contains an argument and keywords:

For more information, see Parameters.

Program Files: One or Many?

An IDL program file can contain one or many routines, which can be a mix of procedures and functions. You can think of procedures and functions as modular units that are used together to build larger programs. Developers can choose whether to save the procedures and functions needed to build an application individually or to combine them in the same file. Reusing the same procedure or function for multiple programs can be a deciding factor in saving them separately.

How you structure your IDL programs is up to you. But before you start programming, consider how you want to set up your file structure. IDL allows you to save every routine as its own file or to combine multiple routines into one file.

Why save each routine separately?

If each routine will be used in multiple programs, you can reuse the routines with other routines. You may find it easier to find routines named individually.

Why combine routines into one file?

Save multiple routines in the same file if the routines are all used by the same program. Routines that call each other can be saved together, but IDL does not require it. You may find it easier to combine a series of routines that work together.

Note
This important rule applies when saving multiple routines in one file: The named procedure that is the same as the file name must be the last (final) routine in the file. You can see how this works in How a Procedure and Function Work Together.

Procedure

A procedure is a self-contained sequence of IDL statements that performs a well-defined task. A procedure contains a procedure definition statement (PRO <procedure_name>), where the procedure name is the name of the IDL statement you are creating. Parameters are named variables that are used in the scope of the procedure.

Use procedures when you are working on data "in place" or when no value is returned from the program. For example, a procedure could create a plot display on the screen but return no values back to IDL.

Diagram of a Procedure

The following diagram shows a simple IDL procedure, with all the elements explained.

Figure 7-4: Simple Procedure Example

When you run this procedure, the resulting plot and overplot display as:

Procedure Example

To see a simple procedure, open the indexedtorgb.pro file in IDL by typing .EDIT indexedtorgb at the IDL command line.

From the IDL menu, select Run → Compile indexedtorgb.pro, then select Run → Run indexedtorgb.

This procedure reads an image file, loads a color table, and indexes the colors to the red, green, and blue definitions from the color table. Then the image displays in a window.

Figure 7-5: Output of indexedtorgb procedure.

Take a look at the code for indexedtorgb.pro in IDL to understand the combination of commands that make up this procedure.

Function

A function is a self-contained sequence of IDL statements that performs a well-defined task and returns a value to the calling program unit when it is executed. All functions return a function value, which is given as a parameter in the RETURN statement that exits the function. A function is identified by a function definition statement (FUNCTION <function_name>), where the function name is the name of the IDL statement you are creating.

Use functions when you need easy access to a returned value, since functions create a new variable by default.

Diagram of a Function

The following diagram shows a simple IDL function, with all the elements explained.

Figure 7-6: Simple Function Example

This function does not run by itself, because it requires the argument who to be defined. The argument is defined in a procedure, HELLO_MAIN, illustrated in How a Procedure and Function Work Together.

How a Procedure and Function Work Together

The following example shows a simple procedure and function. Viewing them together, you can see their similarities and differences, and how they work together. The procedure, HELLO_MAIN, calls the function, HELLO_WHO to return the input of the command line after the PROMPT command asks the user to enter a name at the command line.

When you compile and run hello_main, the hello_who function is also compiled and run. The following lines appear in the IDL Console:

% Compiled module: HELLO_WHO. 
% Compiled module: HELLO_MAIN. 
 

Note

Notice that the hello_who function was compiled first, and the main routine, hello_main, was compiled last. In the example the hello_who function occurs in the file before the hello_main procedure. If the routines were in the opposite order, IDL would compile hello_main and then stop. The function hello_who would not be automatically compiled. (See Automatic Compilation.)

The command line displays a prompt for you to enter your name:

Type your name and press Enter. The function returns your name to the procedure and the Console displays the following: Hello Earnest