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):

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

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 (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
'***GET LOCK
lockID = Createlock("SearchLock")
Do While True
If Codelock(lockID) Then
Exit Do ' Got the lock, exit Loop
End If
Loop
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%
Else
doc.Counter = 1
FT Search Manager, vendor toolscode locking, multi-threadingEnd If
Call doc.Save(True, True, True)
'***END LOCK
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.

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:

window.clearInterval(useClick);

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;
document.forms[0].elements['Button'].click();
}
}
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.

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
re-entered+array+string+it

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:

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