Property :: lockCollectionForUpdate - Lock collection

In order to prevent other applications updating a collection managed by the property handle, this function allows locking the collection. As long as the collection is locked no other process or thread is able to lock or update the collection. Locking a collection does not protect the collection from being read.

Locking a collection for update in the same thread more than once is possible without throwing an error or exception. When already being locked, the function returns false. Locking a collection in a thread or process while the collection is locked for update will fail (returns false).

Update-locked collections can be unlocked by calling unlockCollectionforUpdate().

The function returns true, when locking succeeded and false, when the collection is already locked. The function must not be called from within context class event handlers, which will cause an exception. The function also throws an exception, when the property does not handle a collection or when no instance is selected in the parent property handle or property handle is invalid.

When closing the property handle completely, i.e. when closing the last property handle referring to the same cursor object (e.g. created by calling use()), the collection will be unlocked for update when not yet done by the application. Because cursor copies (created by calling cursorCopy()) will automatically be destroyed when destroying the owning cursor object by closing the last referring property handle, locks initiated by copy cursors are also released.