LOTUSSCRIPT LANGUAGE

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.


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
    anyFruitV.PrintColor
   
    Set anyFruitV = myBanana
    anyFruitV.PrintColor
   
    Set anyFruitV = myGrape
    anyFruitV.PrintColor
End Sub

Language cross-reference

Testing object references in LotusScript language

See Also