FairCom ISAM for C

LockCtData

Lock / unlock data records or tables.

Short Name

LOKREC()

Type

Low-Level data file function

Declaration

COUNT LockCtData(FILNO datno, COUNT lokmod, LONG recbyt)

Description

LockCtData() provides Low-Level lock and unlock control over fixed- and variable-length data records. LockCtData() can also be used with ISAM files to relax the constraints of the “two-phase” protocol described in Multi-User Concepts of the c-tree Programmer’s Reference Guide. Because c-tree is based on write locks, a locked record can be read by other processes as long as they do not attempt their own write lock on the record.

lokmod specifies an action based on the following values:

Value	Symbolic Constant	Explanation
0	ctFREE	An unlock operation.
2	ctENABLE	A write lock operation. Only one process may obtain a write lock on a record.
3	ctENABLE_BLK	As ctENABLE, but a process unable to get a lock sleeps until the lock is available instead of returning DLOK_ERR. However, if a dead lock is detected, DEAD_ERR is returned.
4	ctREADREC	A read lock operation. Read locks may be acquired by any number of users on the same data record at the same time. A read lock ensures that no other user can acquire a write lock on the record.
11	ctREADREC_BLK	Same as ctREADREC, but a process unable to get a read lock is “put to sleep” until the lock is available.
18	ctFREE_FILE	Frees all locks held on file datno. Set recbyt to 0L for this lokmod. See notes below.
20	ctFREE_ISAM	Frees all ISAM level locks on file datno.
21	ctCHKLOK	Checks the lock status of recbyt for datno.
512	ctLK_RECR	Enable recursive locking.
22	ctFREE_WRTLOKS	Unlock write locks for a user for a specified data file.
25	ctFREE_REDLOKS	Unlock read locks for a user for a specified data file.
26	ctCHK_ANYLOK	Check if the table has any user lock .
27	ctCHKLOK_OTHER	Check for lock by other connection/datno
28	ctENABLE_BLKRQS	Make a non-blocking write lock request on the specified record. If acquired, the force blocking lock option is set on that lock (making other connections block when requesting the lock even if they are non-blocking lock requests).

Note: Many systems do not support read locks. If read locks are not supported, c-tree returns no error condition (i.e., the read lock is not attempted, but no error is reported). The FairCom Server supports both read and write locks.

recbyt specifies the beginning byte offset for the record lock/unlock operation. c-tree automatically provides the data file record length for the number of bytes to be locked. In the case of a variable-length file, c-tree only applies the lock to the minimum, fixed-length portion of the record. In any event, c-tree always asks for at least a 1-byte lock.

Return

In single-user applications, LockCtData() always returns successfully. In other modes, check uerr_cod for the values in the following table.

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful lock/unlock operation. Check sysiocod.
41	UDLK_ERR	Could not unlock data record. Check sysiocod.
42	DLOK_ERR	Record is already locked. Check sysiocod.
48	FMOD_ERR	LockCtData() called for an index file.
86	DEAD_ERR	Waiting for a write lock would cause a dead lock.
160	ITIM_ERR	Multi-user interference: key value changed between index search and subsequent data record read.

A LockCtData() call attempting to unlock a record that is part of transaction returns NO_ERROR (0), but sets sysiocod to UDLK-TRN (-3), indicating the lock will be held until the end of the transaction.

If LockCtData(datno,ctCHKLOK,recbyt) returns NO_ERROR then sysiocod holds the lock status. If sysiocod and uerr_cod are zero, then no lock is held by the calling user. If sysiocod is non-zero and uerr_cod is zero, interpret sysiocod as follows:

The low-order byte contains the type of lock: ctENABLE (2) for a write lock, or ctREADREC (4) for a read lock.
The high-order byte is composed of one or more of the following attributes bits (left shifted 8 bits):

Value

Symbolic Constant

Explanation

1

ctISAMLOCK

ISAM lock.

4

ctTRANLOCK

Lock obtained or touched in transaction.

8

ctTRANOUT

Lock obtained outside of transaction.

Value	Symbolic Constant	Explanation
1	ctISAMLOCK	ISAM lock.
4	ctTRANLOCK	Lock obtained or touched in transaction.
8	ctTRANOUT	Lock obtained outside of transaction.

The higher order byte may contain other attribute bits that may be found in ctport.h where ctISAMLOCK is defined.

For an example of ctCHKLOK, a call of the form LockCtData(datno, ctCHKLOK, recbyt) might return the following values:

Value	Symbolic Constant	sysicod	Explanation
0	NO_ERROR	0x0502	ISAM write lock at recbyt obtained inside transaction.
0	NO_ERROR	0x0000	No lock held at recbyt.

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

Example

LONG pntr;

FILNO datno;

TEXT recbuf[147];

if ((pntr = NewData(datno)) == 0L ||

fill_buffer(recbuf) != NO_ERROR ||

WriteData(datno,pntr,recbuf) ||

LockCtData(datno,ctFREE,pntr))

printf("\nCould not write new record (%d)",uerr_cod);

/* NewData always acquires a lock on a new record */

Limitations

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

Locks on a specified record offset

ctCHKLOK_OTHER can be used to check if a lock is held on the specified offset of a data file by either another connection or by the same connection but with a different file number. The definition of "different file number" depends on the MULTIOPN mode that is in effect on the data file whose file number is specified:

If using MULTIOPN_NODIFUSR or MULTIOPN_DIFUSR, then a lock that was acquired on the record offset by the calling connection using a different file number (known as a co-file) is treated as though the lock was acquired by another connection.
If using MULTIOPN_SAMUSR_1 or MULTIOPN_SAMUSR_M, then a co-file lock is treated as though the lock was acquired by the calling connection.

To use this feature, call LOKREC() with the mode ctCHKLOK_OTHER. As with the ctCHKLOK mode, LOKREC() returns NO_ERROR to indicate success, or a non-zero error code to indicate failure. On success, c-tree's connection-level state variable sysiocod is set to indicate whether or not another connection or co-file has acquired a lock on the specified offset:

A sysiocod value of 0 indicates no lock is held by another connection or co-file.
A sysiocod value of 2 indicates a write lock is held by another connection or co-file.
A sysiocod value of 4 indicates a read lock is held by another connection or co-file.

Table Locking

V11 and later of FairCom DB support file-level locking on c-tree data files, which is known as a "table lock." An application can request a file lock to prevent other connections from reading from and/or writing to the file. Table Locks can be invoked using SQL or using the LockCtData() function. For information, see the sections titled Table Lock Support (Table Lock Support, Table Lock) and Table Lock Mode for LOCKREC.

LOKREC() modes to unlock all records in all files of the specified type that are open by the caller

In V11, LOKREC() function's ctFREE_FILE mode now supports options to free ALL locks in ALL specified types of files that a caller has open. To use this feature, call LOKREC() with mode of ctFREE_FILE, recbyt of zero (it is ignored), and set datno to one, or a combination of the following values:

ctFREEALL_NOTRAN - free all non-transaction file locks
ctFREEALL_NOIICT - free all transaction-controlled file locks without IICT enabled
ctFREEALL_IICT - free all transaction-controlled file locks with IICT enabled
ctFREEALL_TRAN - free all transaction-controlled file locks
ctFREEALL_ALL - free all file locks

Example

Free all locks in all non-transaction files and all transaction-controlled files that are not using IICT that the caller has open.

rc = LOKREC( ctFREEALL_NOTRAN | ctFREEALL_NOIICT,ctFREE_FILE, 0 );