LockCtData

Lock / unlock data records.

Short Name

LOKREC()

Type

Low-level data file function

Declaration

COUNT LockCtData(COUNT 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 Plus Programmer’s Reference Guide. Since c-tree Plus 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.
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.

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

recbyt specifies the beginning byte offset for the record lock/unlock operation. c-tree Plus 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 Plus only applies the lock to the minimum, fixed-length portion of the record. In any event, c-tree Plus 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 comprised 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.

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 Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

LONG      pntr;

COUNT     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.