FairCom ISAM for C

LockDump

Dump the FairCom Server internal lock table.

Short Name

ctLOKDMP()

Type

Low-Level function

Declaration

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

Description

LockDump() creates a diagnostic dump of the FairCom Server internal lock table. refno indicates whether locks for a particular file or user are to be dumped or whether all locks are to be dumped. mode indicates whether the dump is organized by file or by user number. dumpname is the name of a text file to which the contents of the dump will be appended.

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

refno	mode	Interpretation
ctLOKDMPallfiles ctLOKDMPdatafiles ctLOKDMPindexfiles filno	ctLOKDMPfile	Dump all locks by file. Dump all locks on data files. Dump all locks on index files. Dump locks for file filno.
ctLOKDMPallusers ctLOKDMPcaller userno	ctLOKDMPuser	Dump all locks by user. Dump locks for user calling LockDump(). Dump locks for user userno.

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 FairCom Server. This thread ID is listed when ctadmn is used to list users logged on to the FairCom Server. In addition to dumping the location of the lock and the type of lock, users waiting for a lock are also listed.

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, there are two records with locks held in SOMEFILE.FCS. Each record is listed with it’s locked file offset value, the thread ID of the user holding the lock, the type of lock, and a listing of thread IDs waiting for the record lock to be released. The waiting thread IDs are further delineated with a prefix indicating the type of lock they are waiting to obtain, write (W) or read (R) locks.

Types of Locks

There are several types of record locks that can be reported. The most common of these are:

• read - A read lock requested and held by a user thread.
• write/1 - A write lock requested and held by a user thread.
• write/2 - An internal lock very briefly held by the FairCom 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 - A very briefly held commit read lock enforced by the FairCom 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.

File Lock Info

• cumulative lock attempts xxx (yyy) - Total number of file and (header) lock attempts. The header locks are internal FairCom 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 FairCom 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.

Return

The common error code returns are:

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful lock dump.
12	FNOP_ERR	Could not open the dumpname text file.
22	FNUM_ERR	mode is ctLOKDMPfile and refno (filno) is out of range.
26	FACS_ERR	mode is ctLOKDMPfile and refno (filno) does not reference an opened file for the caller.
116	IMOD_ERR	Bad mode or combination of mode and refno.
454	NSUP_ERR	The call is not made to a FairCom Server; or the caller is not part of the ADMIN group; or DIAGNOSTICS LOCK_DUMP is not in the configuration file.

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

COUNT retval;

TEXT dumpname[20]="AllUserLocks.dmp"

retval = LockDump(ctLOKDMPallusers, dumpname, ctLOKDMPuser);

switch (retval) {

case NO_ERROR:

break;

case NUSUP_ERR:

terminate("LockDump not supported .");

default:

terminate("LockDump error.");

}

Limitations

Note: Dumping large quantities of locks in a very active system could affect performance.

Because of potential performance impact, a FairCom 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.

Related Topics

• The command-line utility ctstat -filelocks and -userlocks modes provide an alternate way to retrieve lock table information. That utility provides a more granular method of inspecting locks. See File and User Lock Example in the FairCom DB Server Administrator's Guide.
• LockDump Output