Provides lock name information.
Arguments
nspace
This optional argument allows you to specify a global in another namespace by using an extended SSVN reference. You can specify the namespace name either explicitly, as a quoted string literal or as a variable, or by specifying an implied namespace. Namespace names are not case-sensitive. You can use either bracket syntax ["USER"] or environment syntax |"USER"|. No spaces are allowed before or after the nspace delimiters.
You can test whether a namespace is defined by using the following method:
WRITE ##class(%SYS.Namespace).Exists("USER"),! ; an existing namespace
WRITE ##class(%SYS.Namespace).Exists("TESTNAMESPACE1") ; a non-existent namespace
You can use the $NAMESPACE special variable to determine the current namespace. The preferred way to change the current namespace is NEW $NAMESPACE then SET $NAMESPACE="nspacename".
lock_name
An expression that evaluates to a string containing a lock variable name, either subscripted or unsubscripted. A lock variable (commonly a global variable) is defined using the LOCK command.
info_type
An info_type keyword is required when ^$LOCK is invoked as a stand-alone function, it is optional when ^$LOCK is used as an argument to another function. The info_type must be specified in capital letters as a quoted string.
-
"OWNER" returns the process ID (pid) of the owner(s) of the lock. If the lock is a shared lock, it returns the process IDs of all of the owners of the lock as a comma-separated list. If the specified lock does not exist, ^$LOCK returns the empty string.
-
"FLAGS" returns the state of the lock. It can return the following values: "D" — in delock pending state; "P" — in lock pending state; "N" — this is a node lock, the descendants are not locked; "Z" — this lock is in ZAX mode; "L" — lock is lost, the server no longer has this lock; "*" — this is a remote lock. If the specified lock is in a normal lock state, or does not exist, ^$LOCK returns the empty string.
-
"MODE" returns the lock mode of the current node. It returns 'X' for exclusive lock mode, 'S' for shared lock mode, and 'ZAX' for ZALLOCATE lock mode. If the specified lock does not exist, ^$LOCK returns the empty string.
-
"COUNTS" returns the lock counts for the lock, specified as a binary list structure. For an exclusive lock, the list contains one element; for a shared lock the list contains an element for each owner of the lock. You can use the pid argument to return only the list element for a specified owner of the lock. Each element contains the owner's pid, the exclusive mode increment count, and the shared mode increment count. If both the exclusive and shared mode increment counts are 0 (or " "), the lock is in 'ZAX' mode. An increment count may be followed by a 'D' to indicate that the lock has been unlocked in the current transaction, but its release is delayed ('D') until the transaction is committed or rolled back. If the specified lock does not exist, ^$LOCK returns the empty string.
The info_type keyword must be specified in all capital letters. Specifying an invalid info_type keyword generates a <SUBSCRIPT> error.
pid
A process ID of the owner of a lock. Only meaningful when using the "COUNTS" keyword. Used to limit the "COUNTS" return value to (at most) one list element. The pid is specified as an integer on all platforms. If the pid matches the process ID of an owner of lock_name ^$LOCK returns that owner's "COUNTS” list element; if pid does not match the process ID of an owner of lock_name ^$LOCK returns the empty string. Specifying pid as 0 is the same as omitting pid; ^$LOCK returns all "COUNTS" list elements. The pid argument is permitted with the "OWNER", "FLAGS", or "MODE" keyword, but is ignored.
Examples
The following example shows the values returned by info_type keywords for an exclusive lock:
LOCK ^B(1,1) ; define lock
WRITE !,"lock owner: ",^$LOCK("^B(1,1)","OWNER")
WRITE !,"lock flags: ",^$LOCK("^B(1,1)","FLAGS")
WRITE !,"lock mode: ",^$LOCK("^B(1,1)","MODE")
WRITE !,"lock counts: "
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; delete lock
The following example shows how the value returned by info_type "COUNTS" changes as you increment and decrement an exclusive lock:
LOCK ^B(1,1) ; define exclusive lock
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK +^B(1,1) ; increment lock
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK +^B(1,1) ; increment lock again
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; decrement lock
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; decrement lock again
ZZDUMP ^$LOCK("^B(1,1)","COUNTS")
LOCK -^B(1,1) ; delete exclusive lock
The following example shows how the value returned by info_type "COUNTS" changes as you increment and decrement a shared lock:
LOCK ^S(1,1)#"S" ; define shared lock
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK +^S(1,1)#"S" ; increment lock
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK +^S(1,1)#"S" ; increment lock again
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK -^S(1,1)#"S" ; decrement lock
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK -^S(1,1)#"S" ; decrement lock again
ZZDUMP ^$LOCK("^S(1,1)","COUNTS")
LOCK -^S(1,1)#"S" ; delete shared lock
The following examples show how to use ^$LOCK as an argument to the $DATA, $ORDER, and $QUERY functions.
As an Argument to $DATA
$DATA(^$|nspace|LOCK(lock_name))
^$LOCK as an argument to $DATA returns an integer value that specifies whether the lock name exists as a node in ^$LOCK. The integer values that $DATA can return are shown in the following table.
Value |
Meaning |
0 |
Lock name information does not exist |
10 |
Lock name information exists |
Note that $DATA used in this context can only return 0 or 10, with 10 meaning that the specified lock exists. It cannot determine if a lock has descendents, and cannot return 1 or 11.
The following example tests for the existence of a lock name in the current namespace. The first WRITE returns 10 (lock name exists), the second WRITE returns 0 (lock name does not exist):
LOCK ^B(1,2) ; define lock
WRITE !,$DATA(^$LOCK("^B(1,2)"))
LOCK -^B(1,2) ; delete lock
WRITE !,$DATA(^$LOCK("^B(1,2)"))
As an Argument to $ORDER
$ORDER(^$|nspace|LOCK(lock_name),direction)
^$LOCK as an argument to $ORDER returns the next or previous ^$LOCK lock name node in collating sequence to the lock name you specify. If no such lock name exists as a ^$LOCK node, $ORDER returns a null string.
Locks are returned in case-sensitive string collation order. Subscripts of a named lock are returned in subscript tree order, using numeric collation.
The direction argument specifies whether to return the next or the previous lock name. If you do not provide a direction argument, InterSystems IRIS returns the next lock name in collating sequence to the one you specify. For further details, refer to the $ORDER function.
The following subroutine searches the locks in the SAMPLES namespace and stores the lock names in a local array named LOCKET.
LOCKARRAY
SET lname=""
FOR I=1:1 {
SET lname=$ORDER(^$|"SAMPLES"|LOCK(lname))
QUIT:lname=""
SET LOCKET(I)=lname
WRITE !,"the lock name is: ",lname
}
WRITE !,"All lock names listed"
QUIT
As an Argument to $QUERY
$QUERY(^$|nspace|LOCK(lock_name))
^$LOCK as an argument to $QUERY returns the next lock name in collating sequence to the lock name you specify. If there is no next lock name defined as a node in ^$LOCK, $QUERY returns a null string.
Locks are returned in case-sensitive string collation order. Subscripts of a named lock are returned in subscript tree order, using numeric collation.
In the following example, five global lock names are created (in random order) in the current namespace.
LOCK (^B(1),^A,^D,^A(1,2,3),^A(1,2))
WRITE !,"lock name: ",$QUERY(^$LOCK(""))
WRITE !,"lock name: ",$QUERY(^$LOCK("^C"))
WRITE !,"lock name: ",$QUERY(^$LOCK("^A(1,2)"))
$QUERY treats all global lock variable names, subscripted or unsubscripted, as character strings and retrieves them in string collating order. Therefore, $QUERY(^$LOCK("")) retrieve the first lock name in collating sequence order: either ^$LOCK("^A”) or an InterSystems IRIS-defined lock higher in the collating sequence. $QUERY(^$LOCK("^C")) retrieves the next lock name in collating sequence after the nonexistent ^C: ^$LOCK("^D”). $QUERY(^$LOCK("^A(1,2)")) retrieve ^$LOCK("^A(1,2,3)”) which follows it in collation sequence.