IBM Support

LotusScript Self-Help Training Module 1 - 'Using LotusScript within a custom application'



This technote is the first of two modules that train you on how to use LotusScript within a custom built application. Module 1 covers Domino Designer, LotusScript Debugger and the Designer Help file. Module 2 covers the creation of back-end LotusScript agents.


This training module is broken up into three parts, each containing a written section as well as an accompanying video that demonstrates the information presented in the text. You can either read the information, watch the video, or do both as you prefer.

Part 1: Domino Designer
Part 2: LotusScript Debugger
Part 3: Domino Designer Help

Click here to access the second module of this training, which is titled "How to write a simple back-end LotusScript agent".

Part 1: Domino Designer

Video: Domino Designer (10 min 02 sec)

LotusScript is one of many languages that you can use within Notes/Domino including Simple Actions, Formula Language, Java, JavaScript and HTML. LotusScript, like the other languages, can be used in a wide variety of places within a Notes Application. Agents, form events, field events, view events, database events, buttons, and actions are a few of the places that LotusScript can be used. However before we can start putting LotusScript into any of these places we will need to be familiar with the Domino Designer client.

There are three types of Notes clients. In addition to the regular Notes client that most users are familiar with, there is also the Domino Administration client and the Domino Designer client. The Domino Designer client needs to be installed on the workstation and it can be accessed by clicking on the Designer icon on the windows desktop or the Designer icon from the regular Notes client

Figure 1

The icon for the Designer client is the one that has the angle square superimposed on it. If the icons for the Designer client do not exist on your machine, search the Notes program directory for the Designer executable, which is named ndesigner.exe on a Windows machine. This can be done by choosing Start -> Search on a Windows machine and then choosing All files and folders and supplying ndesigner.exe as the file to look for. If it is not found then the Notes client will need to be reinstalled making sure that the option to install the Designer client is checked as part of the install. The installation can be done over the top of the existing Notes client and none of the settings, bookmarks, etc will be lost.

In addition to the Domino Designer client, a user will also need to have the proper Access Control Level (ACL) to a Notes database in order to be able to open it in the Designer client. The ACL levels required are designer or manager. There are several ways to open a database in the Designer client once the correct ACL level has been set. A user can click on the Open database icon of the home page of the Domino Designer client (see figure 2)

Figure 2

You can choose File Open database from the Domino Designer client as well and then navigate to the Notes database either locally or on the Domino server.

Figure 3

You can also right click on a database icon on the workspace and chose open in Designer.

Figure 4

Most design elements in a Notes Database can use LotusScript and so will have different sections to which LotusScript code can be added. The sections that are available are dependent on what Design element we are working with. For example, a form has QueryOpen and QueryClose events that a field does not but a field has entering and exiting events that a form does not have. You can tell what events are available for particular Design element by looking in the Domino Designer client

Figure 5

LotusScript can be put in any event that has the little scroll symbol next to it (Figure 5) but not in those that have the circle next to it, only JavaScript can be used in those. You can tell which ones already have code in them as they will be the dark ones, if the scroll is clear then there is no code in it. More information on each of the events for the different Design elements see the Designer Help File, all of them will be listed in there as well as letting you know what will trigger that event

There are four sections that will be included in all Design element for LotusScript although there is no need to include code on all the sections, just those that you wish to use. The four common events are Initialize, Terminate, Declarations, and Options.

The Initialize event contains the code that gets executed when that LotusScript module gets loaded. In other words it is the code that gets executed when the agent runs or the form gets loaded. You can think of this as the main function of other programming languages like C and Java.

The terminate event contains the code that gets executed when the module gets unloaded. Its the last code that gets executed by that module and can be used for cleaning things up.
The Declarations section is just what it sounds like, a place where you can declare a variety of things such as variables to be used, constants to be used, a user defined class, or even calls to external C functions. Any declarations made here are visible through out all of the LotusScript being used.

The Options section is where you add any of the LotusScript options you wish to be using. For example Option Public to declare this LotusScript for public use or Option Declare to generate errors for any variables that are being used without being declared first. If you have any Script Libraries as part of your database that you want to use, you would include it here by including a Use statement with the library name. For example, Use "Common", would include a script library called Common.

A LotusScript Library is a collection of LotusScript functions that you wish to reuse in multiple places. By including these functions you can have them in one place instead of having a copy of the function in each area you are using it. This not only saves space in the database but also allows a change to one of the functions be made in a single place and reflected in all places the function is being used.

A script library can be created by choosing Create -> Design Script Library -> LotusScript Library.

Figure 6

You can also copy a script library in one database and paste it in another. You can see the script Libraries in a database under the shared code section of the databases (see Figure 7).

Figure 7

In order to be able to create an agent in the Domino Designer client we need to have an understanding on what can trigger an agent to run. There are 2 kinds of Notes agents, Schedule triggered agents and event triggered agents. A scheduled agent is an agent that runs on a schedule. The schedule can be set to run multiple times a day, or daily, weekly or monthly. It can further be scheduled down to the time of day to run or the day of the week or month as well.

Event triggered agents are agents that get triggered when a particular event happens. These events are Action Menu selection, Agent list selection, Before new mail arrives, after new mail arrives, After documents are created or modified, or After documents are pasted. Action Menu selection are used for User-activated agents or for WebQuerySave or WebQueryOpen agents. Agent list selection is used for Agents that are only to be called by other agents and for agents that are still being developed or are run from Designer. Before new mail arrives agents are agents that are run before mail is delivered to a mail file, After new mail arrives agents are run after mail has been delivered to a mail box. After documents are created or modified agents are triggered when documents are created or modified in a database while After documents are pasted only get activated if the document is copied from another database into this one.

Part 2: LotusScript Debugger

The following video demonstrates how to use the LotusScript Debugger.

Video: LotusScript Debugger (4 min 21 sec)

A very useful tool to use in conjunction with Using LotusScript in the Designer client is the LotusScript Debugger. Once it is enabled any LotusScript that runs on the client will be through the debugger. Once in the debugger you can step through the LotusScript line by line, into and out of functions and subroutines as well as monitor, or even change the values of any variables in the code.

You start the LotusScript Debugger with the File Menu, File -> Tools ->Debug LotusScript

Figure 8

Once the debugger is started any LotusScript that gets executed will give you the debug console. The console consists of a window with the LotusScript code in it and then 4 tabs across the bottom that contains some additional information. These tabs are breakpoints, variables, output, calls.

Breakpoints are points in your code that will allow the code to run up until that breakpoint so that you do not have to step through each line. You can add breakpoints by double clicking on the line of code in the debugger, double clicking that line again will disable the breakpoint and double clicking again will remove the breakpoint. You can also add breakpoints to your code by adding a line that says stop and the debugger will always stop on that line. Any breakpoints that have been set can be seen on the breakpoints tab.

The variables tab will contain all of the variables within scope and their current values. The output tab has any output from the agent listed there. And the calls tab gives you the current call stack of functions on where you are in the code.

There are several buttons that allow you to control the flow within the LotusScript

Figure 9

The continue button will let the LotusScript continue until it either completes or hits a breakpoint. The Step Into button will execute the current line of LotusScript but if it is a call to a subroutine or function, it will take us into that function and let us step through the code in that function line by line as well. The Step Over button does the same thing except that if the line is a call into a subroutine of function, it will execute all of the code in that function instead of stepping you into that function. The Step Exit button will execute the rest of the code in the subroutine or function you are in and take you to the next line after the call into the function you were in.

Part 3: Domino Designer Help

Video: Domino Designer Help (4 min 07 sec)

Another very useful tool we have available is the Designer Help file. Each of the three Notes clients has its own Help file. The Designer Help file contains information on all of the different Design elements as well as the different programming languages available for use within Notes. There are example on how to create each of the Design elements available as well as tips on how to get the best performance from that Design elements. There are also sections on accessing Domino data via the Web, securing your application, techniques for testing your application before deploying it etc. You will be able to find information on anything you are trying to do with your Notes application. There are multiple ways to access the data in the Help file, table of contents, an index, or searching. To access the Help file you just need to press the F1 key and the Help file for what ever client you are in will be launched or you can choose Help topics from the Help menu.

Figure 10

Related information

LotusScript Self-Help Training Module 2 - 'How To Write

Document information

More support for: IBM Notes

Software version: 8.5, 9.0

Operating system(s): Windows

Reference #: 7010056

Modified date: 16 June 2010