FUNCTION [core language]

Defines a function in a program file including variables to represent parameters passed to the function.

Syntax

FUNCTION <function name>[ ( [<parameter list>] ) ]
[<statements>]

The name of the function. Although dBASE Plus imposes no limit to the length of function names, it recognizes only the first 32 characters.

(<parameter list>)

Variable names to assign to data items (or parameters) passed to the function by the statement that called it. The variables in <parameter list> are local in scope, protecting them from modification in lower-level subroutines. For more information about the local scope, see LOCAL.

Any statements that you want the function to execute. You can call functions recursively.

Description

Use functions to create code modules. By putting commonly used code in a function, you can easily call it whenever needed, pass parameters to the function, and optionally return a value. You also create more modular code, which is easier to debug and maintain.

When a FUNCTION is defined inside a CLASS definition, the FUNCTION is considered a method of that CLASS. You cannot nest functions.

The keywords FUNCTION and PROCEDURE are interchangable in dBASE Plus.

A single program file can contain a total of 184 functions and methods. Each class also counts as one function (for the class constructor). To access more functions simultaneously, use SET PROCEDURE...ADDITIVE. The maximum size of a function is limited to the maximum size of a program file.

When a function is called via an object, usually as a method or event handler, the variable this refers to the object that called the function.

Function naming restrictions

Do not give a function the same name as the file in which it’s contained. Statements at the beginning of the file, before any FUNCTION, PROCEDURE, or CLASS statement, are considered to be a function (not counted against the total limit) with the same name as the file. (This function is sometimes referred to as the "main" procedure in the program file.) Multiple functions with the same name do not cause an error, but the first function with that name is the only one that is ever called.

Don't give the function the same name as a built-in dBL function. You cannot call such a function with the DO command, and if you call the function with the call operator (parentheses), dBASE Plus always executes its built-in function instead.

Also do not give the function a name that matches a dBL command keyword. For example, you should not name a function OTHER( ) because that matches the beginning of the keyword OTHERWISE. When you call the OTHER( ) function, the compiler will think it’s the OTHERWISE keyword and will generate an error, unless you happen to be in a DO CASE block, in which case it will be treated like the OTHERWISE keyword, instead of calling the function.

These function naming restrictions do not apply to methods, because calling a method through the dot or scope resolution operator clearly indicates what is being called. However, you may run into problems calling methods inside a WITH block. See WITH for details.

Making procedures available

You can include a procedure in the program file that uses it, or place it in a separate program file you access with SET PROCEDURE or SET LIBRARY. If you include a procedure in the program file that uses it, you should place it at the end of the file and group it with other procedures.

When you call a procedure, dBASE Plus searches for it in the search path in search order. If there is more than one procedure available with the same name, dBASE Plus runs the first one it finds. For this reason, avoid using the same name for more than one procedure. See the description of DO for an explanation of the search path and order dBASE Plus uses.