Parameters: Arguments and Keywords

The variables and expressions passed to the function or procedure from its caller are parameters. Actual parameters are those appearing in the procedure call statement or the function reference. In the following,

; Call procedure with two parameters.

myproABC, A, 12

 

; Call function with one parameter. The result is stored

; in variable A.

A = myfuncXYZ(C/D)

the actual parameters in the procedure call are the variable A and the constant 12, while the actual parameter in the function call is the value of the expression (C/D).

Formal parameters are the variables declared in the procedure or function definition. The same procedure or function can be called using different actual parameters from a number of places in other program units.

The correspondence between the actual parameters of the caller and the formal parameters of the called procedure is established by position or by keyword.

Positional Parameters (Arguments)

A positional parameter, or plain argument, is a parameter without a keyword. Just as its name implies, the position of a positional parameter establishes the correspondence—the n-th formal positional parameter is matched with the n-th actual positional parameter.

Keyword Parameters

A keyword parameter, which can be either actual or formal, is an expression or variable name preceded by a keyword and an equal sign (“=”) that identifies which parameter is being passed.

When calling a routine with a keyword parameter, you can abbreviate the keyword to its shortest, unambiguous abbreviation.

Note: Because keyword names can be abbreviated, keywords within a routine must have unique names that do not contain 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 in the same routine.

Keyword parameters can also be specified by the caller with the syntax /KEYWORD, which is equivalent to setting the keyword parameter to 1 (e.g., KEYWORD = 1). The syntax /KEYWORD is often referred to, in the rest of this documentation, as setting the keyword.

For example, a procedure is defined with a keyword parameter named TEST.

PRO XYZ, A, B, TEST = T

The caller can supply a value for the formal (keyword) parameter T with the following calls:

; Supply only the value of T. A and B are undefined inside the

; procedure.

XYZ, TEST = A

 

; The value of A is copied to formal parameter T (note the

; abbreviation for TEST), Q to A, and R to B.

XYZ, TE = A, Q, R

 

; Variable Q is copied to formal parameter A. B and T are undefined

; inside the procedure.

XYZ, Q

result = FUNCTION(Arg1, Arg2, KEYWORD = value)

 

Note: When supplying keyword parameters for a function, keywords are specified inside the parentheses.

Copying Parameters

When a procedure or function is called, the actual parameters are copied into the formal parameters of the procedure or function and the module is executed.

On exit, via a RETURN statement, the formal parameters are copied back to the actual parameters, providing they were not expressions or constants. Parameters can be inputs to the program unit; they can be outputs in which the values are set or changed by the program unit; or they can be both inputs and outputs.

When a RETURN statement is encountered in the execution of a procedure or function, control is passed back to the caller immediately after the point of the call. In functions, the parameter of the RETURN statement is the result of the function.

Number of Parameters

A procedure or a function can be called with fewer arguments than were defined in the procedure or function. For example, if a procedure is defined with 10 parameters, the user or another procedure can call the procedure with 0 to 10 parameters.

Parameters that are not used in the actual argument list are set to be undefined upon entering the procedure or function. If values are stored by the called procedure into parameters not present in the calling statement, these values are discarded when the program unit exits. The number of actual parameters in the calling list can be found by using the system function N_PARAMS. Use the N_ELEMENTS function to determine if a variable is defined.

Determining Variable Scope

The ARG_PRESENT function returns TRUE if its parameter will be passed back to the caller. This function is useful in user-written procedures to determine if a created value remains within the scope of the calling routine. ARG_PRESENT helps the caller avoid expensive computations and prevents heap leaks. For example, assume that a procedure exists which depends upon an argument passed by the caller:

PRO pass_it, i

If the caller does not specify i, the program may not function properly. You can check to make sure that an argument was specified by using the following statement:

IF ARG_PRESENT(i) THEN BEGIN

Function Parameters Example

An example of an IDL function to compute the digital gradient of an image is shown in the example below. The digital gradient approximates the two-dimensional gradient of an image and emphasizes the edges.

This simple function consists of three lines corresponding to the three required components of IDL procedures and functions: the procedure or function declaration, the body of the procedure or function, and the terminating end statement.

FUNCTION GRAD, image

; Define a function called GRAD. Result is ABS(dz/dx) + ABS(dz/dy).

 

; Evaluate and return the result.

   RETURN, ABS(image - SHIFT(image, 1, 0)) + $

     ABS(image-SHIFT(image, 0, 1))

 

; End of function.

END

The function has one parameter called IMAGE. There are no local variables. Local variables are variables active only within a module (i.e., they are not parameters and are not contained in common blocks).

The result of the function is the value of the expression used as an argument to the RETURN statement. Once compiled, the function is called by referring to it in an expression. Two examples are shown below.

; Store gradient of B in A.

A = GRAD(B)

 

; Display gradient of IMAGE.

; Access image data and pass to GRAD function.

; Display the gradient.

file=FILEPATH('endocell.jpg', SUBDIRECTORY=['examples','data'])

READ_JPEG, file, image, /GRAYSCALE

result=GRAD(image)

IIMAGE, result