The syntax for defining a subroutine is as follows:

[accessibility] Sub name([parameters])
    ...statements...
End Sub

Where:

For example, the following subroutine displays a message box that greets the user by name. This subroutine takes no parameters.

Public Sub SayHi()
    MessageBox.Show("Hello " & SystemInformation.UserName)
End Sub

The following code shows how the program might invoke the subroutine:

Private Sub Form1_Load() Handles MyBase.Load
    SayHi()
End Sub

A subroutine executes its code until it reaches the End Sub statement, at which point control returns to the calling code.

You can also use one or more Return statements to make the subroutine return to the calling code early, skipping any code that comes later.

For example, the following subroutine checks the username and password textboxes. If either is blank, the subroutine returns. If both are filled in, the subroutine continues to run other code to validate the user.

Public Sub ValidateUser ()
    If txtUsername.Text.Length < 1 Then Return
    If txtPassword.Text.Length < 1 Then Return

    ' Look up the user in the database.
    ...
End Sub

The syntax for defining a function is similar to the syntax for defining a subroutine, with the addition of a return type:

[accessibility] Function name([parameters]) As returnType
    ...statements...
End Function

The only new piece (aside from using the keyword Function instead of Sub) is returnType. This indicates the data type returned by the function.

To exit a function, use the Return keyword followed by the value the function should return to the calling code.

For example, the following function examines the current hour of the day and builds a greeting message accordingly. The Return statement at the end makes the function return the message.

Public Function Greeting() As String
    Dim message As String
    Select Case Date.Now.Hour
        Case Is < 12
            message = "Good morning "
        Case Is < 17
            message = "Good afternoon "
        Case Else
            message = "Good evening "
    End Select

    Return message
End Function

You can use more than one Return statement to make the function return in several places. For example, you could rewrite the Greeting function like this:

Private Function Greeting() As String
    Select Case Date.Now.Hour
        Case Is < 12
            Return "Good morning "
        Case Is < 17
            Return "Good afternoon "
        Case Else
            Return "Good evening "
    End Select
End Function

Once you have defined a function, you can invoke it and treat its result just as you would treat any literal or variable value of that data type.

For example, the following version of the SayHi subroutine calls the Greeting function and concatenates its result to the value returned by SystemInformation.UserName to produce a greeting message:

Public Sub SayHi()
    MessageBox.Show(Greeting() & SystemInformation.UserName)
End Sub

A procedure's declaration can include a comma-separated list of parameters that allow calling code to pass information into the procedure. Each parameter's declaration begins with the keyword ByVal or ByRef, followed by the parameter's name and its data type.

The following section says more about ByVal and ByRef but first it's worth looking at an example.

Recall the definition of the factorial function. The factorial of a number N is written N! and pronounced N factorial. The definition of N! is 1 * 2 * 3 * ... * N.

The following Visual Basic code implements the factorial function:

' Return value!
Public Function Factorial(ByVal value As Long) As Long
    Dim result As Long = 1
    For i As Long = 2 To value
        result *= i
    Next i
    Return result
End Function

This function's parameter list declares a parameter named value of type Long. The name value is the name that the parameter has inside the function. It behaves mostly like a variable declared within the function by using the Dim statement.

The following code invokes the Factorial function:

Dim number As Long = CLng(txtNumber.Text)
Dim result As Long = Factorial(number)
MessageBox.Show(result.ToString())

This code converts text entered by the user into a Long and saves it in the variable number. It then calls the Factorial function, passing number in as a parameter.

At this point control moves to the Factorial function. Inside that function, whatever value was passed to it (in this case, whatever was in the number variable) is known by the parameter name value. The function performs its calculations and returns a result.

Control then returns to the Click event handler, which saves the value returned by Factorial in the variable result. Finally, the code displays the result in a message box.

A procedure's parameter list can include zero, one, or more parameters separated by commas. For example, the following code defines the function Gcd, which returns the greatest common divisor (GCD) of two integers. (The GCD of two integers is the largest integer that evenly divides them both.)

' Calculate GCD(a, b).
Private Function Gcd(ByVal a As Long, ByVal b As Long) As Long
    Dim remainder As Long
    Do
        remainder = a Mod b
        If (remainder <> 0) Then
            a = b
            b = remainder
        End If
    Loop While (remainder > 0)

    Return b
End Function

The following code shows how you might call the Gcd function. The code initializes two integers and passes them to the Gcd function, saving the result. It then displays the result in a message box.

Dim a As Long = CLng(txtA.Text)
Dim b As Long = CLng(txtB.Text)
Dim result As Long = Gcd(a, b)
MessageBox.Show(result.ToString())

Parameter lists have one more feature that's confusing enough to deserve its own section. Parameters can be passed to a procedure by value or by reference.

When you pass a parameter by value, Visual Basic makes a copy of the value and passes the copy to the procedure. The procedure can then modify its copy without damaging the value used by the calling code.

In contrast, when you pass a value by reference, Visual Basic passes the location of the value's memory into the procedure. If the procedure modifies the parameter, the value is changed in the calling code as well.

Normally values are passed by value. That's less confusing because changes that are hidden inside the procedure cannot confuse the calling code. Sometimes, however, you may want to let a procedure modify a parameter. For example, suppose you want to write a function named GetMatchup that selects two chess players to play against each other. The method should return True if it can find a match and False if no other matches are possible (because they've all been played). The function can only return one value (True or False), so it returns the two players through parameters passed by reference.

The following code shows how the method might be structured:

Private Function GetMatchup(ByRef player1 As Integer,
 ByRef player2 As Integer) As Boolean
    ' Do complicated stuff to pick an even match.
    ...

' Somewhere in here the code sets player1 and player2.
    ...

    ' We found a match.
    Return True
End Function

The method takes two parameters, player1 and player2, that are passed by reference. The method performs some complex calculations not shown here to assign values to player1 and player2. It then returns True to indicate that it found a match.

The following code shows how a program might call this method:

Dim playerA, playerB As Integer
If (GetMatchup(playerA, playerB)) Then
    ' Announce this match.
    ...
Else
    ' No match is possible. We're done.
    '...
End If

This code declares variables playerA and playerB to hold the selected players' names. It calls the GetMatchup method, passing it the two player name variables. Depending on whether the method returns True or False, the program announces the match or does whatever it should when all the matches have been played.

Notice that there's no indication in the calling code that these parameters are being passed by reference. That can make understanding and debugging the code more confusing. Because of that potential for confusion, it's considered bad practice to return results from a procedure through parameters passed by reference.

A better approach is to use a function that takes input parameters by value and returns as a result a structure holding all the output values.

In this lesson: