Knowledgebase

LockDump Output

LockDump() is a low-level FairCom DB function that creates a diagnostic dump of the FairCom DB 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 FairCom DB. This thread ID is listed when ctadmn is used to list users logged on to FairCom DB. 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, FairCom DB 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 FairCom DB 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 FairCom DB. 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 FairCom DB 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 FairCom DB 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 FairCom DB
• 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.

Locating a Record in LockDump Output

The record offset is split into ctreeRecordOffsetSelector-ctreeRecordOffsetLong in the LockDump output:

• ctreeRecordOffsetLong is the low word of the 64-bit record offset
• ctreeRecordOffsetSelector is the high word

Combine them to get a complete record offset. In C, this can be done with the following:

long offset = (((long)ctreeRecordOffsetSelector) <<32) +(uint)ctreeRecordOffsetLong;

In This Section Types of Locks Locating a Record in LockDump Output

Types of 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 FairCom DB 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 FairCom DB. 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 FairCom DB Server built with strict serialization support.

Locating a Record in LockDump Output

The record offset is split into ctreeRecordOffsetSelector-ctreeRecordOffsetLong in the LockDump output:

• ctreeRecordOffsetLong is the low word of the 64-bit record offset
• ctreeRecordOffsetSelector is the high word

Combine them to get a complete record offset. In C, this can be done with the following:

long offset = (((long)ctreeRecordOffsetSelector) <<32) +(uint)ctreeRecordOffsetLong;