LOTUSSCRIPT LANGUAGE


Passing arguments by reference and by value
LotusScript provides two ways to pass arguments to functions and subs:
Whether an argument is passed by reference or by value depends on the data type and other characteristics of the argument:
Note An array parameter should not be declared as "ByVal"; a Function or Procedure call should not have parentheses around an array argument.
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:


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.

See Also