Codelock explanation required

HCL Domino Domino Forum
1

I’m currently trying to use codelock() but I don’t quite understand how to implement it…I found from this source

http://www-12.lotus.com/ldd/doc/domino_notes/Rnext/help6_designer.nsf/f4b82fbb75e942a6852566ac0037f284/19c98a6c24f0d52185256c54004c4ff6?OpenDocument

And it says something like this, “…If the lock is already held by another agent, the thread stalls until the lock becomes available…”…does this mean it the lock must be in an agent? What does it mean by another agent? Do I require two agents to run a codelock?

Currently, I written the codelock in QuerySave within a form. And the auto number generation in script library…Doesn’t seem to work. I still get duplicates…

2

Subject: Perhaps it would be better if you explain …

what you want to acheive in business terms

and then explain the basic design you have chosen to make that happen

before diving into your current detailed coding.

It may be that an alternative approach is appropriate

3

Subject: RE: Perhaps it would be better if you explain …

Well, basically, I would like to create sequential number for forms in a single server environment. It not a web application though. Duplication of numbers occured previously, so I’m working on solving this issue at the moment.

It seems like there are a lot of suggestions regarding the use of codelock functions to solve multithreading issues. Perhaps, you have better suggestions?

Thanks.

4

Subject: So…

what you have is a single document carrying the current/next sequential number

and what you want is a way to ensure that two (or more) Notes clients are not updating that document at the same time?

In this case I suggest you look at locking the DOCUMENT using the NotesDocument.Lock method

see below for details or (of course) Designer help, However in summary

when a Notes Client executes a NotesDocument.Lock the code attempts to reach the admin server for that app and places a lock on the specified document that stops other Clients doing the same

i.e. it works between ‘threads’ running on separate machines

AND is only associated with one document

That seems to match your needs more closely that CodeLock

as the name implies Codelock is mostly used to stop two agents interfering with one another by running at the same time on the same server.

It achieves this by forcing each to grab control of a “transient” token by name.

Hope this helps … let us know how you get on

Locks a document.

Note This method is new with Release 6.

Defined in

NotesDocument

Syntax

flag = notesDocument.Lock( [ name ] [, provisionalOK ] )

Parameters

name

Array of type String. Optional. The names of the lock holders. Each lock holder must be a user or group. Defaults to one lock holder: the effective user. The empty string (“”) is not permitted in the array.

provisionalOK

Boolean. Optional.

True permits the placement of a provisional lock.

False (default) does not permit a provisional lock.

Return value

flag

Boolean.

True if the lock is placed.

False if the lock is not placed.

Usage

IsDocumentLockingEnabled in NotesDatabase must be True or this method raises an error.

This method:

Places a persistent lock if the administration (master lock) server is available.

Places a provisional lock if the administration server is not available and the second parameter is True.

Raises an error if the administration server is not available and the second parameter is False.

The following actions occur depending on the current lock status:

If the document is not locked, this method places the lock and returns True.

If the document is locked and the current user is one of the lock holders, this method returns True.

If the document is locked and the current user is not one of the lock holders, this method returns False.

If the document is modified by another user before the lock can be placed, this method raises an error.

5

Subject: RE: So…

does this method work when I creating a new document? meaning to say that a new document will be created with a new number…I just want to make sure there are no duplicate number…

i am now trying to recode based on your suggestion…will let you know my progress…

thanks

6

Subject: Stepping back a moment…

perhaps I’ve made a wrong assumption about how your sequential numbering work.

Obviously you have a lot of documents that you want to have their own unique number on them - lets call these the data documents.

The important thing is that the unique numbers are assigned sequentially in the order that the documents are created.

I had assumed you had another document - a unique single document - with a counter field holding the last number used.

When you create a new data document, you run code in the query open that

  1. finds the counter document (in a view?)

  2. Gets a lock on it (the counter NOT the new document)

3 reads the counter value

  1. places it in the unique number field on the data document

  2. increments the counter value by one

  3. saves the counter document so that the next new documents gets the next value)

  4. releases the lock

  5. continues with editing the new document

Alternatively, you might be doing something similar in the Post Save

If you are doing something different, let me know what

and we can go from there

7

Subject: RE: Stepping back a moment…

currently, i’m using a codelock function in querysave, then call another function to increments the number by getting the counter from a view, which will return the value to querysave, then release the lock in querysave.

i just use codelock function…didn’t use agents…which i’m not sure if it’s ok. i’m still getting duplicates using my method.

when you mentioned “Gets a lock on it (the counter NOT the new document)”…it seems to me that codelock is the way to go, not notesdocument.lock…or i have misunderstood the concept?

thanks so much for your responses. i couldn’t appreciate more.

8

Subject: RE: Stepping back a moment…

You’re on the right track. Alan assumed you were using a numbering document, not a view lookup. There is a non-zero time interval between the time that one user creates a document and another one sees it in a view, so the lookup method can easily result in duplicates in a busy application. That’s one of the reasons why a separate document, writable by all users, is often used to store the current (or next) document number. It’s easy to lock and release a document, and the lock is first-come, first-served and simultaneous across connected replicas when a master lock server is in use (the “you have a lock” message is not returned until the doc is locked everywhere). Duplicates can still occur in disconnected replicas, though, but using a separate locks database that only exists on one server (and explicitly calling it by server and filename in your code) can solve that as well.

9

Subject: we were talking about a different architecture

to meet the same basic requirement. :slight_smile:

In this case we both were trying for a sequential numbering system requirement

but my architecture was for a separate count record

while yours was to try find the next number from the list of numbers to be found on teh existing data documents.

Theoretically both look good -

however for several reasons including those outlined by Stan

mots Notes developers tend to favour the separate counter document.

basically its difficult to ensure that any Note view contains all documents.

Additiobally the document lock mechanism makes the counter doc method quite robust.

As to using codelock

I can only repeat my understanding that Codelock only works with ‘threads’ executing on the same machine

while document lock will work between separate client machines

because each client will try for a lock on the document on the server.

Stan is again correct that the situation becomes complicated if there are replicas on several servers

and even more complicated if users are allowed to use local replicas and work offline :frowning:

but you had indicated your current application was one server, Notes client only, no online working

so my first choice was a straightforward design