|
|
|
ctGetFileLocks
Declaration
NINT ctGetFileLocks(pTEXT FileName, NINT options, pctLOKINF pFileLockInfo, pLONG pNbrLocks);
Description
Returns information about all locks currently held on the specified file.
typedef struct ctwatinfo {
NINT loktyp; /* lock type */
NINT taskid; /* connection number */
TEXT usrnam[32]; /* user name */
} ctWATINF, ctMEM * pctWATINF;
typedef struct ctlokinfo {
LONG8 recbyt; /* offset of lock in file */
NINT loktyp; /* lock type */
NINT taskid; /* connection number */
NINT waitcnt; /* number of waiters */
TEXT usrnam[32]; /* user name */
} ctLOKINF, ctMEM * pctLOKINF;
FileName holds the name of the file whose list of locks is to be returned.
pFileLockInfo points to an array of ctLOKINF record lock information structures allocated by the caller. On input, pNbrLocks points to the size of this array. A successful call to ctGetFileLocks() sets pNbrLocks to point to the number of ctLOKINF entries that were written to the pFileLockInfo array.
Specify a value of ctLOKINFgetwaitlist for the options parameter to cause ctGetFileLocks() to return a list of lock waiters in addition to the ctLOKINF lock information for each record lock. When this option is specified, ctWATINF structures follow each ctLOKINF structure for which there are connections waiting to acquire the lock. The number of ctWATINF structures is indicated by the ctLOKINF structure's waitcnt field value. See the note below for details about the alignment of the ctWATINF and ctWATINF structures.
If you do not want to receive a list of lock waiters for each record lock, specify a value of 0 for the options parameter.
If the specified array size is too small to hold the list of all locks held on the specified file, *pNbrLocks is set to the number of array entries required, and ctGetFileLocks() returns error VBSZ_ERR (153, buffer too small).
Note: When using the ctLOKINFgetwaitlist option, the lock wait lists are written to the pFileLockInfo buffer following the list of ctLOKINF structures. If the buffer is not large enough to hold all the ctLOKINF lock information structures and ctWATINF wait list structures, ctGetFileLocks() returns error VBSZ_ERR and sets *pNbrLocks to the number of ctLOKINF structures that are needed to hold the total number of ctLOKINF and ctWATINF structures to be returned.
Note: The user name is stored in the pFileLockInfo buffer as a null-terminated string and is not padded to the full length of the usrnam field. This is true for both the ctLOKINF and ctWATINF usrnam fields. Each user name is followed by padding bytes if necessary to ensure that the next ctWATINF structure in the buffer is aligned on a four-byte boundary and that the next ctLOKINF structure in the buffer is aligned on an eight-byte boundary.
Only a user who is a member of the ADMIN group can call this function. If a user who is not a member of the ADMIN group calls this function, it returns error LADM_ERR (589, member of ADMIN group required).
Dumping large quantities of locks in a very active system could affect performance.
Return Values
Symbolic Constant |
|
Explanation |
NO_ERROR |
0 |
No error |
VBSZ_ERR |
153 |
Buffer too small |
LADM_ERR |
589 |
Member of ADMIN group required |
See FairCom DB Error Codes for a complete listing of valid error values.
Example
For code that demonstrates how to call these functions, see the functions ictadmnListOpenFiles(), ictadmnListFileUsers(), and ictadmnListFileLocks() in the c-tree source file ctree\source\ctadmn.c.
See also
ctGetOpenFiles, ctGetFileLocks
