%SYS.LockQuery

Class %SYS.LockQuery Extends %SYSTEM.Help [ Abstract, Final, SqlTableName = "", StorageStrategy = "", System = 4 ]

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

Methods

AnyRemoteOwnedLocks

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

ClientSysNameToSysNum

ClassMethod ClientSysNameToSysNum(SysName As %String = "") As %Integer [ Internal, Private ]

Convert a remote client system name to internal system number.

ClientSysNumToSysName

ClassMethod ClientSysNumToSysName(SysNum As %Integer = 0) As %String [ Internal, Private ]

Convert a remote client system number to client system name.

CommonExecute

ClassMethod CommonExecute(ByRef qHandle As %Binary, id As %String, Flag As %Integer) As %Status [ Internal, Private ]

Common Execute codes for List and Detail query.

GetLockSysNameTable

ClassMethod GetLockSysNameTable(ByRef SYSTEMS As %String, ByRef BYTES2 As %String, ByRef SYSN2 As %String) As %Status [ Internal, Private ]

Get lock system number and name translation table.

TranslateID

ClassMethod TranslateID(id As %String) As %String [ Internal, Private ]

Translate the input ID string and return four values separated by commas.

1. pid : The process ID, 0 - all processes.
2. clin: The remote client system number, -1 - all remote systems.
3. ntype: The network protocol from remote client, 100 - all network protocols.
4. svrn: The remote server system number, -1 - all remote systems.

DetailExecute

ClassMethod DetailExecute(ByRef qHandle As %Binary, id As %String = "") As %Status [ Internal ]

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.

DetailFetch

ClassMethod DetailFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = DetailExecute ]

DetailClose

ClassMethod DetailClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = DetailExecute ]

ListExecute

ClassMethod ListExecute(ByRef qHandle As %Binary, id As %String = "") As %Status [ Internal ]

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

ListFetch

ClassMethod ListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = ListExecute ]

ListClose

ClassMethod ListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = ListExecute ]

WebListExecute

ClassMethod WebListExecute(ByRef qHandle As %Binary, id As %String = "", NoLineRoutine As %Boolean = 0) As %Status [ Internal ]

Query for Web Lock display utility to use.

This query returns a row for each lock owner and lock waiter. So if one lock is owned by more than one process, it will return one row for each owner. It also returns one row for each waiter for one lock item.

ProcessClient: Owner's or waiter's Process ID. It can be a client system name if it is owned by a remote client. There is only one owner or waiter for each row.

ModeCount: Lock mode and count of the lock item. If the lock count is 1 the count will not be displayed, otherwise a '/count' will follow. A '->Delock' will be appended if the lock is in 'Deferred Delock' state (delocked within a transaction). The column can be:

• 'Exclusive' - Exclusive lock mode.
• 'Shared' - Share lock mode.
• 'LockZA' - ZALLOCATE lock mode.
• 'WaitExclusive' - Waiting for exclusive lock mode.
• 'WaitShared' - Waiting for share lock mode.
• 'WaitLockZA' - Waiting for ZALLOCATE lock mode.
  The Wait modes are followed by 'Exact', 'Parent', or 'Child'
• 'LockPending' - Exclusive lock Pending, waiting for server to grant the exclusive lock.
• 'SharePending' - Share lock Pending, waiting for server to grant the share lock.
• 'DelockPending' - Delock Pending, waiting for server to release the lock.
• 'Lost' - Lock lost due to network reset. Reference: Lock reference string of the lock item. This does not include the database name.

Directory: The database where the lock item is located.

System: The system name where the lock is located. If it is the local system the column will be a null string.

Removable: Flag indicates whether this lock (row) can be removed or not. Value 1 -> Removable, 0 -> Not removable, 2 -> Removable, but needs special warning because it is in 'DelockPending' state.

DeleteID: Delete key that can be used to call SYS.Lock.DeleteOneLock to delete the lock of the specific owner (that is the row).

CanBeExamined: Flag to tell whether the owner job can be examined or not.

WebListFetch

ClassMethod WebListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = WebListExecute ]

WebListClose

ClassMethod WebListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = WebListExecute ]

WebListFilterExecute

ClassMethod WebListFilterExecute(ByRef qHandle As %Binary, Filter As %String = "", NoLineRoutine As %Boolean = 0) As %Status [ Internal ]

WebListFilterFetch

ClassMethod WebListFilterFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = WebListExecute ]

WebListFilterClose

ClassMethod WebListFilterClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = WebListExecute ]

ConflictsExecute

ClassMethod ConflictsExecute(ByRef qHandle As %Binary, LockRef As %String = "") As %Status [ Internal ]

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.

ConflictsFetch

ClassMethod ConflictsFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = ConflictsExecute ]

ConflictsClose

ClassMethod ConflictsClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = ConflictsExecute ]