Learning
Documentation
Community
Open Exchange
Global Masters
Home / Class Reference / ENSLIB namespace / %SYS.LockQuery
Private  Storage   

%SYS.LockQuery


abstract class %SYS.LockQuery extends
%SYSTEM.Help

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

Inventory


Parameters Properties Methods Queries Indices ForeignKeys Triggers
18 4


Summary


Methods
AnyRemoteOwnedLocks Help


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 Detail(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, WaiterPID As %String, WaiterMode As %String, WaiterType As %String, RemoteOwner As %Boolean, EscalateInfo 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.