Property :: lockInstance - Lock instance
In order to prevent other applications accessing the currently selected instance, this function allows locking the instance. The function requires that a persistent instance has been selected or located in the property handle. Before locking an instance, the function checks whether the instance data is up to date or not. When not, the function will refresh the instance in order to obtain the proper instance state.
As long as the instance is locked no other process or thread is able to lock the instance. Locking an instance twice in the same or another application will fail (returns false). Locking an instance does not protect the instance from being read or updated. Instances locked have to be unlocked explicitly. Closing the property handle or deselecting the instance does not unlock the instance. Locks are reset when closing the database or terminating the application.
Locked instances have to be be unlocked by calling unlockInstance().
The function returns true, when locking succeeded and false, when the instance 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 property handle or property handle is invalid.
This feature is dangerous, since remaining locks (e.g. because improper exception handling) may cause system dead locks. Hence, we suggest using locker classes (InstanceLock) instead, 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.
Implementation overview
- Lock instance immediately
Property :: lockInstance ( ) - Lock instance
Property :: lockInstance ( iTimeout )
Implementation details
- to list
-
Lock instance
bool Property :: lockInstance ( int32 iTimeout )
The function locks the instance and waits the number of seconds passed in iTimeout. The function returns true, as soon as the instance could be locked. When the waiting interval has passed without being able to lock the instance, the function returns false.
- iTimeout - Timeout in seconds
to list