FUNCTION Statement

Identifies a DataBasic module as an external function that can be called by other DataBasic programs.

Syntax

FUNCTION {name}({parameterList})

Syntax Elements

Comments

An external function must contain a FUNCTION statement, a RETURN statement that specifies the value to return, and (preferably) an END statement. Except for comments, $OPTIONS and INCLUDE statements, FUNCTION must be the first statement in the program.

An external function must be declared with a DEFFUN statement before it can be used. It is then executed in the same way as an intrinsic function; that is, its returned value must be used in some way (it cannot be executed with the CALL statement). The number and types of parameters passed to the function must match those declared in the FUNCTION and DEFFUN statements. If there is a mismatch, an error message is displayed and the program enters the debugger.

External functions must be cataloged (see the CATALOG command for details). It is recommended that you also catalog the calling program, because this will make your program more efficient.

The ENTER and CHAIN statements cannot be used to execute external functions. Nor can external functions be executed from TCL.

You cannot use the ENTER statement to run another program from within a function.

Passing Data

Data can be passed from the calling program to the function and back again through:

• The parameters in the argument list.

• COMMON variables.

It is strongly recommended that you do not use the same name for more than one parameter, whether passed in the argument list or in COMMON variables.

Internal Subroutines

An external function can contain internal subroutines (each starting with a statement label and ending with a RETURN statement) called with GOSUB or ON GOSUB statements. If a RETURN is encountered for which there is no corresponding GOSUB or ON GOSUB statement, the function returns.

Program Termination

If a STOP or CHAIN statement is executed before the function's END statement, control never returns to the calling program.

Precision

A calling program and the corresponding function do not need to have the same precision. When a value is passed back to the calling program, the value retains the precision used in the function (until an operation is performed that changes its precision, as defined in the description of the PRECISION statement).

Examples

XOR Function

In the item XOR:

**************************************
* Function XOR
*
* Returns the result of performing an XOR operation on two Boolean values.
*
**************************************
FUNCTION XOR(B1, B2)
   RETURN((B1 AND NOT(B2)) OR (B2 AND NOT(B1))
END

In the item XORPROG:

* Declare the XOR function.
DEFFUN XOR(BOOL1, BOOL2)
.
.
.
BLN1 = @TRUE
BLN2 = @FALSE
* Call the XOR function.
XORVAR = XOR(BLN1, BLN2)

The latter program fragment calls the XOR function to perform an exclusive OR on the Boolean values held in variables BLN1 and BLN2 and sets the variable XORVAR to the result.

FUNCTION ADD (X, Y)

DEFFUN ADD(X, Y)
.
.
.
NEWVAL = ADD (A+2, 395)

Function ADD is passed two parameters. On return to the calling routine, the result is assigned to variable NEWVAL.

FUNCTION ARYFUN(MAT ARY, INDEX)
   DIM ARY(10)

DEFFUN ARYFUN(MAT ARY, INDEX)
DIM MYDATA(10)
.
.
.
RESULT = ARYFUN(MAT MYDATA, ELEMENT)

Function ARYFUN accepts and returns two values, the first of which must be a dimensioned array with 10 elements.

See Also

DEFFUN statement, SUBROUTINE statement, RETURN statement, PROGRAM statement.