Duffbert's Random Musings

Document Number:  7003259

Abstract

This paper is intended to give a brief overview of document locking, which is a new feature beginning with Notes Domino 6 (ND6). Document locking is a way to dramatically reduce replication/save conflicts, and to otherwise ensure that when one user is editing a document, no one else will try to do so. If the document is in a database replicated amongst Domino 6 servers that communicate easily with one another, then the feature works very smoothly. If some of the servers are extremely remote, or

Content
This paper is intended to give a brief overview of document locking, which is a new feature beginning with Notes Domino 6 (ND6).

Document locking is a way to dramatically reduce replication/save conflicts, and to otherwise ensure that when one user is editing a document, no one else will try to do so.  If the document is in a database replicated amongst Domino 6 servers that communicate easily with one another, then the feature works very smoothly.  If some of the servers are extremely remote, or are in different domains and do not communicate directly with each other, or the system is a mix of R5 and Domino 6, then various problems will ensue.

How to enable document locking

-        Enable the feature called "Allow document locking" on the first tab of the Database Properties dialog box
-        The database needs to be ODS 43 (ND6)
-        You will need to have an administrative server selected in the ACL
-        You do not need to compact the database

What happens once document locking is enabled

Once enabled, you will find that every time you edit a document, the status bar indicates, "Document successfully locked."  Likewise, when saving/closing a document, "Document successfully unlocked" is written to the status bar.  This requires no extra steps for your users.  Behind the scenes, whenever the document is put in/out of edit mode, two fields are written to: $Writers and $WritersDate.  The first field is a read/write access names field, the same as an AuthorNames field.  The second field is a time/date stamp.  These fields are used to let the system know that the document is locked.  When unlocked, these fields are blanked out.

Note that you can alternatively lock/unlock a document via the Actions menu (or right-click and choose Lock/Unlock from the pop-up menu).  If you lock a document this way, it remains locked until you unlock it.  If you lock a document implicitly by simply editing the document, it unlocks automatically when you come out of edit mode.

If the database has no replica copies, then using this feature is trivial.  But let us assume that there are replica copies on multiple servers.  In that case, when you try to edit a document, the server makes a call to the administrative server to make sure that this document is not locked.  If it is locked, you are given an appropriate error message.  If it is not locked, then you are given the lock.  For this reason, it is critical to the smooth functioning of this feature that the servers can all communicate with the administrative server easily.  If they cannot, or if that communication is slow, then your users will experience a host of problems, from incomplete error messages to an inability to edit/save the document.

Note that the feature can handle local and dial-up access.  It gives the user a message to the effect that it will try to synchronize the edits when connected, and will generate a rep/save conflict only if necessary.  The user will get an email message with the results of this attempt.

What happens in a mixed environment

-        R5 client trying to edit an unlocked document.  This is not a problem.
-        R5 client trying to edit a locked document.  Client generates an error message on save, cannot save edits.
-        Web browser trying to edit an unlocked document.  This is not a problem.
-        Web browser trying to edit a locked document.  Rep/Save conflict, if appropriate.  No error messages.  Note that you could program something into your form, or in a WebQueryOpen agent, to check for $Writers and give a warning to web users if a value is found in that field.
-        ND6 client trying to edit a document on an R5 server.  The following error message displays:
"Server does not support this version of the network protocol."
Note that your ND6 client will have the menu option to Lock/Unlock, but the server is not able to support that call.

In summary, this is a very smooth feature if the database replicates among Domino 6 servers that can easily communicate with each other, and if the users have ND6 clients.  If your system is not set up this way, you should do appropriate testing to ensure that you can at least train your users as to what error messages or problems they may encounter.