Declaration of functions and procedures Foundation

Functions and procedures are the most important structural elements of an Xbase++ program. Along with functions from the runtime library, new functions can be declared and are called user-defined functions (or "UDFs"), to conceptually distinguish them from the functions in the runtime library. Using the declarations FUNCTION or PROCEDUREan identifier is declared for the program section. This section of code is always executed when the corresponding identifier appears in program code. The program section for a UDF or procedure is terminated by a new FUNCTION or PROCEDURE declaration or by the end of the program file.

Procedures and UDFs are programmed in a similar manner. An identifier is declared and the program code for the procedure or function follows it. The difference between UDFs and procedures is that a UDF has a function value which is returned to the calling routine. This function value, or return value, must be specified within the UDF using the statement RETURN. The following lines show a comparison between procedures and functions:

FUNCTION MyFunc             PROCEDURE MyProc 
    Code                       Code 
RETURN value                RETURN 

The statement RETURN is not necessary for procedures, but it is a good programming practice to terminate the program code of procedures using this statement. No return value can be specified since procedures have no meaningful return value (more precisely: they always return the value NIL).

Xbase++ distinguishes between two kinds of UDFs and procedures: those that can be called in all files of a program and those that can be called only within the program file where they are declared. The ability to access procedures and UDFs is referred to as their visibility. When procedures and UDFs can only be called within the file in which they are declared, they have file-wide visibility. Otherwise they have global visibility and can be called in any program file.

UDFs and procedures with file-wide visibility are also referred to as static functions or procedures because they are declared using the keyword STATIC, as in STATIC FUNCTION and STATIC PROCEDURE. UDFs and procedures should always be declared as STATIC when they are called from only one single program file. This has the advantage that the identifier for the UDF or procedure can be redefined repeatedly in various files. Identifiers for globally visible functions and procedures can be defined only once in a program. The internal functionality of a program module can be hidden from other modules so that only a specifically defined subset of features is externally available.

Functions and procedures can receive values that are processed within the program code of the function or procedure. After the call to the UDF or procedure, these values are assigned to variables which must be specified within the declaration. The variables receiving these values are referred to as formal parameters. The passed values are called arguments. The following example illustrates the difference between parameters and arguments:

PROCEDURE Main                     // declare procedure 

   nVal1  = 100 
   nVal2  =   2 
   nResult= Divide( nVal1, nVal2 ) // pass arguments 
                                   // to function 

   ? nResult                       // result: 50 

RETURN 

FUNCTION Divide( x, y )            // function with parameters 

RETURN IIf( y==0, 0, x/y )         // code and return value 
                                   // on one line 

The function Divide() is called from the procedure Main. Within the () parentheses, the two arguments nVal1 and nVal2 are passed to the function. The function Divide() has two parameters x and y which receive the values of the arguments. The program code and assignment of the return value of the function appear on a single line. The functionDivide() returns the value 0 (zero) if division by zero is attempted.

When a UDF or a procedure can receive parameters, the identifiers for the parameters are generally specified in parentheses within the declaration. When so specified, the parameters are treated as LOCAL variables. The declaration of parameters can also occur using the keyword PARAMETERS. In this case, the parameters are treated as variables of the PRIVATE storage class. The function Divide()could also be programmed as follows:

FUNCTION Divide                    // declare function 
PARAMETERS x, y                    // declare parameters 

RETURN IIf( y==0, 0, x/y )         // code and return value 
                                   // on one line 

Parameters should be specified in parentheses within the FUNCTIONor PROCEDURE declaration. This allows the reference to the parameters to be resolved at compile time since they are lexical variables. The parameters declared using the keyword PARAMETERS are dynamic variables first created when the UDF or procedure is called (see the following section about declaring variables).