Passing Arguments by Value and by Reference (Visual Basic)
In Visual Basic, you can pass an argument to a procedure by value or by reference. This is known as the passing mechanism, and it determines whether the procedure can modify the programming element underlying the argument in the calling code. The procedure declaration determines the passing mechanism for each parameter by specifying the ByVal (Visual Basic) or ByRef (Visual Basic) keyword.
Distinctions
When passing an argument to a procedure, be aware of several different distinctions that interact with each other:
Whether the underlying programming element is modifiable or nonmodifiable
Whether the argument itself is modifiable or nonmodifiable
Whether the argument is being passed by value or by reference
Whether the argument data type is a value type or a reference type
For more information, see Differences Between Modifiable and Nonmodifiable Arguments (Visual Basic) and Differences Between Passing an Argument By Value and By Reference (Visual Basic).
Choice of Passing Mechanism
You should choose the passing mechanism carefully for each argument.
Protection. In choosing between the two passing mechanisms, the most important criterion is the exposure of calling variables to change. The advantage of passing an argument ByRef is that the procedure can return a value to the calling code through that argument. The advantage of passing an argument ByVal is that it protects a variable from being changed by the procedure.
Performance. Although the passing mechanism can affect the performance of your code, the difference is usually insignificant. One exception to this is a value type passed ByVal. In this case, Visual Basic copies the entire data contents of the argument. Therefore, for a large value type such as a structure, it can be more efficient to pass it ByRef.
For reference types, only the pointer to the data is copied (four bytes on 32-bit platforms, eight bytes on 64-bit platforms). Therefore, you can pass arguments of type String or Object by value without harming performance.
Determination of the Passing Mechanism
The procedure declaration specifies the passing mechanism for each parameter. The calling code can't override a ByVal mechanism.
If a parameter is declared with ByRef, the calling code can force the mechanism to ByVal by enclosing the argument name in parentheses in the call. For more information, see How to: Force an Argument to Be Passed by Value (Visual Basic).
The default in Visual Basic is to pass arguments by value.
When to Pass an Argument by Value
If the calling code element underlying the argument is a nonmodifiable element, declare the corresponding parameter ByVal (Visual Basic). No code can change the value of a nonmodifiable element.
If the underlying element is modifiable, but you do not want the procedure to be able to change its value, declare the parameter ByVal. Only the calling code can change the value of a modifiable element passed by value.
When to Pass an Argument by Reference
If the procedure has a genuine need to change the underlying element in the calling code, declare the corresponding parameter ByRef (Visual Basic).
If the correct execution of the code depends on the procedure changing the underlying element in the calling code, declare the parameter ByRef. If you pass it by value, or if the calling code overrides the ByRef passing mechanism by enclosing the argument in parentheses, the procedure call might produce unexpected results.
Example
Description
The following example illustrates when to pass arguments by value and when to pass them by reference. Procedure Calculate has both a ByVal and a ByRef parameter. Given an interest rate, rate, and a sum of money, debt, the task of the procedure is to calculate a new value for debt that is the result of applying the interest rate to the original value of debt. Because debt is a ByRef parameter, the new total is reflected in the value of the argument in the calling code that corresponds to debt. Parameter rate is a ByVal parameter because Calculate should not change its value.
Code
Module Module1
Sub Main()
' Two interest rates are declared, one a constant and one a
' variable.
Const highRate As Double = 12.5
Dim lowRate = highRate * 0.6
Dim initialDebt = 4999.99
' Make a copy of the original value of the debt.
Dim debtWithInterest = initialDebt
' Calculate the total debt with the high interest rate applied.
' Argument highRate is a constant, which is appropriate for a
' ByVal parameter. Argument debtWithInterest must be a variable
' because the procedure will change its value to the calculated
' total with interest applied.
Calculate(highRate, debtWithInterest)
' Format the result to represent currency, and display it.
Dim debtString = Format(debtWithInterest, "C")
Console.WriteLine("What I owe with high interest: " & debtString)
' Repeat the process with lowRate. Argument lowRate is not a
' constant, but the ByVal parameter protects it from accidental
' or intentional change by the procedure.
' Set debtWithInterest back to the original value.
debtWithInterest = initialDebt
Calculate(lowRate, debtWithInterest)
debtString = Format(debtWithInterest, "C")
Console.WriteLine("What I owe with low interest: " & debtString)
End Sub
' Parameter rate is a ByVal parameter because the procedure should
' not change the value of the corresponding argument in the
' calling code.
' The calculated value of the debt parameter, however, should be
' reflected in the value of the corresponding argument in the
' calling code. Therefore, it must be declared ByRef.
Sub Calculate(ByVal rate As Double, ByRef debt As Double)
debt = debt + (debt * rate / 100)
End Sub
End Module
See Also
Tasks
How to: Pass Arguments to a Procedure (Visual Basic)
How to: Change the Value of a Procedure Argument (Visual Basic)
How to: Protect a Procedure Argument Against Value Changes (Visual Basic)
How to: Force an Argument to Be Passed by Value (Visual Basic)
Concepts
Procedure Parameters and Arguments (Visual Basic)