Working with object reference variables

You use an object reference variable to create, manage, and delete objects. It has the data type of a class and, like other variables, is a named area in storage. However, unlike other variables, the value stored in the area is not the object itself but a 4-byte pointer to the object data, called an object reference. LotusScript® uses this pointer to access the object data.

When you create an instance of a class, you must explicitly declare an object reference variable. That is, you create the object, create the object reference variable, and assign an object reference to the variable.

The object reference points to the object. When an object is created, its member variables are initialized, each to the initial value for the data type of the member. For example, a member of data type Integer is initialized to 0. If a member is itself a user-defined data type or a class, it is initialized by initializing its member variables.

You can create an object reference without creating an object with the following syntax:

Dim x As ClassName

Because the variable you declare contains a reference to an object that does not yet exist, the variable is initialized to the value NOTHING.

Creating objects

After defining a class, you create and assign objects using the LotusScript® New keyword.

  • To create a new object and assign a reference to that object in a variable that you are declaring, use the Dim statement with the following syntax:

    Dim objRef As New className[(argList)]

  • To create a new object and assign a reference to it if you have already declared an object reference variable (with a Dim statement without the New keyword), use the Set statement with the following syntax:

    Set objRef = New className[(argList)]

You can't use the New keyword to declare an array of object reference variables or a list of object reference variables.

In this example, X can hold only references to Demo objects, or else the value NOTHING. It is initialized to NOTHING.

Class Demo
 ' ...
End Class
' Declare an object reference variable X of the class
' Demo, create an instance of that class, and assign X
' a reference to the new Demo object.
Dim X As New Demo
Dim DemoArray(10) As Demo ' Array of object reference variables
Dim DemoList List As Demo ' List of object reference variables

LotusScript® initializes each element of DemoArray to NOTHING. However, since a list has no elements when it is declared, LotusScript® does not initialize the elements in DemoList. Each element of DemoArray, and each element of DemoList, when created, can hold either the value NOTHING or a reference to a Demo object, for example:

Set DemoArray(0) = New Demo

Using the Set statement

The Set statement is an assignment statement used only to assign values (object references) to object reference variables. You cannot use any other a to assign values to object reference variables.

You can assign a reference to a newly created object to an array element or a list element.

Continuing from the previous example:

Dim Z(10) As Demo 
' Declare an array of object reference variables.
Dim A List As Demo   
' Declare a list of object reference variables.
Set Z(1) = New Demo  
' Assign Z(1) a reference to the created object.
'Assign a list element a reference to the created object.
Set A("ITEM01") = New Demo

You can assign an existing object reference to another variable using the Set statement without the New keyword.

For example:

Class Customer
 ' ...
End Class
' Declare object reference variable C, create a Customer 	' object, and assign C a reference to the new Customer object.
Dim C As New Customer

' Declare object reference variable myArray and initialize
' all elements of MyArray to NOTHING.
Dim myArray(10) As Customer

Dim dTwo As Customer  ' Object reference is set to NOTHING.

Set dTwo = myArray(1) 
' Assign the myArray(1) value, NOTHING, to DTwo.

Set myArray(1) = C
' myArray(1) and C refer to the same Customer.

Set dTwo = myArray(1) 
' Now dTwo also refers to the same Customer.

Set myArray(1) = NOTHING 
' Set the object reference to NOTHING.
' Assign myArray(1) a reference to a new Customer object.
Set myArray(1) = New Customer
' Assign dTwo a reference to a new customer object.
' Now, variables C, myArray(1), and dTwo each refer to
' different Customer objects.
Set dTwo = New Customer

An assignment using Set does not copy an object. The assigned value is a reference to an object, not the object itself. The value stored in an object reference variable is a pointer to the data that makes up the object. Set copies the reference into the target variable.

Using Variants to hold object references

You can assign an object reference to a variable of type Variant.

In the following script, the variable anyFruitV holds a reference to Fruit objects and is of type Variant. The script executes when the user clicks a Notes® button.

Class Fruit
     Sub PrintColor
          MessageBox ("I have no color.")
     End Sub
End Class
Class Banana As Fruit
     Sub PrintColor
          MessageBox ("I'm yellow.")
     End Sub
End Class

Class Grape As Fruit
     Sub PrintColor
          MessageBox ("I'm purple.")
     End Sub
End Class
Sub Click(Source As Button)    ' Sample Notes product object.
     Dim myFruit As New Fruit
     Dim myBanana As New Banana
     Dim myGrape As New Grape
     Dim anyFruitV As Variant
     Set anyFruitV = myFruit
     Set anyFruitV = myBanana
     Set anyFruitV = myGrape
End Sub