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). Collections locked have to be unlocked explicitly. Closing the property handle does not unlock the collection. Locks are reset when closing the database or terminating the application.
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.
This feature is dangerous, since remaining logs (e.g. because improper exception handling may cause system dead locks. Hence, we suggest using locker classes (like CollectionLock) instaed, which are automatically destructed when leaving the function, which will unlock the locked resource.
Nevertheless, lock functions might be used, when lock and unlock are called in different functions, which cannot be avoided, sometimes.
The value is true when the function was executed successfully. Otherwise the value is set to false.