webCOMAND

cObject::lock_object()

Locks the object for a user in the current repository session.  While the object is locked, other users will not be able to lock the same object, in this or other sessions.  This user will also not be able to lock the same object in other sessions.  However, this method has no effect (and will return TRUE) if the user already possesses the lock in the same session.

By default, it will return FALSE immediately if the object is locked by another user or the same user in another session.  An optional timeout can be set to block until the object is unlocked for at most the specified number of seconds. 

The timeout is approximate; a timeout of 0 will guarantee that this will try at most once to obtain a lock, but individual attempts may take time depending on the timely return of the internal locking mechanism within the storage engine.  The timeout will therefore be treated as approximate, and can exceed the specified number of seconds.

Prototype

bool lock_object(array $options = [])

Parameters

  • options - Associative array of key/value pairs with the following recognized keys.
    • Timeout - The optional timeout (in seconds). If 0 (the default), FALSE will be returned immediately if the object is already locked by another repository user.
    • User - The User (object) to lock on behalf of.  If not provided, the current "user of record" for the object's repository connection will be used.

Return

TRUE if the lock was successfully obtained, otherwise FALSE.

Example

$repo = comand::repo();
$user = $repo->get_first('FROM User WHERE Username='admin' LIMIT 1');
$contact = $repo->get_first('FROM Contact LIMIT 1');
$locked = $contact->lock_object([
    'Timeout' => 3,   // wait up to 3 seconds to get lock
    'User' => $user, // lock on behalf of admin user
]);
if(!$locked) {
    echo("Could not get lock.\n");
    exit();
}
$contact->LastName = 'New Name';
$contact->approve();
$contact->unlock_object([
    'User' => $user, // unlock on behalf of admin user
]);

Related

unlock_object()