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 or ByRef keyword.
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 and Differences Between Passing an Argument By Value and By Reference.
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
ByRefis that the procedure can return a value to the calling code through that argument. The advantage of passing an argument
ByValis 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
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
Objectby 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
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.
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. 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.
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
ByRefpassing mechanism by enclosing the argument in parentheses, the procedure call might produce unexpected results.
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 is a
ByRef parameter, the new total is reflected in the value of the argument in the calling code that corresponds to
rate is a
ByVal parameter because
Calculate should not change its value.
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
Procedure Parameters and Arguments
How to: Pass Arguments to a Procedure
How to: Change the Value of a Procedure Argument
How to: Protect a Procedure Argument Against Value Changes
How to: Force an Argument to Be Passed by Value
Passing Arguments by Position and by Name
Value Types and Reference Types