Syntax

[Private | Public] [Static] Sub name[(arglist)]
  [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

Declares a subroutine.

Comments

The Sub statement has the following parts:

Part

Description

Private

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

Public

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

Static

Recognized by the compiler but currently has no effect.

name

Name of the subroutine, which must follow the 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.

3. Must not exceed 80 characters in length.

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 the parameter is passed by value.

ByRef

Keyword indicating that the 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 (i.e., Integer, String, and so on). Arrays are indicated with parentheses. For example, an array of integers would be declared as follows:

 Sub Test(a() As Integer)
 End Sub

A subroutine terminates when one of the following statements is encountered:

  End Sub
  Exit Sub

subroutines can be recursive.

Passing Parameters to Subroutines

Parameters are passed to a subroutine 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 subroutine 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 subroutine. 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 UserSub:

  UserSub 10,12,(j)

Optional Parameters

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

Sub Test(a%,b%,c%)
  End Sub

  Sub Main
    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:

Test 1,,

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

    Test ,1   'Only passes two out of three required parameters.

    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 subroutine, 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 subroutine, 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 subroutine. In this case, you can use the IsMissing function to determine if the parameter was skipped:

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

Example

This example uses a subroutine to calculate the area of a circle.

Sub Main()
  r = inputbox("Enter a circle radius to be converted to area","Radius -> Area")
  PrintArea r
End Sub

Sub PrintArea(r)
  area! = (r ^ 2) * Pi
  MsgBox "The area of a circle with radius " & r & " = " & area!
End Sub

See Also

Main (statement); Function...End Function (statement).

S