Passing arguments by reference and by value

LotusScript® provides two ways to pass arguments to functions and subs:

By reference (default)
When you pass an argument by reference, you pass a pointer to the value in memory. The function operates on the argument. When a function changes the value of an argument passed by reference, the original value changes.
By value
When you pass an argument by value, you pass a copy of the value in memory. The function operates on the copy. This means that when a function changes the value of an argument passed by value, the effect is local to that function; the copy changes but the original value in memory is not affected.

Whether an argument is passed by reference or by value depends on the data type and other characteristics of the argument:

Arrays, lists, type instances, and objects must be passed by reference.

Note: An array parameter should not be declared as "ByVal"; a Function or Procedure call should not have parentheses around an array argument.

Constants and expressions are automatically passed by value.
Other arguments can be passed either way, as specified in the definition or the call. Arguments to functions and subs are passed by reference unless the definition or the call specifies passing by value.

Passing by reference

The variable must have the same data type as the corresponding parameter in the function definition, unless the parameter is declared as Variant or is an object variable. An object variable can be passed to an object of the same, base, or derived class. In the latter, the base class must contain an instance of the derived class or a class derived from the derived class.

If the variable is then modified by the function or sub, the variable has the modified value when the function or sub returns.

Passing by value

You can do the following:

Use the ByVal keyword in the argument's declaration in the function or sub definition.
The argument is passed by value whenever the function or sub is called.
Insert parentheses around the argument in the function or sub call.
You can control whether an argument is passed by reference or by value at the time when the function or sub is called.

A value passed to a function or sub is automatically converted to the data type of the function or sub argument if conversion is possible. A Variant argument will accept a value of any built-in data type; and any list, array, or object. A Variant argument will not accept a value of a user-defined type. Keep in mind, however, that lists, arrays, objects, and user-defined types cannot, and therefore should not, be passed by value.

If the variable argument is then modified by the function or sub, the variable has its original value after the function or sub returns. The function or sub operates only on the passed copy of the variable, so the variable itself is unchanged.

Examples

Example 1

' Define a function FOver with three Integer parameters:
' a variable, an array variable, and a list variable.
Function FOver(a As Integer, b() As Integer, c List As Integer)
   ' ...
End Function
Dim x As Integer
Dim y(5) As Integer
Dim z List As Integer
' Call the function FOver correctly, with arguments
' whose types match the types of the declared parameters.
Call FOver(x, y, z)

Example 2

' Define a function GLevel with one Integer list parameter.
Function GLevel (b List As Integer)
   ' ...
End Function
Dim z List As Integer
' Call the function GLevel incorrectly, passing a list
' argument by value.
Call GLevel ((z))
' Output:
' Error: Illegal pass by value: Z
' A list argument cannot be passed by value.

Example 3

' Define a function FExpr with two Integer parameters;
' the second must always be passed by value.
Function FExpr(a As Integer, ByVal b As Integer)
   ' ...
End Function
Dim x As Integer, w As Integer
Dim y(5) As Integer
Dim z List As Integer
' Call the function FExpr correctly with two Integer
' arguments: a constant and a variable.
Call FExpr(TRUE, x)
' Both arguments are passed by value:
' the first, TRUE, because it is a constant;
' and the second, x, because of the ByVal declaration
' in FExpr.
' The following call produces two error messages:
Call FExpr(TRUE, y)
' Output:
' Error: Illegal pass by value: Y
' Error: Type mismatch on: Y
' Because Y is an array variable, it is an illegal argument to 
' pass by value and its type does not match the declared 
' parameter type.

Example 4

' When a function modifies one of its parameters,
' the argument value is changed after the function returns
' if the argument was passed by reference. The value is not
' changed if the argument was passed by value.
Function FTRefOrVal(a As Integer) As Integer
   FTRefOrVal = a + 1
   a = a + 5
End Function
Dim x As Integer, y As Integer
' Show results of passing argument by reference.
Print x, FTRefOrVal(x), x
' Output:
' 0            1             5
' The value of x was changed from 0 to 5 in FTRefOrVal.
' Show results of calling with argument by value
' (note the extra parentheses around y%).
Print y, FTRefOrVal((y)), y
' Output:
' 0            1             0
' The value of the copy of y was changed from 0 to 5
' in FTRefOrVal. The value of y is unchanged.

Additional Documentation | Trademarks |