FairCom ISAM for C

LockList

Retrieve a list of users that own, and are waiting for, a data record lock at a specified byte offset of a data file.

Declaration

NINT LockList(FILNO datno, ctRECPT recbyt, NINT NbrUsers, pLOCKID userlist, pLONG pNbrLockers, pLONG pNbrWaiters);

Short Name

ctLOKLST

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

LockList() information is obtained with the following parameters

datno is the file number of a data file opened by the calling program.
recbyt is the byte offset of a data record. To set the high-order word of the record offset for huge files, call ctSETHGH() immediately before calling LockList().
NbrUsers is the number of LOCKID structures in the array pointed to by userlist.
userlist may be NULL, but then NbrUsers must be zero.
pNbrLockers and pNbrWaiters cannot be NULL. In the event that NbrUsers is smaller than the sum of lockers and waiters, then the list returned in userlist is truncated after NbrUsers entries. LockList() returns NO_ERROR if successful.

LockList() returns the user identification information for lock owners and lock waiters in the userlist array. The lock owners are returned at the beginning of the array, and the lock waiters follow the lock owners in the array. The number of lock owners is returned in the 4-byte integer pointed to by pNbrLockers. For read locks there may be more than one lock owner. For write locks there can only be one lock owner unless strict serialization is in effect. The number of users waiting for the lock is returned in the 4-byte integer pointed to by pNbrWaiters. There are waiters for a lock only when a lock request includes the blocking attribute (e.g., ctENABLE_BLK).

Details

LOCKID is a structure defined in ctport.h that includes the internal thread ID, the login name and the node name:

typedef struct lockid {

LONG ThrdID; /* internal thread ID */

TEXT UserID[32]; /* logon ID [IDZ] */

TEXT NodeName[32]; /* optional network NodeName IDZ*/

} LOCKID, * pLOCKID;

Because an ISAM operation that fails with a lock denied error DLOK_ERR (42) does not permit the denied locker to determine the record location of the denied lock, LockList() has been enhanced to accept a pseudo datno that indicates the request is for the last denied data record lock by the caller. Use ctLastDeniedLock, defined in ctport.h, for datno and the recbyt will be ignored. Instead, the last denied record lock, across all of the data files opened by the user, if any, will be examined for current lockers and waiters.

The last denied data record lock is not cleared upon the next successful data record lock. So calling LockList(ctLastDeniedLock ...) may be referencing a denied lock from the “distant” past. If the user closes the data file which contains the last denied lock, then the last denied lock will be cleared.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error occurred.

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

The following is an example to list all lock owner and “waiters” for a given record offset.

Example

NINT ListLockUsers(NINT datno, ctRECPT recbyt)

{

NINT i;

LOCKID list[128];

LONG lockers, waiters;

NINT eRet;

ctSETHGH(0);

eRet = (NINT)LockList((FILNO)datno, recbyt, 128, &list, &lockers, &waiters);

if (eRet != NO_ERROR)

{

printf("LockList failed with error %d\n", eRet);

return -1;

}

/* list lock owners */

for (i = 0; i < (NINT)lockers; i++)

printf("Lock owner %s\n", list[i].UserID);

/* list lock waiters */

for (i = (NINT)lockers; i < (NINT)waiters; i++)

printf("Waiting for lock %s\n", list[i].UserID);

return (NINT)(lockers + waiters);

}