This documentation is archived and is not being maintained.

Argument Passing Mechanism

Visual Studio .NET 2003

When a nonvariable element is passed as an argument, the procedure can never modify it in the calling code, whether it is passed ByVal or ByRef. For a variable element, the following table summarizes the interaction between the element's data type and the passing mechanism.

Element type Passed ByVal Passed ByRef
Value type (contains only a value) The procedure cannot change the variable or any of its members. The procedure can change the variable and its members.
Reference type (contains a pointer to a class or structure instance) The procedure cannot change the variable but can change members of the instance to which it points. The procedure can change the variable and members of the instance to which it points.

Determination of the Passing Mechanism

The procedure declaration determines the passing mechanism. The calling code cannot override a ByVal mechanism, but if an argument is declared with ByRef, the calling code can force the mechanism to pass by value by enclosing the argument name in parentheses in the call. The following example illustrates this:

Sub DoSomething(ByRef InString As String)
   ' Code that makes changes to InString.
End Sub
' ...
Dim Str As String = "Cannot be replaced if passed ByVal"
Call DoSomething((Str))   ' Pass Str ByVal even though declared ByRef.
' The parentheses around Str protect it from change.

The default in Visual Basic is to pass arguments by value. You can make your code easier to read by using the ByVal keyword, as in the following example:

Sub PostAccounts(ByVal AcctNum As Integer)
   ' Code to post accounts.
End Sub

When you pass a variable by reference, you must use the ByRef keyword to specify this mechanism. The preceding example can be extended with a second argument as follows:

Sub PostAccount(ByVal AcctNum As Integer, ByRef RunningTotal As Single)
   ' Code to post account for AcctNum and change value of RunningTotal.
End Sub

It is good programming practice to include either the ByVal or ByRef keyword with every declared argument.

Choice of the Passing Mechanism

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.

Although the passing mechanism can also 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 is more efficient to pass it ByRef.

For reference types, only the four-byte pointer to the data is copied. Therefore, you can pass arguments of type String or Object ByVal without harming performance.

See Also

Argument Passing ByVal | Argument Passing ByRef | Argument Passing by Position and by Name | Procedures | Procedure Arguments | Argument Data Type Declaration | Optional Arguments | Parameter Arrays | Value Types and Reference Types | ByVal | ByRef