Share via


How to: Force an Argument to Be Passed by Value 

The procedure declaration determines the passing mechanism. If a parameter is declared ByRef, Visual Basic expects to pass the corresponding argument by reference. This allows the procedure to change the value of the programming element underlying the argument in the calling code. If you wish to protect the underlying element against such change, you can override the ByRef passing mechanism in the procedure call by enclosing the argument name in parentheses. These parentheses are in addition to the parentheses enclosing the argument list in the call.

The calling code cannot override a ByVal mechanism.

To force an argument to be passed by value

  • If the corresponding parameter is declared ByVal in the procedure, you do not need to take any additional steps. Visual Basic already expects to pass the argument by value.

  • If the corresponding parameter is declared ByRef in the procedure, enclose the argument in parentheses in the procedure call.

Example

The following example overrides a ByRef parameter declaration. In the call that forces ByVal, note the two levels of parentheses.

Sub setNewString(ByRef inString As String)
    inString = "This is a new value for the inString argument."
    MsgBox(inString)
End Sub
Dim str As String = "Cannot be replaced if passed ByVal"

' The following call passes str ByVal even though it is declared ByRef.
Call setNewString((str))
' The parentheses around str protect it from change.
MsgBox(str)

' The following call allows str to be passed ByRef as declared.
Call setNewString(str)
' Variable str is not protected from change.
MsgBox(str)

When str is enclosed in extra parentheses within the argument list, the setNewString procedure cannot change its value in the calling code, and MsgBox displays "Cannot be replaced if passed ByVal". When str is not enclosed in extra parentheses, the procedure can change it, and MsgBox displays "This is a new value for the inString argument."

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.

Robust Programming

If a procedure declares a parameter ByRef, the correct execution of the code might depend on being able to change the underlying element in the calling code. If the calling code overrides this calling mechanism by enclosing the argument in parentheses, or if it passes a nonmodifiable argument, the procedure cannot change the underlying element. This might produce unexpected results in the calling code.

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: Change the Value of a Procedure Argument
How to: Protect a Procedure Argument Against Value Changes

Concepts

Procedures in Visual Basic
Procedure Parameters and Arguments
Argument Passing By Value and By Reference
Differences Between Modifiable and Nonmodifiable Arguments
Differences Between Passing an Argument By Value and By Reference
Argument Passing by Position and by Name
Value Types and Reference Types