Procedure and Function Parameters

Programmer Guide > Writing Procedures and Functions > Procedure and Function Parameters

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

The procedure and function definition statements notify the compiler that a user-written program module follows. The syntax of these definition statements is:

PRO Procedure_name, p1, p2, ..., pn

FUNCTION Function_name, p1, p2, ..., pn

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

Correspondence Between Formal and Actual Parameters

Correspondence between the caller’s actual parameters and the called procedure’s formal parameters is established by position or by keyword.

A keyword parameter, which may 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 procedure with a keyword parameter, you can abbreviate the keyword to its shortest unambiguous abbreviation. Keyword parameters may also be specified by the caller with the syntax /Keyword, which is equivalent to setting the keyword parameter to 1 (e.g., Keyword = 1).

note	Because PV-WAVE allows users to abbreviate keywords to the shortest unambiguous use, when adding new keywords, make sure the new keywords could not be considered abbreviations of longer keywords. For example, PV-WAVE would view Replace and ReplaceAll as ambiguous keywords.

A positional parameter is a parameter without a keyword. Just as its name implies, the position of positional parameters establishes the correspondence. The nth formal positional parameter is matched with the nth actual positional parameter.

note	Do not use reserved words for keywords. If you use a reserved word as a keyword, a syntax error will result. For a list of the reserved words in PV‑WAVE, see "Names of Variables".

Example of Using Positional and Keyword Parameters

A procedure is defined with a keyword parameter named Test:

PRO XYZ, A, B, Test = T

The caller can supply a value for the format parameter T with the calls:

XYZ, Test = A

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

; procedure.

XYZ, Te = A, Q, R

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

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

XYZ, Q

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

; undefined inside the procedure.

Copying Actual Parameters into Formal 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 if they were not expressions or constants. Parameters may be inputs to the program unit; or they may be outputs in which the values are set or changed by the program unit; or they may 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 Required in Call

A procedure or a function may be called with less arguments than were defined in the procedure or function. For example, if a procedure is defined with ten parameters, the user (or another procedure) may call the procedure with zero to ten parameters.

Parameters that are not used in the actual argument list are set to be undefined upon procedure or function entry. 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 may be found by using the system function N_PARAMS. Use the N_ELEMENTS function to determine if a variable is defined or not. The functions KEYWORD_SET and PARAM_PRESENT can be used to determine if parameters are used or not in a function or procedure call.

Example of a Function

An example of a function to compute the digital gradient of an image is shown 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 procedures and functions: 1) the procedure or function declaration, 2) the body of the procedure or function, and 3) the terminating END statement.

FUNCTION GRAD, IMAGE

; Defines a function called GRAD.

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

; Evaluates and returns the result. Result = abs (dz/dx) + abs

; (dz/dy) which is the sum of the absolute values of the

; derivative in the x and y directions.

END

; End of function.

The function has one parameter called IMAGE. There are no local variables. (Local variables are variables within a module that are not parameters and are not contained in Common Blocks.)

The result of the function is the value of the expression appearing after the RETURN statement. Once compiled, the function is called by referring to it in an expression. Some examples might be:

A = GRAD(B)

; Store gradient of B in A.

TVSCL, GRAD(ABC + DEF)

; Display gradient of image sum.

Example Using Keyword Parameters

A short example of a function that exchanges two columns of a 4-by-4 homogeneous coordinate transformation matrix is shown. The function has one positional parameter, the coordinate transformation matrix, T. The caller can specify one of the keywords XYexch, XZexch, or YZexch, to interchange the XY, XZ, or YZ axes of the matrix. The result of the function is the new coordinate transformation matrix:

FUNCTION SWAP, T, XYEXCH = XY, $
XZEXCH = XZ, YZEXCH = YZ

; Function to swap columns of T. If XYEXCH is specified swap

; columns 0 and 1, XZEXCH swaps 0 and 2, and YZEXCH

; swaps 1 and 2.

IF KEYWORD_SET(XY) THEN S = [0, 1]

; Swap columns 0 and 1?

ELSE IF KEYWORD_SET(XZ) THEN S = [0, 2]

; XZ set?

ELSE IF KEYWORD_SET(YZ) THEN S = [1, 2]

; YZ set?

ELSE RETURN, T

; Nothing is set, just return.

R = T

; Copy matrix for result.

R(S(1), 0) = T(S(0), *)

R(S(0), 0) = T(S(1), *)

; Exchange two columns using matrix insertion operators and

; subscript ranges.

RETURN, R

; Return result.

END

Typical calls to SWAP are:

Q = SWAP(!P.T, /XYexch)

Q = SWAP(Q, /XYexch)

Q = SWAP(INVERT(Z), YZexch = 1)

Q = SWAP(Z, XYexch = I EQ 0, YZexch = I EQ 2)

The last example sets one of the three keywords, according to the value of the variable I.

This function example uses the system function KEYWORD_SET to determine if a keyword parameter has been passed and it is non-zero. This is similar to using the condition

IF N_ELEMENTS(P) NE 0 THEN IF P THEN ... ...

to test if keywords that have a true/false value are both present and true.

note	Use the PARAM_PRESENT function in conjunction with KEYWORD_SET to test if a keyword was actually used in a function or procedure call. For information on PARAM_PRESENT, see the PV‑WAVE Reference.

Version 2017.0