Parameters

tblName

The name of the table to lock

searchesOnly

If this parameter is true, the lock blocks only searches, and all updates may proceed unaffected by the lock.

recursive

If this parameter is true, the lock is a counting lock.

exclusive

If this parameter is true, the lock will fail on a locked table unless the lock is also recursive and keyed.

keyed

If this parameter is true, a key will be generated which can be used to perform operations on tables even though they are locked.

l

A NetricsLock object which will pass the lock key to the table. If the table is locked with a lock key and this parameter is not passed with the matchine key, the operation will fail.

Return Value

A NetricsLock object which contains the keyed lock. It can be passed to other methods to operate on the locked table. Operations will only succeed if this lock object is specified.

These commands block and unblock operations on a table. If a number of updating commands are to be run on a given table, these commands are useful for making sure that no lookups take place until the whole sequence of updates is complete. (Otherwise, it is possible that lookups or other operations could occur between update commands.)

Table locks have several optional properties which may be useful in different situations.

With no options, the tbllock command implements a simple toggle lock. Attempts to set or unset the lock always succeed, provided that no other types of locks are in use. A toggle lock only has two states, locked or unlocked. If you were to set the lock twice, and then unset it once, the table would be unlocked.

In contrast, a recursive lock is a counting lock. When locked with a recursive lock, the table will not become unlocked until the number of unlock operations match the number of lock operations. This kind of lock can be useful in environments with updates coming from multiple independent sources. Client A can set a recursive lock, and begin adding new records. Client B can also set a recursive lock and begin adding records. The table will not become unlocked until both clients A and B have released their locks. To create a recursive lock, pass the recursive parameter a value of true.

An exclusive lock is another type of lock which may be useful when updates are coming from multiple sources. Unlike a recursive lock, attempts to lock a locked table with an exclusive lock will return with an error. When using exclusive locks, client A may set an exclusive lock and begin adding new records. When client B attempts to acquire a lock, it will fail and need to wait and try again when client A has released the lock. To create an exclusive lock, pass the exclusive parameter a value of true.

Database locks may also be keyed. When the keyed parameter is set to true, a keyed lock will be created. It will be returned to the caller in the NetricsLock object. The use of the key in any NetricsServerInterface method will allow that method to succeed, even though the table is locked. When a keyed lock is used, the key must be used to unlock the table. Unlike an unkeyed lock, a keyed lock is allowed to be both recursive and exclusive.

Lock types may not be mixed on a single table at a single time. Attempts to acquire a lock on a locked table with differing locking options will always fail. Any locking options used in a lock command must also be used in a corresponding unlock command to ensure that the unlock operation matches the lock operation.