lotusscript programming · lotusscript. y. lotusscript is an object-oriented form of basic. ƒ....

LotusScript Programming

Kim [email protected]

Copyright (c) 2006 Kim Greene Consulting, Inc.. All rights reserved worldwide.

2Copyright © 2006 Kim Greene Consulting, Inc. All Rights Reserved Worldwide

Introduction - Kim Greene

President of Kim Greene ConsultingPresident of Kim Greene ConsultingServices offered include:Services offered include:

ƒƒSystem and application tuningSystem and application tuningƒƒEnterprise integrationEnterprise integrationƒƒAdministration and troubleshootingAdministration and troubleshootingƒƒDomino application developmentDomino application developmentƒƒCustomized education and trainingCustomized education and trainingƒƒWorkplace installation and setupWorkplace installation and setupƒƒWorkplace performance tuningWorkplace performance tuningƒƒTechnical writer for Technical writer for eServereServer Magazine and iSeries Magazine and iSeries Experts JournalExperts Journal

Member of Penumbra GroupMember of Penumbra Groupƒƒwww.penumbra.orgwww.penumbra.org


Agenda

Essential DetailsƒWhat is LotusScript?ƒObject oriented

°Properties & MethodsƒEvent driven

Domino Object Model (DOM)ƒLearn how Domino objects relate

Code, Code, Code!!!ƒDemo time!


Essential Details


Domino Basics

Notes uses databases of Documents to collect informationƒEverything is stored in a document

Three types of documentsƒData documentsƒResponse documentsƒDesign documents


LotusScript

LotusScript is an object-oriented form of BASICƒVery similar to Microsoft's Visual Basic

Supported natively in Domino since R4Need to know 3 things to use LotusScript:ƒWhat object-oriented meansƒEvent-driven programmingƒDomino object model


Objects

• Objects are things (hence the name)A door is an objectA button on a form is an object

• Most objects are contained by something elseThe door is contained by the door frameThe button is contained by the formDocuments are contained by the database

• All objects have properties


Properties

• Properties are physical characteristics• Your front door has properties

MaterialColorNumber of windowsIf it’s openIf it’s lockedEtc.


Properties Are Facts

• Notes objects have properties, tooDatabase pathReplica IDThe value of an item (field)Server name

• Some can be changed programmaticallyYou can change the value of an itemYou can’t change the server’s name


Methods

• All objects have methods• Methods are what you use to do things

to objects• The door might have methods like:

OpenCloseSlamKnockLock…


Notice a Subtlety Here

• The fact the door is open is a property

• To cause a closed door to become open requires a method


Notes Objects Have Methods Too

• NotesDocument methods include:CopyToDatabaseMakeResponseSaveSendRemove… any many more …


Events

• Some objects have events• Events are things that happen at a

specific point in timeWhen you click a buttonWhen a document is savedWhen the database is openedWhen you enter a field

• Events are what you use to trigger your code ... to start it actually running


These All Work Together

• At your front doorThe “twist” event of the doorknob object …Triggers the “unlatch” method of the bolt (object)

• In a NotesDocument objectThe “Entering” event of a field (item) …Triggers the “SelectAll” method, highlighting the contents of the field


Everything Falls in a “Class”

• Notes has two types of classes:Front-end classesBack-end classes

• Front-end classesStarts with NotesUIWorkspaceOnly interacts with things on the screenCannot be used in background agents, etc.You will not use these a lot

• Back-end classesStarts with NotesSessionMostly includes things under the coversCan be used almost anywhereIs the bread-and-butter of LotusScript


Dim statements identify objects

• “Dim” declares a variable you plan to useDim x

• Often, Dim statements also define the type of objects that will go into a variable

Dim x As IntegerDim db As NotesDatabaseDim view As NotesView

• You have to work with the object hierarchy from the top down

To get a view, you need a NotesDatabaseTo get a database, you need a NotesSession


Set “instantiates” objects

• After declaring a type (with Dim) you must say which specific one it is (with Set)

Set view = db.GetView(“AllDocsByNumber”)• ‘Dim’ said what it would be (a view)• ‘Set’ says which one it is (AllDocsByNumber)

• Dim as SomeKindOfObject• Set = WhichSpecificObjectOfThatType


Once You Instantiate An Object

• You have access to all of the object’s properties and methods

Dim wallet As MoneyHolderDim cash As MoneyDim serialNumber As StringSet wallet = new MoneyHolderSet cash = wallet.GetBillByDenomination(100)serialNumber = cash.SerialNo ‘a propertyCall cash.Spend(“Saks Fifth Avenue”) ‘ a method


As Actually Used

Dim s as NotesSessionDim db as NotesDatabaseDim view as NotesViewDim doc as NotesDocument

Set s = New NotesSessionSet db = s.CurrentDatabaseSet view = db.GetView(“AllDocsByNumber”)Set doc = view.GetDocumentByKey(“A391”, True)Call doc.Remove(True)


Domino Object Model


Domino Object Model

Confused? How can you keep all of these straight?Confused? How can you keep all of these straight?


Domino Object Model - Applied to previous example


Domino Designer Online Help

HelpHelp\\help6_designer.nsfhelp6_designer.nsfHit F1 from your Domino Designer clientHit F1 from your Domino Designer client

ƒƒIndex Index -- most comprehensive helpmost comprehensive help



Sub InitializeDim ws As New NotesUIWorkspaceCall ws.AddDatabase( "", "log.nsf" )Call ws.AddDatabase( "", "names.nsf)"

End Sub


Code, Code, Code!!!


Example 1

• Update location documentEnable replicationSet replication options and frequency

• Considerations on how to deployAs a buttonAs a background agentAs an event on a form…


Demo Time!!!


Examples – Update location document

Dim db As New NotesDatabase("", "names.nsf")

Dim view As NotesViewDim doc As NotesDocument

'--- Gets a handle on the Location documents from the NAMES.NSFSet view = db.GetView("Locations")Set doc = view.GetFirstDocument()

'--- Loops through the location documents until the endWhile Not (doc Is Nothing)

Call doc.ReplaceItemValue("ReplicationEnabled", "1")Call doc.ReplaceItemValue("ReplicateImmediate" , "1")Call doc.ReplaceItemValue("ReplicateAtStart", "1")Call doc.ReplaceItemValue("Enabled" , "1")Call doc.Save(True, False)

Set doc = view.GetNextDocument(doc)

Wend


Example 2

• Profile documentsSpecify database nameList profile documentsProvide option to delete individual profile documents

• Considerations on how to deployAs a button or actionAs an agent…


Demo Time!!!


Examples – Profile Documents

Dim session As New NotesSession

Dim db As NotesDatabase

Dim answer As String

Dim pcollect As NotesDocumentCollection

Dim pdoc As NotesDocument

Dim k As Integer

Dim profileans As Integer

Dim maildb As String

Dim dbtoopen As String


Examples – Profile Documents (cont’d)

' Ask the user which database they want to open

maildb = Inputbox("Which database do you want to open?")

dbtoopen = "mail\"&maildb

' Set to the database specified by the user

‘NOTE: Server this is running on is KGCI

Set db = session.GetDatabase(“KGCI", dbtoopen)



If Not db Is Nothing Then

If db.IsOpen Then

Messagebox "The database " & db.Title & _

" is open."

answer = Messagebox ("Do you want to see the profile documents?", 4, "")

If answer = 6 Then

Set pcollect = db.GetProfileDocCollection

Select Case pcollect.Count

Case 0

Msgbox "No profile documents found.",64,cagentname

Case Else



For k = 1 To pcollect.Count

Set pdoc = pcollect.GetNthDocument(k)

profileans = Msgbox("Profile document " & pdoc.NameOfProfile & " has been found. Do you want to delete it?",1,cagentname)

If profileans = 1 Then

Messagebox "deleting profile doc"

Call pdoc.Remove(True)

Else

Msgbox "Profile document " & pdoc.NameOfProfile & " was not deleted.",64,cagentname

End If

Next k

End Select

End If



End If

Else

Messagebox "Error opening LOG.NSF"

End If

Exit Sub


Example 3

• Set internet passwordAllow end user to set/change their internet password

• Considerations on how to deployAs a buttonAs an event on a form…


Demo Time!!!


Examples – Update Internet Password

Sub Click(Source As Button)

' Code by Bob Pratico of K2ITS

Dim ses As New NotesSession

Dim reg As New NotesRegistration

Dim MyID As String

Dim MyDir As String

Dim charPos As Integer

Dim serverName As NotesName

Dim ndb, maildb As notesdatabase



' Check to ensure they are executing on the server and not a local replica; bail out if they are not running it on a server

Set maildb = ses.CurrentDatabase

serverN$ = maildb.Server

If serverN$ = "" Then

Messagebox "You cannot do this from a local replica of your mailbox. You must execute this from your mailbox replica on the server", 16, "Sorry - must be run on the server"

Exit Sub

End If



' Tell the user what's about to happen

Messagebox "This will allow you to set (or reset) your Internet Password which is distinct from your Lotus Notes password and is used to " _

& "access Domino web applications." & Chr(13) & Chr(13) & "You will first be asked for your Lotus Notes password to verify your identity. " _

& "Upon confirmation, you will be asked to specify an Internet password of your choice with a minimum of 8 characters (case-sensitive). " _

& "After verifying your choice, the password will be recorded.", 0 + 64, "Set Internet Password"



' Build the filepath to the existing ID which we switch to in order to verify the user's identity

' If the keyfilename contains a backslash character, then it is a full pathname and can be used as is. If keyfilename

' does not contain a backslash character then it is contained

' in the Notes default directory. This can be retrieved from the

' directory environment string.

MyID = ses.GetEnvironmentString("KeyFilename", True)

MyDir = ses.GetEnvironmentString("Directory", True)

Dim nuserName As New NotesName(ses.UserName)

NotesUserName = nuserName.Abbreviated



charPos = Instr(1, MyID, "\")

If charPos = 0 Then ' Not found

build_str = MyDir + "\" + MyID

Else

build_str = MyID

End If

' If the user cancels the password prompt, then an error code will be generated. The On Error statement will redirect the

' program execution so that the error handling code will be executed. The resume statement will then control where

' program execution goes when the error handling routine is completed.



' If the valid password for the current user's Notes ID is entered, then no error code will be generated and the

' program will continue to execute program statements in their normal sequence.

'on error is also used to bail out if the user does not have write access to the Internet password field in the NAB

On Error Goto BailOut

UserName = reg.SwitchToID(build_str)

' If you made it to here then the Notes ID password was entered sucessfully


Examples – Update Internet Password' Now ask for the Internet password with a minimum of 8 characters

EnterPassword:

new_pword = ""

Do While Len(new_pword) < 8

new_pword = Inputbox("Specify a new Internet Password" , "Note: Password must be a minimum of 8 characters")

If Len(new_pword) = 0 Then ' Bail Out if they hit the cancel button

Goto QuitSub

End If

If Len(new_pword) < 8 Then

Messagebox "Password must be at least 8 characters", MB_OK + MB_ICONSTOP + MB_DEFBUTTON0 + MB_APPLMODAL, "Invalid Password!"

End If



Loop

' Ask them to reconfirm the Internet password

confirm_pword = Inputbox("Confirm New Internet Password" , "Please reconfirm ...")

If Len(confirm_pword) = 0 Then ' Bail out if they hit the cancel button

Goto QuitSub

End If



'Compare the two passwords and ensure they are the same

If confirm_pword <> new_pword Then

Messagebox "Confirm password does not match New password - Please Re-enter", MB_OK + MB_ICONSTOP + MB_DEFBUTTON0 + MB_APPLMODAL, _

"Invalid Password!"

Goto EnterPassword

End If

Dim NamesDb As New NotesDatabase("", "NAMES.nsf")

Dim FoundList As NotesDocumentCollection



' Alert the user it may take a few seconds to do the lookup to their Person document in the NABs

Messagebox "Please be patient - this may take a few seconds.", 0 + 64, "Please be patient!"

Dim doc As notesdocument

Dim ndoc As notesdocument

Dim nview As notesview

Dim ncol As notesdocumentcollection

Dim k,x As Integer

Dim locs() As Integer



' Lookup routine into the NAB

Set serverName = ses.CreateName( serverN$ )

serverNameabbr$ = serverName.Abbreviated

Set doc=ses.documentcontext

user1$ = NotesUserName 'this is the user's name

Set ndb = ses.getdatabase(serverN$,"names.nsf")

Set nview = ndb.getview("($VIMPeople)")

Set ndoc = nview.GetDocumentByKey(user1$)

Call nDoc.ReplaceItemValue("HTTPPassword", new_pword) ' write the new password into the Address Book



' Use @Password formula code to scramble the new password value. Use LotusScript Evaluate function to execute the formula statement in LotusScript.

eval = Evaluate("@Password(HTTPPassword)", nDoc)

Call nDoc.ReplaceItemValue("HTTPPassword", eval)

Call nDoc.Save(False, False)

'Success - tell the user

Messagebox "Your Internet Password has been reset on the " & serverNameabbr$ & " server, and is immediately useable on that particular server. For it to be useable on other servers, you will need to allow time for it to replicate.", 0 + 64, "Finished - Internet Password Set!"



Goto QuitSub

BailOut:

Messagebox "Unable to set your Internet Password. Please contact your Notes administrator if you are unsuccessful setting it with this Action Button.",16, "Error!"

Exit Sub

QuitSub:

End Sub


References


References

References

Lotus Domino Homepage

ƒhttp://www.lotus.com/dominoLotus Developer's Domain

ƒhttp://www-10.lotus.com/ldd/notesua.nsf?OpenDatabaseDomino Designer Help - R5 & Domino 6

ƒhelp\help5_designer.nsfƒhelp\help6_designer.nsf

OpenntfOpenntfƒƒhttp://http://www.openntf.orgwww.openntf.org

CodestoreCodestorehttp://http://www.codestore.netwww.codestore.net

SandboxSandboxhttp://http://www.lotus.com/lddwww.lotus.com/ldd

Lotus DocumentationLotus Documentationƒƒhttp://wwwhttp://www--10.lotus.com/ldd/notesua.nsf?OpenDatabase10.lotus.com/ldd/notesua.nsf?OpenDatabase


References

References

Lotus Domino Homepage

ƒhttp://www.lotus.com/dominoLotus Developer's Domain

ƒhttp://www-10.lotus.com/ldd/notesua.nsf?OpenDatabaseDomino Designer Help - R5 & Domino 6

ƒhelp\help5_designer.nsfƒhelp\help6_designer.nsf

Lotus Developer’s DomainLotus Developer’s Domainhttp://http://www.lotus.com/lddwww.lotus.com/ldd

Domino Designer Help databasesDomino Designer Help databasesƒƒhelphelp\\help5_designer.nsfhelp5_designer.nsfƒƒhelphelp\\help6_designer.nsfhelp6_designer.nsfƒƒHelpHelp\\help7_designer.nsfhelp7_designer.nsf


References

Class map in Domino 6 and 7 Designer Class map in Domino 6 and 7 Designer clientsclientsƒƒDomino Objects for LotusScript and OLEDomino Objects for LotusScript and OLE

Reference tab in design pane of Domino Reference tab in design pane of Domino DesignerDesigner


Your Turn!

Questions?