Environment > Using Procedures, Functions, SAVE Files > Defining a Procedure

# Defining a Procedure

A sequence of one or more IDL statements can be given a name, compiled, and saved for future use with the procedure definition statement. Once a procedure has been successfully compiled, it can be executed using a procedure call statement interactively from the terminal, from a main program, or from another procedure or function.

The general format for the definition of a procedure is as follows:

PRO Name, Parameter1, ..., Parametern

; Statements defining procedure.

Statement1

Statement2

...

; End of procedure definition.

END

The PRO statement must be the first line in a user-written IDL procedure.

Calling a user-written procedure that is in a directory in the IDL search path (!PATH) and has the same name as the prefix of the `.sav` or `.pro` file, causes the procedure to be read from the disk, compiled, and executed without interrupting program execution.

## Calling a Procedure

The syntax of the procedure call statement is as follows:

Procedure_Name, Parameter1, Parameter2, ..., Parametern

The procedure call statement invokes a system, user-written, or externally-defined procedure. The parameters that follow the procedure’s name are passed to the procedure. When the called procedure finishes, control resumes at the statement following the procedure call statement. Procedure names can be up to 128 characters long.

Procedures can come from the following sources:

- System procedures provided with IDL.
- User-written procedures written in IDL and compiled with the .RUN command.
- User-written procedures that are compiled automatically because they reside in directories in the search path. These procedures are compiled the first time they are used.
- Procedures written in IDL, that are included with the IDL distribution, located in directories that are specified in the search path.
- Under many operating systems, user-written system procedures coded in FORTRAN, C, or any language that follows the standard calling conventions, which have been dynamically linked with IDL using the LINKIMAGE or CALL_EXTERNAL procedures.

## Procedure Examples

Some procedures can be called without any parameters. For example:

IPLOT

This is a procedure call to launch the iPlot iTool. There are no explicit inputs or outputs. You can also call iPlot with parameters including data and color specifications:

data = RANDOMU(Seed,45)

IPLOT, data, COLOR=[255,0,0]

This opens the iPlot tool and passes it random plot data. The `data` parameter is an argument and the COLOR parameter is a keyword. These elements are described in more detail in Parameters.

You can also create a named program consisting of a procedure. For example, suppose you have a file called `hello_world.pro` containing the following code:

PRO hello_world

PRINT, 'Hello World'

END

This IDL “program” consists of a single user-defined procedure.

IDL program files are assumed to have the extension `.pro` or the extension `.sav`. When IDL searches for a user-defined procedure or function, it searches for files consisting of the name of the procedure or function, followed by the `.pro` or `.sav` extension. Procedures and functions can also accept arguments and keywords. Both arguments and keywords allow the program that calls the routine to pass data in the form of IDL variables or expressions to the routine.

For example, the previous user-defined procedure could be changed to include an argument and a keyword:

PRO hello_world, name, INCLUDE_NAME = include

IF (KEYWORD_SET(include) && (N_ELEMENTS(name) NE 0)) THEN BEGIN

PRINT, 'Hello World From '+ name

ENDIF ELSE PRINT, 'Hello World'

END

Now if the INCLUDE_NAME keyword is set to a value greater than zero, the above procedure will include the string contained within the `name` variable if a value was supplied for the name argument. Enter the following procedure call at the command line:

hello_world, name, /INCLUDE_NAME

IDL prints,

Hello World

Now define a string name and repeat the procedure call:

name = "Horton"

hello_world, name, /INCLUDE_NAME

IDL prints:

Hello World From Horton

This example uses the KEYWORD_SET and N_ELEMENTS functions in order to handle the possibility of missing information in a procedure or function call. See Determining if a Keyword is Setfor more information.