How to: Change the Value of a Procedure Argument
When you call a procedure, each argument you supply corresponds to one of the parameters defined in the procedure. In some cases, the procedure code can change the value underlying an argument in the calling code. In other cases, the procedure can change only its local copy of an argument.
When you call the procedure, Visual Basic makes a local copy of every argument that is passed ByVal. For each argument passed ByRef, Visual Basic gives the procedure code a direct reference to the programming element underlying the argument in the calling code.
If the underlying element in the calling code is a modifiable element and the argument is passed ByRef, the procedure code can use the direct reference to change the element's value in the calling code.
Changing the Underlying Value
To change the underlying value of a procedure argument in the calling code
In the procedure declaration, specify ByRef for the parameter corresponding to the argument.
In the calling code, pass a modifiable programming element as the argument.
In the calling code, do not enclose the argument in parentheses in the argument list.
In the procedure code, use the parameter name to assign a value to the underlying element in the calling code.
See the example further down for a demonstration.
Changing Local Copies
If the underlying element in the calling code is a nonmodifiable element, or if the argument is passed ByVal, the procedure cannot change its value in the calling code. However, the procedure can change its local copy of such an argument.
To change the copy of a procedure argument in the procedure code
In the procedure declaration, specify ByVal for the parameter corresponding to the argument.
-or-
In the calling code, enclose the argument in parentheses in the argument list. This forces Visual Basic to pass the argument by value, even if the corresponding parameter specifies ByRef.
In the procedure code, use the parameter name to assign a value to the local copy of the argument. The underlying value in the calling code is not changed.
Example
The following example shows two procedures that take an array variable and operate on its elements. The increase procedure simply adds one to each element. The replace procedure assigns a new array to the parameter a() and then adds one to each element.
Public Sub increase(ByVal a() As Long)
For j As Integer = 0 To UBound(a)
a(j) = a(j) + 1
Next j
End Sub
Public Sub replace(ByRef a() As Long)
Dim k() As Long = {100, 200, 300}
a = k
For j As Integer = 0 To UBound(a)
a(j) = a(j) + 1
Next j
End Sub
Dim n() As Long = {10, 20, 30, 40}
Call increase(n)
MsgBox("After increase(n): " & CStr(n(0)) & ", " & _
CStr(n(1)) & ", " & CStr(n(2)) & ", " & CStr(n(3)))
Call replace(n)
MsgBox("After replace(n): " & CStr(n(0)) & ", " & _
CStr(n(1)) & ", " & CStr(n(2)) & ", " & CStr(n(3)))
The first MsgBox call displays "After increase(n): 11, 21, 31, 41". Because the array n is a reference type, replace can change its members, even though the passing mechanism is ByVal.
The second MsgBox call displays "After replace(n): 101, 201, 301". Because n is passed ByRef, replace can modify the variable n in the calling code and assign a new array to it. Because n is a reference type, replace can also change its members.
You can prevent the procedure from modifying the variable itself in the calling code. See How to: Protect a Procedure Argument Against Value Changes.
Compiling the Code
When you pass a variable by reference, you must use the ByRef keyword to specify this mechanism.
The default in Visual Basic is to pass arguments by value. However, it is good programming practice to include either the ByVal or ByRef keyword with every declared parameter. This makes your code easier to read.
Security
There is always a potential risk in allowing a procedure to change the value underlying an argument in the calling code. Make sure you expect this value to be changed, and be prepared to check it for validity before using it.
See Also
Tasks
How to: Pass Arguments to a Procedure
How to: Protect a Procedure Argument Against Value Changes
How to: Force an Argument to Be Passed by Value
Concepts
Procedure Parameters and Arguments
Passing Arguments by Value and by Reference
Differences Between Modifiable and Nonmodifiable Arguments
Differences Between Passing an Argument By Value and By Reference