# 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.

## Syntax

**Internal Function Statement**

```
 *
 function function.name{(arg.list)}
 statements
 returning exp
```

 **External Function Statement**

```
 function {function.name}{(arg.list)}
	statements
 return return_value
```

## Parameter(s)

**Internal Function Statement**

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

 After the function has been defined, use the following format to call the function:

```
 @function.name ([arg.list])
```

 **External Function Statement**

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

## Description

**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.

 Note:

- 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(s)

**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"
 return
 Diff: Msg = "Diff"
 return
 ExitFunc:
 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
```

## See also

- [call statement](https://d3codex.com/pickbasic-flashbasic/call-statement/)
- [deffun statement](https://d3codex.com/pickbasic-flashbasic/deffun-statement/)
- [gosub statement](https://d3codex.com/pickbasic-flashbasic/gosub-statement/)
- [return statement](https://d3codex.com/pickbasic-flashbasic/return-statement/)
- [Statements and functions](https://d3codex.com/pickbasic-flashbasic/statements-and-functions/)

---
Source: https://d3codex.com/pickbasic-flashbasic/function-statement/ - part of the D3Codex reference.