function

FUNCTION

Syntax

FUNCTION [ BACKGROUND ] Function_Name [ as Return_Type ] ( [ [ BYREF ] Parameter1 [ AS Type1 | = Default_Value1 ] [, [ BYREF ] Parameter2 [ AS Type2 | = Default_Value2 ] [, ... [, [ BYREF ] ParameterN [ AS TypeN | = Default_ValueN ]...]]] )
    [ statements ]
    [ Function_Name = Expression ]
    [ EXIT FUNCTION ]
END FUNCTION

Argument		Description
BACKGROUND	V6	Optional. Forces a function to run in the background.
Function_Name	V5	The name of the function. Function names should begin with a letter (A-Z, a-z) and may contain numbers and underscore (_) characters. Although the use of the period (.) character is not prohibited, it may not be supported in future releases of Alpha Five.
Return_Type	V5	Required. The data type of the returned variable. See Variable Data Types.
BYREF	V6	Optional. By default FUNCTION passes arguments by value (BYVAL). Use the BYREF keyword to have a function pass an argument by reference (e.g. pass its address).
Parameter1 ... ParameterN	V5	Optional. A constant, variable, or expression that passes a value to the function. Each Parameter must have an associated Type.
Default_Value1 ... Default_ValueN	V6	Optional. The value to use if the value is omitted in the function call. This syntax makes the argument optional.
Type1 ... TypeN	V5	Required for each Parameter. See Variable Data Types.

Description

FUNCTION is used to declare a user-defined function. A function declaration specifies the name of the function Function_Name, the type of value returned by the function ( Return_Type ) and the name ( Parameter1 ... ParameterN ) and type ( Type ), of values to be passed to the function, if any. The Return_Type is defined after the function name, and defaults to numeric (N) if no return type is specified.

The parameter type can be any Alpha Five variable type. Use the A type when the parameter you pass to the function may be one type in a certain instance and another type in another 'instance. Although function parameters are not required, a function can have one or more defined parameters. The functions parameter names and types are declared inside parentheses, separated by commas. The parameters type determines what type of value the function accepts. The declared parameters behave like local variables, remaining defined until the function execution is complete. The functions return value is established by assigning an expression value to the function name. The data type of this value must match the defined Return_Type.

By default parameters are passed by value (BYVAL). With Alpha Five version 6 it is possible to pass variables BYREF. This means that the receiving function can directly manipulate the variables of the calling function.

Variables declared inside a function remain local to that function unless they are declared with the dim SHARED or dim GLOBAL statement. When the function terminates local variables are destroyed. If the SHARED or GLOBAL variable does not already exist it is created in the function and remains after the function 'terminates. Function execution is terminated when any of the following commands are reached: EXIT FUNCTION, RETURN, end FUNCTION.

A script can have up to 64 user-defined functions. Functions can call other functions or the same function recursively up to 32 'times. A function defined within a script is a local function. It is only visible to that script. Alpha Five also supports global functions which can be used anywhere in Alpha Five. For information on global functions, see How to Define a Global Function.

Optional Function Arguments

Functions can be defined with optional parameters. Alpha Five infers the type of the argument based on the type of the default value.

Age = 0

Unknown = NULL_VALUE()

Note : An optional parameter cannot be followed by a required parameter in the parameter list.

Note the last example above where the argument, "Unknown", is given a default value of NULL_VALUE(). This indicates that the argument is optional, but its type is not known in advance.

function anything as C ( any = NULL_VALUE())

str = ""

str = str + any

anything = "Value = " + str

end function

? anything()-> "Value = 0"

? anything(1) -> "Value = 1"

? anything("Hello") -> "Value = Hello"

? anything({1/1/90}) -> "Value = 01/01/1990"

? anything(.T.) -> "Value = True"

function multiply as N (arg1 as N, arg2 as N)

multiply = arg1 * arg2

end function

function beep_a_lot as V (beep_num as N)

for i = 1 TO beep_num

ui_beep()

next i

end function

n = multiply(5,2)

trace.writeln(str(n))

beep_a_lot(n)

function AddNumbers as N (n1 as N, n2 = 0 as N, n3 = 0 as N)

AddNumbers = n1 + n2 + n3 + n4

end function

AddNumbers(2,3,4,5) à 14

AddNumbers(2,3) -> 5

The following function sets the default value of state to "MA":

function shipping_charge as N ( order_total as N, state = "MA", weight as N)

'type your code here

if (state = "MA") Then

shipping_charge = 0

else

shipping_charge = weight * 2.5

end if

end function