Beginner LotusScript for Notes Domino 6
Intermediate LotusScript for Notes Domino 6
Advanced LotusScript for Notes Domino 6
Notes Domino 6 LotusScript Package

Using Custom Classes in LotusScript

Classes are used in LotusScript to work with the core Notes objects like NotesDocument and NotesDatabase. These classes are used to represent an object in Notes like a document or a database. Programmers use properties and methods to set and retrieve information about these objects. Programmers can create their own classes to represent an object. These custom classes can then be used across the application to save programming time and reduce code maintenance.

This tip is for advanced LotusScript programmers who are already familiar with subroutines and functions. See the list of TLCC courses at the start of this tip if you want to learn more about TLCC's LotusScript courses. TLCC also offers a free demonstration version of our beginner LotusScript course.

If you are a LotusScript programmer than you already have used the supplied classes that are in Notes. The NotesDocument class is an example of a class. The NotesDocument class is used to represent a particular Notes document. The line below assigns the first document from a Notes View to the object called doc:

Dim doc as NotesDocument

Set doc = MyView.GetFirstDocument

The doc object is now "instanstiated", meaning it points to an area in memory that contains information about this actual Notes document. The following example shows how to retrieve a document property:

MsgBox doc.LastModified

This object also has methods which are used to take an action. Below is one example used to save the object (the document) to the Notes database:

doc.Save(false, false )

Working with the Notes classes should be very familiar to you. Suppose you want to create your own object to represent your data?

Demonstration

Demonstration Database The attached Database has a demonstration of the code in this tip. Detach the following Notes database to your Notes Data directory. Open this database using File | Database | Open. The demos are all agents. Using the Notes client go to the Actions menu to run the agents. The code can be viewed using the Domino Designer client.

Creating a Custom Class

Let's assume our data is used to represent a person (it could be an employee, customer or vendor.) There are certain items about that person we want to represent:

• Name
• Address
• City
• State
• Phone

Working With Custom Classes

Before diving deeper into the custom classes, let's explore what exactly is an object. The object created above is an area in memory that holds the data about this object, John, in this case. Many objects can be created using the same Person class. Objects can be assigned to another object reference variable. However, the assigned objects all point to the same area in memory. If an object's properties are changed than any other object pointing to the same memory location will also change. Objects are assigned to other objects (of the same class) by using the assignment operator (equals sign.)

The code example below creates a John object like before. It then assigns John to Harry (which is the same Person class.) The code than changes a property for Harry. This also changes John's property as well. Objects can be assigned to other object reference variables and also stored in arrays.

1.	Sub Initialize
2.	Dim cr As String
3.	cr =  Chr(13)
4.	Dim John As New Person
5.	John.firstname = "John"
6.	John.lastname = "Smith"
7.	John.address = "Main Street"
8.	John.city = "Miami"
9.	John.state = "FL"
10.	John.phone = "555-1212"
11.	Msgbox "The information about John is:" + cr + John.firstname  + " " + John.lastname   + cr + John.address + cr + John.city +", " +John.state +"   " + John.phone
12.	Dim Harry As Person
13.	Set Harry = John
14.	Msgbox "The information about Harry is:" + cr + harry.firstname  + " " + harry.lastname + cr + harry.address + cr + harry.city +", " +harry.state +"   " + harry.phone
15.	Harry.firstname = "Harry"
16.	Harry.lastname = "Jones"
17.	Msgbox "The information about Harry is:" + cr + harry.firstname  + " " + harry.lastname + cr + harry.address + cr + harry.city +", " +harry.state +"   " + harry.phone
18.	Msgbox "The information about John is:" + cr + John.firstname  + " " + John.lastname + cr + John.address + cr + John.city +", " +John.state +"   " + John.phone
19.	End Sub

This code is demonstrated in the sample database as the agent "Assigning Objects".

Variables that reference an object can be set to "nothing" so that they no longer point at data in memory. The line below sets John to nothing. Nothing is a keyword that can be used to delete the variable's reference. Any other variables that point to the same place in memory will still be valid. When there is no longer any object reference variables pointing to the data in memory than LotusScript will automatically release that memory (cleanup.)

Set John = Nothing

When John is now accessed an error will occur:

      

To prevent this error you can test the object reference variable to determine if it is pointing to an actual object using the "Is" operator as follows:

If John Is Nothing Then

Msgbox "John does not point to anything."

Else

Msgbox "John's name is:" + cr + John.firstname  + " " + John.lastname

End If

This code is demonstrated in the sample database as the agent "Deleting Objects".

Objects can also be deleted from memory by using the Delete keyword.

Delete John

This will cause the object to be removed from memory and all other objects that point to this object will now be "nothing."

Using New in Custom Classes

In the examples above the New keyword was used to create a new object reference variable. You probably have used the New keyword before in the Notes classes. If you want to point to a Notes database one way is to use the following syntax:


   Dim variableName As New NotesDatabase( server$, dbfile$ )

      or

   Set variableName = New NotesDatabase( server$, dbfile$ )

The server name and the database path and file name are provided in the syntax above. This information is used by the NotesDatabase class to setup the object reference variable to point to that specific database.

The New keyword can also be used in your custom classes to define the object when it is being created. This is done by adding a user defined subroutine called New to the class definition. The example below shows the addition of the New subroutine to the Person class so that the programmer can pass in all the data when creating a new object. The New subroutine can also perform other operations. In the example below the full name is computed and assigned to a variable on line 16.

Whenever the New keyword is used to create an object (with Dim or Set) then the New Subroutine in the Person class below will run. Notice on line 8 that the variables being passed in are sometimes the same as the variables already declared? When this is the case we need to differentiate between the variables declared in the subroutine's declaration and the variables declared already in the class. This is done with the Me keyword. Use of Me.address refers to the variable declared in the class. Me can only be used in the class itself and is used to refer to that class. This is illustrated on lines 11 to 14. If the Me keyword was not used than the class variables would never get set.

1.	Class Person
2.	Public firstname As String
3.	Public lastname As String
4.	Public address As String
5.	Public city As String
6.	Public state As String
7.	Public phone As String
8.	Public fullname as String
9.	Sub New(fname As String, lname As String, address As String, city As String, state As String, phone As String)
10.	firstname = fname
11.	lastname = lname
12.	Me.address = address
13.	Me.city = city
14.	Me.state = state
15.	Me.phone = phone
16.	fullname = fname + " " + lname
17.	End Sub
18.	End Class

The agent code below uses the New keyword when declaring the object.

1.	Sub Initialize
2.	Dim cr As String
3.	cr =  Chr(13)
4.	Dim John As New Person("John","Smith","Main St.","Denver", "CO", "555-1212")
5.	Msgbox "The information about John is:" + cr + John.fullname + cr + John.address + cr +   John.city +", " +John.state +"   " + John.phone
6.	End Sub

This code is demonstrated in the sample database in the agent called "Using New".





Properties and Methods

We defined properties for the custom class in the beginning of this tip. Properties hold values. To access a property using the dot notation (John.address) the property must be declared as Public. In the examples given so far all the properties were declared as Public so they could be accessed outside the class.

Public lastname As String

If the Public keyword was not used than the property could not be accessed outside the class using the dot notation. The line below defines a property for age.

age as integer

The age can be set in the New subroutine or we can add other subroutines or functions to get or set the age. The class definition below has a subroutine to set the age (lines 19-21), a function to return the age (lines 22-24 and another function to add years to an age (lines 25-28.)

1.	Class Person
2.	Public firstname As String
3.	Public lastname As String
4.	Public address As String
5.	Public city As String
6.	Public state As String
7.	Public phone As String
8.	Public fullname As String
9.	age As Integer
10.	Sub New(fname As String, lname As String, address As String, city As String, state As String, phone As String)
11.	firstname = fname
12.	lastname = lname
13.	Me.address = address
14.	Me.city = city
15.	Me.state = state
16.	Me.phone = phone
17.	fullname = fname + " " + lname
18.	End Sub
19.	Sub setAge(a As Integer)
20.	age = a
21.	End Sub
22.	Function getAge() As Integer
23.	getAge = age
24.	End Function
25.	Function addToAge(i As Integer) As Integer
26.	age = age + i
27.	addToAge = age
28.	End Function
29.	End Class