Caché ObjectScript Reference
^$LOCK
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Provides lock name information.
Synopsis
^$|nspace|LOCK(lock_name,info_type,pid)
^$|nspace|L(lock_name,info_type,pid)
Parameters
or Optional — An extended SSVN reference, either an explicit namespace name or an implied namespace. Must evaluate to a quoted string, which is enclosed in either square brackets (["nspace"]) or vertical bars (|"nspace"|). Namespace names are not case-sensitive; they are stored and displayed in uppercase letters.
lock_name An expression that evaluates to a string containing a lock variable name, either subscripted or unsubscripted. If a literal, must be specified as a quoted string.
info_type Optional — A keyword specifying what type of information about lock_name to return. Must be specified as a quoted string. The available options are "OWNER", "FLAGS", "MODE", and "COUNTS".
pid Optional — For use with the "COUNTS” keyword. An integer that specifies the process ID of the owner of the lock. If specified, at most one list element is returned for "COUNTS”. If omitted (or specified as 0), a list element is returned for each owner holding the specified lock. pid has no effect on the other info_type keywords.
Description
The ^$LOCK structured system variable returns information about locks in the current namespace or a specified namespace on the local system. You can use ^$LOCK in two ways:
Note:
^$LOCK retrieves lock table information from the lock table on the local system. It will not return information from a lock table on a remote server.
^$LOCK in an ECP Environment
Parameters
nspace
This optional parameter 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("LOSER")   ; a non-existent namespace
 
You can use the $NAMESPACE special variable to determine the current namespace, and the ZNSPACE command to change the current namespace.
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 optional keyword specified as a quoted string.
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 parameter 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
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.
The direction argument specifies whether to return the next or the previous lock name. If you do not provide a direction argument, Caché 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.
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 a Caché-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.
See Also