Acquire a PSL process lock.







name of the lock that should be acquired


optional control permitted under the lock*Valid Values* 
s shared 
r reader 
w writer 
x exclusive 
x (If the first letter of mode is not srw, or x, a run-time error occurs and mode defaults to x(exclusive).)


optional integer value that specifies the number of seconds before the lock request expires*Valid Values*

  • timeout > 0 number of seconds the lock request is valid
  • timeout = 0 means nonblocking lock request
  • timeout < 0 means infinite timeout period

-1 (Infinite timeout)


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


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");

Was this page helpful? Yes No Submitting... Thank you