Statement/Function

Syntax

[result =] FN functionName[(param1 [,param2 ...])]

Description

Executes the user function specified by functionName, and optionally returns a numeric or string result. The user function must be one which was defined or prototyped at an earlier location in the program. A user function is defined using LOCAL FN, LONG FN or DEF FN <expr> statement. A user function is prototyped using the DEF FN <protoType> statement.

If the user function returns a value, you can use FN <userFunction> as part of a numeric or string expression, as in this example:

count% = 3 * FN NumFish%(x) + 7

If the user function does not return a value, then you should use FN <userFunction> as a standalone statement.

If the function definition includes a list of parameters, then you must provide the same number of parameters (in param1, param2, etc.) when you call the function, and the parameters that you pass must be of compatible types. The compatible types are summarized here (not all of these are available for all kinds of functions; see the individual descriptions of LOCAL FN, LONG FN

<spacer size="3" type="horizontal">and DEF FN <expr>):

<img src="f/fn%20userfunction.jpg" alt="" height="327" width="554" border="0">

Notes:

1. Non-integer values are rounded to integers before being moved into integer or pointer variables.
2. If you pass a numeric value that's outside the range of the formal variable type, you may get an unexpected result, or you may get an overflow error.
3. If you pass a string value that is longer than the maximum size of the formal variable, the string will be truncated.
4. If you specify a variable here, the variable's address will be copied into the formal parameter (addr& or p). If you specify a long-integer expression preceded by "=", then the value of that expression is copied into addr& or p.
5. The array must be a numeric or string array (not an array of records). All of the array's elements are accessible to the function. Any changes that are made to the array's elements within the function will also affect the array outside of the function. Note that if the array specified in the formal FN definition has a different type or different dimensions from the array you pass when you call the function, you may get unexpected results, or even a crash. (Be sure you know what you're doing before you try this!)
6. If you specify a record variable here, the record's address will be copied into the formal parameter (p). If you specify a long-integer expression, then the value of that expression is copied into p.

If the function definition does not have a list of parameters, then you must not include any parameters (nor parentheses) when you call the function.

In most cases, the parameters that you specify in FN <userFunction> are "passed by value." That means that the user function receives a private copy of the parameter's value; if the function changes that copy, it doesn't affect the value of the parameter that was used in the FN call.

In a few cases, the parameters that you specify in FN <userFunction> are "passed by reference." That means that the user function receives the address of the parameter that you specified. If the function changes the contents at that address, it will affect the value of the parameter you passed. Parameters are passed by reference when you use the following kinds of formal parameter declaractions in the function definition:

• pointer (p AS POINTER [TO someType]). (Parameter is passed by reference if you specify a record variable when you call the function.)
• address reference (@addr&; p AS POINTER [TO someType]). (Parameter is passed by reference if you specify a variable when you call the function.)
• array declaration (arr[suffix](dim1[,dim2...]))

You can also pass the address of a variable or array by using the VARPTR function (VARPTR(var) or @var) when you call the function (if you do this, then specify a long integer variable or a pointer variable as the formal parameter in the FN definition). This is another way to give the function direct access to the memory comprising the variable or array, allowing it possibly to change its value.
Note: that there is no way to pass the contents of a record directly to a function. To give the function access to a record's contents, either pass the record by reference, or pass the record's address directly (passing VARPTR(recVar) or @recVar when you call the function).

A FN <userFunction> call may appear anywhere below the place where the function is defined (or prototyped). It can appear in the "main" scope of the program, or inside other functions. It may even appear inside the very function that it is calling—this allows you to implement so-called "recursive" functions (functions which call themselves).

See Also

LOCAL FN; LONG FN; DEF FN