Syntax

[Private | Public] [Static] Function name[(arglist)] [As ReturnType]
  [statements]
End Sub

where arglist is a comma-separated list of the following (up to 30 arguments are allowed):

[Optional] [ByVal | ByRef] parameter [()] [As type]

Description

Creates a user-defined function.

Comments

The Function statement has the following parts:

Part

Description

Private

Indicates that the function being defined cannot be called from other scripts.

Public

Indicates that the function being defined can be called from other scripts. If both the Private and Public keywords are missing, then Public is assumed.

Static

Recognized by the compiler but currently has no effect.

Name

Name of the function, which must follow Basic Control Engine naming conventions: 

1. Must start with a letter.

2. May contain letters, digits, and the underscore character (_). Punctuation and type-declaration characters are not allowed.

The exclamation point (!) can appear within the name as long as it is not the last character, in which case it is interpreted as a type-declaration character.

3. Must not exceed 80 characters in length.

Additionally, the name parameter can end with an optional type-declaration character specifying the type of data returned by the function (that is, any of the following characters: %, &, !, #, @).

Optional

Keyword indicating that the parameter is optional. All optional parameters must be of type Variant. Furthermore, all parameters that follow the first optional parameter must also be optional.

If this keyword is omitted, then the parameter is required.

Note: You can use the IsMissing function to determine if an optional parameter was actually passed by the caller.

ByVal

Keyword indicating that parameter is passed by value.

ByRef

Keyword indicating that parameter is passed by reference. If neither the ByVal nor the ByRef keyword is given, then ByRef is assumed.

Parameter

Name of the parameter, which must follow the same naming conventions as those used by variables. This name can include a type-declaration character, appearing in place of As type.

Type

Type of the parameter (for example, Integer, String, and so on). Arrays are indicated with parentheses. For example, an array of integers would be declared as follows:

 Function Test(a() As Integer)
 End Function

ReturnType

Type of data returned by the function. If the return type is not given, then Variant is assumed. The ReturnType can only be specified if the function name (i.e., the name parameter) does not contain an explicit type-declaration character.

A function returns to the caller when either of the following statements is encountered:

  End Function
  Exit Function

Functions can be recursive.

Returning Values from Functions

To assign a return value, an expression must be assigned to the name of the function, as shown below:

  Function TimesTwo(a As Integer) As Integer
    TimesTwo = a * 2
  End Function

If no assignment is encountered before the function exits, then one of the following values is returned:

Value

Data Type Returned by the Function

0

Integer, Long, Single, Double, Currency

Zero-length string

String

Nothing

Object (or any data object)

Empty

Variant

December 30, 1899

Date

False

Boolean

The type of the return value is determined by the As ReturnType clause on the Function statement itself. As an alternative, a type-declaration character can be added to the Function name. For example, the following two definitions of Test both return String values:

  Function Test() As String
    Test = "Hello, world"
  End Function

  Function Test$()
    Test = "Hello, world"
  End Function

Passing Parameters to Functions

Parameters are passed to a function either by value or by reference, depending on the declaration of that parameter in arglist. If the parameter is declared using the ByRef keyword, then any modifications to that passed parameter within the function change the value of that variable in the caller. If the parameter is declared using the ByVal keyword, then the value of that variable cannot be changed in the called function. If neither the ByRef or ByVal keywords are specified, then the parameter is passed by reference.

You can override passing a parameter by reference by enclosing that parameter within parentheses. For instance, the following example passes the variable j by reference, regardless of how the third parameter is declared in the arglist of UserFunction:

 i = UserFunction(10,12,(j))

Optional Parameters

The Basic Control Engine allows you to skip parameters when calling functions, as shown in the following example:

  Function Test(a%,b%,c%) As Variant
  End Function

  Sub Main
    a = Test(1,,4)  'Parameter 2 was skipped.
  End Sub

You can skip any parameter with the following restrictions:

1. The call cannot end with a comma. For instance, using the above example, the following is not valid:

    a = Test(1,,)

2. The call must contain the minimum number of parameters as required by the called function. For instance, using the above example, the following are invalid:

    a = Test(,1)    'Only passes two out of three required parameters.
    a = Test(1,2)    'Only passes two out of three required parameters.

When you skip a parameter in this manner, the Basic Control Engine creates a temporary variable and passes this variable instead. The value of this temporary variable depends on the data type of the corresponding parameter in the argument list of the called function, as described in the following table:

Value

Data Type

0

Integer, Long, Single, Double, Currency

Zero-length string

String

Nothing

Object (or any data object)

Error

Variant

December 30, 1899

Date

False

Boolean

Within the called function, you will be unable to determine if a parameter was skipped unless the parameter was declared as a variant in the argument list of the function. In this case, you can use the IsMissing function to determine if the parameter was skipped:

  Function Test(a,b,c)
    If IsMissing(a) Or IsMissing(b) Then Exit Sub
  End Function

Example

Function Factorial(n%) As Integer
  'This function calculates N! (N-factorial).
  f% = 1
  For i = n To 2 Step -1
    f = f * i
  Next i
  Factorial = f
End Function

Sub Main()
  'This example calls user-defined function Factorial and displays the
  'result in a dialog box.
  a% = 0
  Do While a% < 2
    a% = Val(InputBox("Enter an integer number greater than 2.","Compute Factorial"))
  Loop
  b# = Factorial(a%)
  MsgBox "The factorial of " & a% & " is: " & b#
End Sub

See Also

Sub...End Sub (statement)

F