Procedures and Functions

New procedures and functions can be written in PV‑WAVE and called in the same manner as system-defined procedures or functions (i.e., from the keyboard or from other programs).

PV‑WAVE automatically compiles and executes a user-written function or procedure when it is first referenced if:

The name of the file containing the routine is the same as the routine name suffixed by .pro.

The source code of the routine is in the current working directory or in a directory in the search path defined by the system variable !Path.

 

Note	It is recommended that you compile user-written functions before they are referenced, unless they meet the above conditions for automatic compilation. This restriction is necessary in order to distinguish between function calls and subscripted variable references.

A procedure is called by a procedure call statement, while a function is called via a function reference. A function always returns an explicit result. For example, if ABC is a procedure and XYZ is a function:

; Calls procedure ABC with two parameters.

ABC, A, 12

; Calls function XYZ with one parameter. The result of XYZ is 

; stored in variable A.

A = XYZ(C/D)

Procedure or Function Execution Sequence

When a user-written procedure or function is called, the following actions take place:

All of the actual arguments in the user procedure call list are evaluated and saved in a temporary location.

The actual parameters saved are substituted for the formal parameters given in the definition of the called procedure. All other variables local to the called procedure are set to UNDEFINED.

The procedure is executed until a RETURN or RETALL statement is encountered or the end of the code is reached. The result of a user-written function is passed back to the caller by specifying it as the parameter of a RETURN statement. RETURN statements in procedures may not have parameters.

All local variables in the procedure (i.e., those variables that are neither parameters nor common variables) are deleted.

The new values of the parameters that were passed by reference are copied back into the corresponding variables. Actual parameters that were passed by value are deleted.

Control resumes in the calling procedure after the procedure call statement or function reference.

Recursion

Recursion is supported with both procedures and functions.

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 previous examples, the parameters in the procedure call are the variable A and the constant 12, while the parameter in the function 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, p₁, p₂, ..., pn

FUNCTION Function_name, p₁, p₂, ..., 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.

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 can 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) can 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 can be found by using the system function N_PARAMS. Use the N_ELEMENTS or SIZE functions to determine if a variable is defined or not. The functions KEYWORD_SET and PARAM_PRESENT can be used to determine if parameters were used in a function or procedure call.

Parameter Passing Mechanism

Parameters are passed to system and user-written procedures and functions by value or by reference. It is important that you recognize the distinction between these two methods.

Expressions, constants, system variables, and subscripted variable references are passed by value.

Variables are passed by reference.

Parameters passed by value can only be inputs to program units; results cannot be passed back to the caller via these parameters. Parameters passed by reference can convey information in either or both directions. For example consider this trivial procedure:

PRO ADD, A, B

A = A + B

RETURN

END

This procedure adds its second parameter to the first, returning the result in the first. The call:

ADD, A, 4

adds 4 to A and stores the result in variable A. The first parameter is passed by reference and the second parameter, a constant is passed by value. The call:

ADD, 4, A

does nothing because a value may not be stored in the constant “4” which was passed by value. No error message is issued.

Similarly, if ARR is an array, the call:

ADD, ARR(5), 4

does not achieve the desired effect (adding 4 to element ARR (5)) because subscripted variables are passed by value. A possible alternative is:

TEMP = ARR(5) 

ADD, TEMP, 4

ARR(5) = TEMP