LockDump Output

LockDump() is a low-level c-tree function which creates a diagnostic dump of the c-tree Server internal lock table. This is useful in development and profiling activities to observe application locking behavior. The syntax of the function is as follows:

COUNT LockDump(COUNT refno, pTEXT dumpname, COUNT mode)

The possible legal combinations of the LockDump() parameters mode and refno are as follows:

mode refno Interpretation

ctLOKDMPfile ctLOKDMPallfiles

ctLOKDMPdatafiles ctLOKDMPindexfiles filno

Dump all locks by file. Dump all locks on data files.

Dump all locks on index files.

Dump locks for file filno.

ctLOKDMPuser ctLOKDMPallusers

ctLOKDMPcaller userno

Dump all locks by user. Dump locks for user calling LockDump(). Dump locks for user userno.

The resulting lock dump output will be found in the file given by dumpname.

In all but one case of the above combinations the caller of LockDump() does not have to have any files open, although it is no problem if the caller does have files open. In the case of

ctLOKDMPfile/filno, the caller must have opened a file with file number filno. The userno

referenced in the last combination is the thread ID assigned by the c-tree Server. This thread ID is listed when ctadmn is used to list users logged on to the c-tree Server. In addition to dumping the location of the lock and the type of lock, users waiting for a lock are also listed.

Limitations

Since dumping all the locks in a very active system with many locks could affect performance, a c-tree Server will ONLY support the LockDump() call if either of the following conditions is met:

 The configuration file, ctsrvr.cfg, contains DIAGNOSTICS LOCK_DUMP.  The user calling LockDump() belongs to the ADMIN user group. Lock Dump Contents

================================================= All Files Lock Dump at Fri May 04 13:00:12 2007 ---

--- SOMEFILE.FCS>>

0000-013c9a16x T221 write/1: W060 W254 W740 W763 W758

0000-002916abx T758 write/1: W774 W772 W771 W775 W773 W778 W779 W776 W071 cumulative lock attempts: 4002(616) blocked: 21(0) dead-lock: 0 denied: 0 Current file lock count: 0

---

cumulative I/O: read ops: 0 bytes: 0 write ops: 5 bytes: 16768 .

. . .

List of connected clients ---

User# 00002: (Node name not set) User# 00012: (Node name not set)

================================================= Description

In the example above, The following details can be obtained:

 There are two records with locks held in SOMEFILE.FCS, each listed with it’s locked file offset value: 0000-013c9a16x and 0000-002916abx.

 The thread ID of the users holding the locks (T221 and T758)  The type of lock: write/1

 A listing of thread IDs waiting for the record lock to be released (for example, W060 W254 W740 W763 W758)

 The waiting thread IDs are further delineated with a prefix indicating the type of lock they are waiting to obtain: (R)ead or (W)rite locks.

Types of Locks

The possible lock types are shown in the following table.

Lock Type Value Explanation

SS open 1 SS (strict serializer) logical Open lock

SS commit intent 2 SS commit intent lock

SS commit 3 SS commit lock

NS commit intent 4 NS (nonstrict serializer) commit intent lock

NS commit 5 NS commit lock

read 6 Read lock - A read lock requested and held by a user

thread.

write/1 9 Exclusive write lock - A write lock requested and held by a user thread.

write/2 10 Exclusive write lock (no aggregate check) - An internal lock very briefly held by the c-tree Server for files under transaction control. You may occasionally observe these in a system with a high transaction volume, and these can be safely ignored.

forcei cmtlok 11 A very briefly held commit read lock enforced by the c-tree Server. These will only occur when the COMMIT_READ_LOCK option is enabled in the server configuration file. These may be occasionally observed in systems with high transaction volumes.

Note: The first five lock types listed in the table are only supported with a c-tree Server built with strict serialization support.

File Lock Info

 cumulative lock attempts xxx (yyy) - Total number of file and (header) lock attempts. The

header locks are internal c-tree Server locks required for critical updates to the file header.

 blocked - Total number of locks and (header locks) that were blocked while another lock was

held. In a high volume system, some blocked lock attempts are expected.

 dead-lock - Total of dead-lock conditions reported for this file. These are generally not

expected, and error DEAD_ERR (86) is returned to the application caller when this condition is detected. DEAD_ERR is returned when waiting for a write lock would cause a deadlock condition.

 denied - Total number of locks denied to a caller with error DLOK_ERR (42). A lock is denied

if the record is already locked. Note that blocking locks cause the thread to sleep until the lock is available, avoiding the DLOK_ERR.

Cumulative I/O

 read ops - Total cumulative read operations for this file.

 bytes - Total cumulative bytes read for this file.

 write ops - Total cumulative write operations for this file.

 bytes - Total cumulative bytes written for this file.

List of connected clients

A list of all connected clients is appended to the end of the lock dump output. This assists the correlation of known user threads at the application level to threads with potential blocked locks.

 User# - The thread ID of the user as identified by the c-tree Server

 Node Name - The node name of the thread as assigned by the application.

Note: On Windows, the list of connected clients includes the IP address in addition to the user name and node name.

8.5.1

Types of Locks

The possible lock types are shown in the following table.

Lock Type Value Explanation

SS open 1 SS (strict serializer) logical Open lock

SS commit intent 2 SS commit intent lock

SS commit 3 SS commit lock

NS commit intent 4 NS (nonstrict serializer) commit intent lock

Lock Type Value Explanation

read 6 Read lock - A read lock requested and held by a user

thread.

write/1 9 Exclusive write lock - A write lock requested and held by a user thread.

write/2 10 Exclusive write lock (no aggregate check) - An internal lock very briefly held by the c-tree Server for files under transaction control. You may occasionally observe these in a system with a high transaction volume, and these can be safely ignored.

forcei cmtlok 11 A very briefly held commit read lock enforced by the c-tree Server. These will only occur when the COMMIT_READ_LOCK option is enabled in the server configuration file. These may be occasionally observed in systems with high transaction volumes.

Note: The first five lock types listed in the table are only supported with a c-tree Server built with strict serialization support.