function statement

User-defined functions can be defined within a program. They can be used like sub-routines invoked with gosub or called externally like sub-routines invoked with call.


Internal Function Statement

 returning exp

External Function Statement

 function {}{(arg.list)}
 return return_value


Internal Function Statement

arg.list Variables passed to the function. Name of internally defined function.

After the function has been defined, use the following format to call the function: ([arg.list])

External Function Statement

arg.list Variables to be assigned by the corresponding @function call. Name of external cataloged function.


Internal Function Statement

A user-defined function statement looks and acts much like an inline subroutine (invoked with gosub), except the return statement becomes "returning X ", where X is the value to return (return_value).

User-defined functions always return a single value and accept any number of input expressions. User-defined functions may not pass dimensioned arrays.

All variables used within the function are local to the function, and are not available to the external program. This private use of the variables allows standardized global libraries to be created and referenced by any program (via the include statement). Programmers need not be concerned about the variable names used in the function as they cannot conflict with the variables in the program, even if the names are the same.

  • Internal user-defined functions may not pass dimensioned arrays.
  • A comment MUST precede the function definition.
  • An internal function that has no input arguments must be invoked with empty parentheses.

    Example: X = @myfunction()

External Function Statement

A user-defined function statement looks, compiles, and catalogs like a callable subroutine, except the return statement becomes "return X", where X is the value to return (return_value).

BASIC provides the ability to call functions.
  • The function statement must appear on the first line of an external function invoked by a calling program.
  • As of D3 v10.3.1, external functions cannot be Flash-compiled. Therefore, the entire chain of calling programs must not be running in Flash mode.
  • The arg.list parameter must contain the same number of comma-delimited arguments as are used to invoke the function in the calling program.

An external function exits with a return statement and a return_value. Compare to an internal function, which exits with a returning statement and a return_value. This allows internal functions to be nested within an external function.

Additional Considerations

If the return statement does not specify a return variable (RETURN X), an empty string is returned.

When defining a subroutine as a function, the variable that you are populating with the result of the function is assigned to the return variable in the subroutine. Therefore, you should always use a different variable for the assignment and calling positions. For example: Y=MYSUB(X)

If the same variable is used for both the return value and the passed argument, any manipulation of either variable will affect the other. This is because an extra argument is added to the subroutine’s argument list to accommodate the return.

For example: If you call a function like this: X=MYFUNC(X), the subroutine is called like this: CALL MYSUB(X,X) This situation can cause unexpected results if changes are made to the variable within the subroutine.

All external functions must be cataloged prior to execution.

Unlike called subroutines, an external function definition does not return values through the arg.list.


Example 1

Internal function statement example:

 * Necessary comment
 function funcVolume(Height,Diameter)
     wVolume = Height * ( (Diameter/2) ^2 ) * 3.14
 returning wVolume
 Print “Volume of 6X2 cylinder is: “:@funcVolume(6,2)

 * program funcGosub
 crt "Function that does GOSUBs"
 * Necessary comment
 function funcgs(a,b)
   if a = b then gosub Same else gosub Diff
   go ExitFunc
 Same: Msg = "Same"
 Diff: Msg = "Diff"
   returning Msg
 print @funcgs(2,2)
 print @funcgs(2,3)

Example 2

External function statement example.

This example calls an external function that returns the volume of a cylinder:

 *program main
 deffun funcVolume(Height,Diameter) ;* This statement is optional
 Volume = funcVolume(6,2)
 Print “Volume of the cylinder is “:Volume

Here is the external function:

 function funcVolume(Height,Diameter)
 wVolume = Height * ( (Diameter/2) ^2 ) * 3.14
 return wVolume