Book Image

Domino 7 Application Development

Book Image

Domino 7 Application Development

Overview of this book

Written by Lotus insiders, the book provides a practical guide to developing applications making use of the important features and enhancements introduced in Notes/Domino 7. These experienced experts use their own experiences to map out the benefits you could gain, and the dangers you may face, as you develop Domino applications in your business. Written by specific experts, edited and overseen by Lotus content generator Dick McCarrick, this book is the definitive guide to developing Domino 7 applications. TECHNOLOGY Domino is an application server that can be used as a standalone web server or as the server component of IBM's Lotus Domino product which provides a powerful collaborative platform for development of customized business applications. It also provides enterprise-grade email, messaging, and scheduling capabilities.
Table of Contents (18 chapters)
Domino 7 Application Development
About the Authors
About the Reviewer
Free Chapter
A Short History of Notes and Domino

FT Search Manager

IONET FT Search Manager is a Lotus Notes based search tool for Lotus Notes and Domino environments. The product uses standard Lotus Notes technologies, but in an innovative way. The FT Search Manager supersedes the native Lotus Search Site and Domain Search functions by providing user-targeted searching of any database, in any location without building central search indexes. This gives maximum effectiveness, speed, flexibility, and security to the user. As an example, the user can securely search for the content of a specific field across six encrypted local mail archives, their server-based mail file, and 12 other databases on different servers worldwide. The user selects only databases that have content relevant to them, and they can customize the results individually (or the administrator can do it for them). In addition, they can perform common search functions, such as Google-style searching, and searching within results. For the full product description, features, and downloads, visit

In any Lotus Notes/Domino environment of R6 and greater, the capabilities described below are available. They are summarized as:

  • Multi-threading in the Notes client utilizes the full potential of the Notes client by working in parallel and not sequentially.

  • Emulating browser behavior allows your users to just hit Enter to start searching (you don't need to go get your mouse and click a button). Also no more "Lotus AND Notes AND NOT Microsoft" type queries. Use "Lotus +Notes -Microsoft" instead, as you do in your favorite web search engine.

Let's look at these in more detail.

Multi-Threading in the Notes Client

The FT Search Manager starts ten multi-threaded agents in parallel. All agents start at the same time and run simultaneously. For example, if five databases are being searched, Agents 1-5 search one database each, and Agents 6-10 do nothing. If 12 databases are searched, Agent 1 searches databases 1 and 11, Agent 2 searches databases 2 and 12, Agent 3 searches Database 3, Agent 4 searches Database 4, and so on. There is nothing particularly clever about these agents, they are all normal LotusScript agents with the "Run in Background Client Thread" setting selected, and they are all started at the same time.

The benefits of multi-threading agents are described in the following sections.


The following tests are a comparison of running the agents in parallel vs. running them sequentially. The only difference between the tests is that in the sequential test, the "Run in Background Client Thread" setting is deselected, forcing sequential operation.

The tests were run on the R7.01 server and client version, with the client searching 20 databases, totaling approximately 60 MB. Each agent searched two databases, finding and processing 100 document results per database, and formatting these in HTML for display to the user. This is a total of 2000 results per search.

Parallel agent results:

Agent1 Start: 14:31:05:36

Agent1 End: 14:31:11:14

Agent2 Start: 14:31:05:36

Agent2 End: 14:31:10:94

Agent3 Start: 14:31:05:32

Agent3 End: 14:31:09:86

Agent4 Start: 14:31:05:37

Agent4 End: 14:31:10:16

Agent5 Start: 14:31:05:37

Agent5 End: 14:31:11:14

Agent6 Start: 14:31:05:38

Agent6 End: 14:31:10:79

Agent7 Start: 14:31:05:33

Agent7 End: 14:31:11:14

Agent8 Start: 14:31:05:39

Agent8 End: 14:31:10:87

Agent9 Start: 14:31:05:39

Agent9 End: 14:31:11:14

Agent10 Start: 14:31:05:40

Agent10 End: 14:31:11:14

Note that all agents started within a second of each other and completed within six seconds. Agent 3 was the first agent to finish as there is no correlation between the agents, search results appear "as they arrive". In reality this means that smaller local databases usually display their results first, while results from larger remote databases

are the last to arrive. As the client is searching in the background, the user can read the initial results, or even other information like mail, while all the results arrive.

The same ten agents were then rerun, with the only change being that it was not multi-threaded (deselect "Run in Client Background Thread"):

Sequential agent results:

Agent1 Start: 15:35:33:32

Agent1 End: 15:35:34:28

Agent2 Start: 15:35:34.47

Agent2 End: 15:35:35.52

Agent3 Start: 15:35:35.75

Agent3 End: 15:35:36.59

Agent4 Start: 15:35:36.80

Agent4 End: 15:35:37.66

Agent5 Start: 15:35:37.86

Agent5 End: 15:35:38.70

Agent6 Start: 15:35:38.90

Agent6 End: 15:35:39.58

Agent7 Start: 15:35:39.88

Agent7 End: 15:35:40.79

Agent8 Start: 15:35:40.98

Agent8 End: 15:35:41.85

Agent9 Start: 15:35:42.05

Agent9 End: 15:35:42.88

Agent10 Start: 15:35:43.07

Agent10 End: 15:35:43.73

Note how the agents run sequentially, starting one after the other, and completing within 10 seconds. This can be seen in the following chart:

The following results were obtained over ten consecutive searches (showing elapsed time for all agents to complete, in seconds):

Run #




































This shows that over ten runs, the parallel agents were 66% faster than the sequential agents. This can be seen in the following chart:

Concurrent Client Operation

As concurrent agents are run in the background, you can use your client for other functions. For instance you can read the results from the first two databases, while the remaining 18 populate in the background. You can even do something completely different, such as read mail. The screen shot below shows a client searching at the same time as the user is reading his or her mail.

Code Locking

Code locking (CodeLock/CodeUnLock) statements are generally only used in the Lotus world when running concurrent web agents on a Domino server to perform some function where unique access is required to an object (for instance, incrementing a hit counter in a specific document). Code locking is not used in the standard Agent Manager Run agents, as it is only effective within the same process — the Agent Manager often starts more than one executive (process), so code locking is redundant. Server-run agents initiated from the web run via an Agent Manager add-in, not the Agent Manager, so they run within a single process. In the same way, when a Notes client starts multiple concurrent agents using the "Run in Background Client Thread" setting, all agents run in the same process, so code locking can be successfully used.

If you want to access common objects when using multiple agents (for example to increment counters in a document), you should use the CodeLock LotusScript statements to lock access to the object while using it. This is mandatory to provide a consistent result (for example, setting a counter), and it's also very useful in avoiding client crashes. As long as the scripts are coded to minimize time spent on using the common objects (freeing the locks as soon as possible), this doesn't have a detrimental affect on performance. The take-home message is that if you think there might be contentious use of an object (database, view, document and so on), then lock it.

The following is an example of code locking:

Dim s as new NotesSession
Dim db as NotesDatabase
Dim doc as NotesDocument
Dim lockID as Integer
Dim lockStatus as Integer
lockID = Createlock("SearchLock")
Do While True
If Codelock(lockID) Then
Exit Do ' Got the lock, exit Loop
End If
Set db = s.CurrentDatabase
FT Search Manager, vendor toolsmulti-threadingdocID$ = xxxx 'set Document Unique ID
Set doc = db.GetDocumentByUNID(docID$)
If doc.HasItem("Counter") Then
docNo% = resultHeader.Counter(0)
docNo% = docNo% + 1
doc.Counter = docNo%
doc.Counter = 1
FT Search Manager, vendor toolscode locking, multi-threadingEnd If
Call doc.Save(True, True, True)
lockStatus = Codeunlock(lockID) ' Let other agents get the lock
lockStatus = Destroylock(lockID) ' Destroy the lock of there
are no more agents waiting

More information and examples about locking code can be found in the Domino Designer online Help.

Emulating Browser Behavior

Two common complaints about Notes-based searching is users having to start searching by clicking a button (not just pressing Enter), and having to remember a Notes-based query syntax. These are covered below.

A Workaround to the Notes "Enter" Problem

In Notes search applications (in fact, this commonly applies to any application), the user has to type in their search query, then find the mouse and click a Search button. Alternatively, they can tab to the button and press Space. This is different from browser-based searching where the user types in their query and then just presses Enter to begin the search. This workaround uses a JavaScript timer to locate a Carriage Return in a field, perform an action based on its existence, and then removes it.

The timing in milliseconds can be decreased (shown here as 100 ms, or 1/10 of a second), but at a cost to the processing percentage used by the client (as the client is continually checking the required field).

All events are Client Javascript. "YourSearchField" means the field the cursor is in when the user can just press Enter to click a button (begin a search). For example this might be called "Query". "YourButton" means the button whose code will be executed when the user presses Enter.

YourSearchField onFocus event:

// Check every 1/10 of a second
useClick = window.setInterval("runSearch()",100);

YourSearchField onBlur event:


YourButton: The button (in this example) requires an HTML Name of "Button". This is set on the HTML tab of the button properties dialog.

Form JS Header:

var newline = String.fromCharCode(10);
var useClick;
var sString;
var t_sString;
function runSearch() {
FT Search Manager, vendor toolsbrowser behavior, emulatingsString = document.forms[0].YourSearchField.value;
if (sString.indexOf(newline)>=0) {
t_sString = replace(sString, '\n', '');
document.forms[0].YourSearchField.value = t_sString;
function replace(str, from, to) {
var i = str.indexOf(from);
if (!from || !str || i == -1) return str;
var newstr = str.substring(0, i) + to;
if (i+from.length < str.length)
newstr += replace(str.substring(i+from.length,str.length),from,to);
return newstr;

You may see the client add a line to your Query and then remove it, but remember that this is just a workaround until something better comes along.

Allowing Web-Style Query Syntax

It is confusing for users to use different search query syntax when using Notes instead of the same syntax they use when Web searching. For instance, see the following Google search:

"no-code" -Javascript java "trackback client" OR

This would be represented in Notes as:

NOT "no-code" AND NOT "Javascript" AND java AND "trackback client"
OR re-entered AND array AND string AND "it"

The FT Search Manager uses text parsing to translate web-style queries into Notes syntax, displaying the web-style query to the user while internally using the Notes-style query. This ensures that your users don't need to remember two different search syntaxes.

This procedure is too complicated to show here, but it can be roughly summarized as:

  1. 1. Create an array of all of the search words by splitting the query using " ".

  2. 2. For each element in the array, replace web search operators (+, -, and so on) with the relevant Notes operator (AND, AND NOT), taking care to recognize quoted strings and strings containing operators, for example "re-entered".

  3. 3. Reassemble the query in the Notes syntax making liberal use of parentheses.

For a working example of this LotusScript function, please contact IONET.


IONET are a Wellington, New Zealand based company that have specialized in Lotus Notes and Domino solutions since V3.0 (circa 1993). They concentrate on innovative, low-cost products to enhance the usability of any Lotus Notes/Domino environment.

For more information on IONET or its products, visit: