lock()

Acquire a PSL process lock.

Syntax

lock(lockname,[mode],[timeout])

Parameter

Parameter	Definition
lockname	name of the lock that should be acquired
mode	optional control permitted under the lockValid Values s shared r reader w writer x exclusive Default x (If the first letter of mode is not s, r, w, or x, a run-time error occurs and mode defaults to x(exclusive).)
timeout	optional integer value that specifies the number of seconds before the lock request expiresValid Values timeout > 0 number of seconds the lock request is valid timeout = 0 means nonblocking lock request timeout < 0 means infinite timeout period Default -1 (Infinite timeout)

Description

The lock() function requests a lock with name lockname. The mode of the request specifies either shared (reader) or exclusive (writer) access under the lock. The optional timeout specifies the number of seconds the request is valid.

The default behavior of lock() function is to request an exclusive lock with an infinite timeout period. The lock() function returns 1 for success and 0 for failure.

PATROL Locks and PSL

Lock names are global to the PATROL Agent; thus,

all PSL processes share the same table of locks
different PSL processes can share parameter lock names to perform concurrent actions

There is no way to enforce lock-naming scope--BMC Software recommends that lock names in PSL scripts be uniquely encoded using the name of the application. This practice will avoid potential clashes with other PSL scripts.

Shared Lock Requests

Shared lock requests for a lock that is currently in share mode are granted--unless there is a waiting write request. Giving priority to a waiting write request prevents the lock mechanism from starving write processes.

Requests for Locks Already Held

It is possible to request a lock that you already hold, although it is not good style:

requesting a lock that you already hold is ignored
requesting a shared lock on a lock you already hold with exclusive access is also ignored

Requesting an upgrade to exclusive access of a lock currently held as shared succeeds and upgrades the lock provided you are the only process that is using the shared lock. If you are not the only process using the lock, the lock() function immediately returns 0 in non-blocking mode (regardless of the value of timeout because blocking would cause immediate deadlock by waiting for yourself!).

Rather than using this upgrade feature, BMC Software recommends that you call the unlock() function to release the shared lock before attempting to acquire the new exclusive lock. Lock tracing is possible using the PslDebug variable (see PslDebug-Run-Time-Error-Checking-Variable).PslDebug can be useful in debugging multiprocess lock interactions.

Failure of the lock Function

The lock() function can fail if

nonblocking request fails
timeout is exceeded before the lock is granted

The lock() function can fail for an infinite timeout if

special-case upgrade request is granted
system has performed some external deadlock correction

Example

The following example uses the lock() function to request a read lock, waiting up to three minutes to acquire the lock:

if (lock("PASSWD_FILE_LOCK","w",180)) {
print("Got the lock\n");
} else {
print("Did not get it\n");
}