timeout

The number of seconds or fractions of a second to wait for a lock request to succeed before timing out. timeout is an optional argument. If omitted, the LOCK command waits indefinitely for a resource to be lockable; if the lock cannot be applied, the process will hang. The syntax for timeout is a mandatory colon (:), followed by an numeric value or an expression that evaluates to an numeric value.

Valid values are seconds with or without fractional tenths or hundredths of a second. Thus the following are all valid timeout values: :5, :5.5, :0.5, :.5, :0.05, :.05. Any value smaller than :0.01 is parsed as zero. A value of zero invokes one locking attempt before timing out. A negative number is equivalent to zero.

Commonly, a lock will wait if another process has a conflicting lock that prevents this lock request from acquiring (holding) the specified lock. The lock request waits until either a lock is released that resolves the conflict, or the lock request times out. Terminating the process also ends (deletes) pending lock requests. Lock conflict can result from many situations, not just one process requesting the same lock held by another process. A detailed explanation of lock conflict and lock request wait states is provided in Lock Management.

If you use timeout and the lock is successful, InterSystems IRIS sets the $TEST special variable to 1 (TRUE). If the lock cannot be applied within the timeout period, InterSystems IRIS sets $TEST to 0 (FALSE). Issuing a lock request without a timeout has no effect on the current value of $TEST. Note that $TEST can also be set by the user, or by a JOB, OPEN, or READ timeout.

The following example applies a lock on lock name ^abc(1,1), and unlocks all prior locks held by the process:

  LOCK ^abc(1,1)

This command requests an exclusive lock: no other process can simultaneously hold a lock on this resource. If another process already holds a lock on this resource (exclusive or shared), this example must wait for that lock to be released. It can wait indefinitely, hanging the process. To avoid this, specifying a timeout value is strongly recommended:

  LOCK ^abc(1,1):10

If a LOCK specifies multiple lockname arguments in a comma-separated list, each lockname resource may have its own timeout (syntax without parentheses), or all of the specified lockname resources may share a single timeout (syntax with parentheses).

Without Parentheses: each lockname argument can have its own timeout. InterSystems IRIS parses this as multiple independent LOCK commands, so the timeout of one lock argument does not affect the other lock arguments. Lock arguments are parsed in strict left-to-right order, with each lock request either completing or timing out before the next lock request is attempted.
With Parentheses: all lockname arguments share a timeout. The LOCK must successfully apply all locks (or unlocks) within the timeout period. If the timeout period expires before all locks are successful, none of the lock operations specified in the LOCK command are performed, and control returns to the process.

InterSystems IRIS performs multiple operations in strict left-to-right order. Therefore, in LOCK syntax without parentheses, the $TEST value indicates the outcome of the last (rightmost) of multiple lockname lock requests.

In the following examples, the current process cannot lock ^a(1) because it is exclusively locked by another process. These examples use a timeout of 0, which means they make one attempt to apply the specified lock.

The first example locks ^x(1) and ^z(1). It sets $TEST=1 because ^z(1) succeeded before timing out:

  LOCK +^x(1):0,+^a(1):0,+^z(1):0

The second example locks ^x(1) and ^z(1). It sets $TEST=0 because ^a(1) timed out. ^z(1) did not specify a timeout and therefore had no effect on $TEST:

  LOCK +^x(1):0,+^a(1):0,+^z(1)

The third example applies no locks, because a list of locks in parentheses is an atomic (all-or-nothing) operation. It sets $TEST=0 because ^a(1) timed out:

  LOCK +(^x(1),^a(1),^z(1)):0

locktype