Sub Statement

Sub Statement
Language Items List

Definition:
Declares and defines the name, arguments, and code that make up a Sub procedure. The Sub statement is similar to the Function statement, however, the procedures (methods) that it defines can't be used in an expression.

Syntax:
[Static] Sub subname [(argumentlist)]
[statementblock]
[Exit Sub]
[statementblock]
End Sub

Details:
All executable code must be entered in the Methods Window as Function or Sub procedures.

Syntax Description

Static Indicates that the Function procedure's local variables do not get reset between calls.

Sub Indicates the beginning of a Sub procedure.

subname The procedure's name. When naming a Sub procedure follow the same naming conventions used for naming other variables, however, type-declaration characters are not allowed.

The subname cannot duplicate the name of any other method defined by the same object. If the subname is the same as a method defined by a baseclass object of ours, our method is said to “override” that methods definition. See the Strictly keyword used in Dim)

argumentlist List of variables that represent arguments passed to the called Function procedure. Separate multiple variables with commas. Individual arguments are passed by reference, unless identified using ByVal. This means that changing an argument’s value inside the Function procedure also changes its value in the calling procedure. If an argument passed to a function is an expression, no part of the expression is changed by the function.

statementblock One or more program lines located within the body of the Sub procedure. These lines make up the body of the function that is executed.

Exit Sub Alternative exit that forces the Sub procedure to be exited immediately. Program execution continues with the statement following the one that called the Sub procedure. You can include as many Exit Sub statements as you like in a Sub procedure.

End Sub Indicates the end of a Sub procedure.

The argument argumentlist has the following syntax. Arguments can be used to change a procedure's behavior or to supply it with some information it can act on:

[ByVal]variable[()] [,[ByVal]variable [()] ] [ As type] ...

Syntax Description

ByVal Specifies that the argument is passed by value, not by reference. Do not use ByVal of an object type, or a variable that is an array.

ariable Name of the variable that represents the argument. For array variables, omit the number of dimensions and include the parentheses.

As type Declares the data type of variable as Double, Currency, Integer, Long, Single, String (variable-length strings only) or object type. A separate As type clause should be used for each set of variables.

Details:
The following examples show various ways to declare integers. The following line declares two by-reference integer arguments:

x,y As Integer

To declare one ByVal integer argument and one by-reference integer argugment, use the following:

ByVal arg1, arg2 As Integer

The following line declares two by-reference integer arguments, and one by-reference single argument:

x,y As Integer, z As Single

To declare a single argument of type object reference to objects of type Form, use the following line:

f As Form

Trying to pass any object that is not a Form or does not inherit from Form throws a type-mismatch program exception. For example, declaring an argument type to be “Window” would allow objects of type Window, Control, Form, and others under each of those types, but not unrelated types.

A Sub procedure is an individual procedure that can take arguments, perform a series of statements, and change its argument values just like a Function procedure. However, a Sub procedure cannot be used in an expression. To call a Sub procedure use the procedure name followed by the argument list. You can also use the optional Call reserved word. Refer to the Call Statement description for more information on calling Sub procedures.

Sub procedures are commonly used to define tasks that will be performed repeatedly, thus reducing the amount of code needed in a program. A sub procedure is also useful for breaking large tasks into several smaller ones in order to isolate each task for debugging.

Caution: Sub procedures can be recursive, meaning that they can call themselves to perform a specified task. Recursive procedures, however, can cause a stack overflow exception to be thrown.

Variables used in Sub procedures must be explicitly declared within the particular procedure. These variables are always local to the procedure.