FUNCTION statement

Syntax

FUNCTION [name] [ ( [MAT] variable [ , [MAT] variable ...] ) ]

Description

Use the FUNCTION statement to identify a user-written function and to specify the number and names of the arguments to be passed to it. The FUNCTION statement must be the first line that is not a comment within the user-written function. A user-written function can contain only one FUNCTION statement.

name is specified for documentation purposes; it need not be the same as the function name or the name used to reference the function in the calling program. name can be any valid variable name.

variable is an expression that passes values between the calling programs and the function. variables are the formal parameters of the user-written function. When actual parameters are specified as arguments to a user-written function, the actual parameters are referenced by the formal parameters so that calculations performed in the user-written function use the actual parameters.

Separate variables by commas. Up to 254 variables can be passed to a user-written function. To pass an array, you must precede the array name with the keyword MAT. When a user-written function is called, the calling function must specify the same number of variables as are specified in the FUNCTION statement.

An extra variable is hidden so that the user-written function can use it to return a value. An extra variable is retained by the user-written function so that a value is returned by the RETURN statement (value) statement. This extra variable is reported by the MAP and MAKE.MAP.FILE commands. If you use the RETURN statement in a user-written function and you do not specify a value to return, an empty string is returned by default.

The program that calls a user-written function must contain a DEFFUN statement that defines the user-written function before it uses it. The user-written function must be cataloged in either a local catalog or the system catalog, or it must be a record in the same object file as the calling program.

If the user-defined function recursively calls itself within the function, a DEFFUN statement must precede it in the user-written function.

Examples

The following user-defined function SHORT compares the length of two arguments and returns the shorter:

FUNCTION SHORT(A,B)
AL = LEN(A)
BL = LEN(B)
IF AL < BL THEN RESULT = A ELSE RESULT = B
RETURN(RESULT)

The following example defines a function called MYFUNC with the arguments or formal parameters A, B, and C. It is followed by an example of the DEFFUN statement declaring and using the MYFUNC function. The actual parameters held in X, Y, and Z are referenced by the formal parameters A, B, and C so that the value assigned to T can be calculated.

FUNCTION MYFUNC(A, B, C)
Z = ...
RETURN (Z)
   .
   .
   .
END

DEFFUN MYFUNC(X, Y, Z)
T = MYFUNC(X, Y, Z)
END