%SYS.LockQuery

abstract class %SYS.LockQuery extends %SYSTEM.Help [ Final ]

Provide Interface for users to read lock table information in the system. SYS.Lock is used to perform management operations.

Filter Specification

The argument to the Rset.Execute() method selects which subset of the current locks to return. The first character of the 'id' argument determines the category of the locks to be collected. This has various forms as described below.
1) Null String or "*" - All locks. When the 'id' is a null string (default value when no id specified) or "*", it collects all locks in the lock table. Example:

  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks in lock table.
  Do Rset.Execute("")
   
  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks in lock table.
  Do Rset.Execute()

2) 'P' or numeric - Process ID. Collect all locks owned by the job with the specified process ID. If the 'id' is a numeric value without a leading 'P', it is treated as a process ID.
For all systems the process ID is in decimal form.
Example:

  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by a process whose process ID is 2004.
  Do Rset.Execute("P2004")
   
  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by a process whose process ID is 2004.
  Do Rset.Execute("2004")

3) 'J' - Internal job number. Collect all locks owned by the job with the specified internal job number.
Example:

  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by a process whose internal job number is 20.
  Do Rset.Execute("J20")

4) 'C' - Remote client system Name. Collect all locks owned by the remote client system with the specified name.
The Name can be one of the names displayed in the 'Process ID' column of the ^LOCKTAB utility.
When the string following the leading 'C' is empty, it collects all locks owned by jobs of the local system.
Example:

  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by jobs of local system.
  Do Rset.Execute("C")
   
  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by remote client named 'SystemA'.
  Do Rset.Execute("CSystemA")

5) 'S' - Remote server system Name. Collect all locks sent to the specified remote system.
When the string following the leading 'S' is empty then it collects all locks kept on the local system.
Example:

  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks on the local system.
  Do Rset.Execute("S")
   
  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks sent to remote server named 'SystemA'.
  Do Rset.Execute("SSystemA")

6) 'N' - Network Protocol. Collect all locks owned by the remote client system through the network protocol. The protocol can be:

"ECP" - The owner is an ECP remote client system.
"" - The owner is a remote client system of any protocol.

Example:

  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by remote ECP clients.
  Do Rset.Execute("NECP")
   
  Set Rset=##class(%ResultSet).%New("%SYS.LockQuery:List")
  //Collect all locks owned by remote clients.
  Do Rset.Execute("N")

Method Inventory

AnyRemoteOwnedLocks()

Methods

classmethod AnyRemoteOwnedLocks(NetType As %String = "") as %Boolean

Check if any remote system owns any lock in the system.
Return TRUE(1) if there is any lock owned by the specified network type, otherwise return FALSE(0).

The NetType argument specifies the network type of the remote system.
It has following value:

"NECP" - The remote system owned the lock through ECP network.
"N" or "" - The null string (Default) means any network type.

For un-recognized network type this method will return FALSE.
Example:

  // Return 1 if any lock is owned by remote ECP client.
  Set rc=##Class(%SYS.LockQuery).AnyRemoteOwnedLocks("NECP")
   
  // Return 1 if any lock is owned by any remote client.
  Set rc=##Class(%SYS.LockQuery).AnyRemoteOwnedLocks("N")

Queries

query Conflicts(LockRef As %String = "")

Selects DelKey As %String, Owner As %String, Mode As %String, Flags As %String, Counts As %String, Sfn As %Integer, LockString As %String, FullReference As %String, WaiterPID As %String, WaiterMode As %String, WaiterType As %String, RemoteOwner As %Boolean

Gets all lock entries that may conflict with the lock reference specified in LockRef if an exclusive lock on that reference were to be attempted.

LockRef is a string that contains the quoted lock reference (quoted by the $NAME function if desired), and is taken as a reference in the current namespace. Extended reference may also be used to specify a different namespace or system^directory.

The output columns are similar to the output column in Detail query except 'EscalateInfo' is not included. See the Detail query description for each column.

Notes:

If the lock reference is subject to subscript level mapping, then the result set may include results from multiple databases due to the implicit duplication of locks to multiple subscript level mapping targets.

The result set will include locks owned by the calling process itself.

The result set can include locks that are both lower or higher than LockRef in the lock tree (ancestors and descendants), as well as an exact match.

The result set can also include locks that are not direct descendants of LockRef if there are waiters waiting for a parent. For example, if LockRef = $NAME(^X("abc",1)) and there is a waiter waiting for ^X("abc") due to a lock held on ^X("abc",2), then ^X("abc",2) will be included in the result set with a waiter of type "P". As with the other queries, ^X("abc") itself is not returned in the results because it has not yet been acquired.

query Detail(id As %String = "")

Get detail columns for lock table entries.

DelKey: A key to be used for SYS.Lock.DeleteOneLock() to remove the lock (row).

Owner: Owner of the lock item. For local system owner it is Process ID (in decimal form). For remote client owner, it is the client system name. For share lock there can be more than one owner, and they are separated by ','.

Mode: Lock mode of the lock item. It can be:

'X' - exclusive lock.
'S' - share lock.
'ZAX' - ZALLOCATE type lock.

Flags: Attribute of the lock item. It can be:

'*' - to remote server.
'D' - Lock is in Delock Pending state, waiting for server to release the lock.
'P' - Lock is in Lock Pending state, waiting for server to grant the lock.
'L' - Lock is lost due to network reset.
'Z' - Lock granted by ZA command. The ZA and ZD commands are obsolete, though the network daemons still grant the locks for remote client with the ZA lock mode internally.

Counts: Lock count of the lock item. The format depends on the lock mode:

For 'X' mode - it is the lock count for the exclusive lock. If the owner also locked it with share mode, the share lock count will be separated with '|' from exclusive lock count, for example, "2|1" means 2 'X' count and 1 'S' count.
For 'S' mode - it is the lock count for the share lock. There can be more than one owner for share lock, so the lock count is separated with ',' between each owner. For example, "1,3,4" means first owner has lock count 1, second owner has lock count 3 and third owner has lock count 4.
For 'ZAX' mode - the Counts will be null string if the owner does not own it with share mode. Otherwise the share lock count will be separated by '|'. For example, "|3" the owner locked it with 'ZAX' mode and 'S' mode with lock count 3.

Sfn: System File Number of the lock item. It tells in which database this lock is located, in internal system file number form.

LockString: Lock reference string of the lock item. This does not include the database name.

FullReference: Full lock reference string of the lock item. This includes the database and system name (if remote lock).

WaiterPID: Waiter of the lock item. This has the same format as Owner. There can be more than one waiter of the lock and they are separated by ','.

WaiterMode: Lock mode the waiter is waiting for. It can be:

'X' - Waiting for exclusive lock mode.
'S' - Waiting for share lock mode.
'Z' - Waiting for ZALLOCATE lock mode.

WaiterType: Which node the waiter is waiting for. It can be:

'E' - Exact node. It is waiting for the same lock node.
'P' - Parent node. It is waiting for a parent node.
'C' - Child node. It is waiting for a child node.

RemoteOwner: A boolean value, TRUE means one of the lock owner(s) is remote.

EscalateInfo: A series of counters if the lock node involved lock escalation. A null string if no lock escalation is involved. Each owner has its own set of counters separated by ','. The counters are for internal use.

query List(id As %String = "")

Selects DelKey As %String, Owner As %String, Mode As %String, Flags As %String, Counts As %String, Sfn As %Integer, LockString As %String, FullReference As %String

Get short information of each lock entry.
See the Detail query description for each column.

Inherited Members

Inherited Methods

Help()