FairCom ISAM for C

LockISAM

Enable, free, or suspend data record locks.

Short Name

LKISAM()

Type

ISAM function

Declaration

COUNT LockISAM(COUNT lokmod)

Description

LockISAM() manages the data record locks during multiple-user ISAM file handling. The LockISAM() options, defined in ctport.h, are:

Value	Symbolic Constant	Explanation
0	ctFREE	Free all data record locks held by this program and cancel the ctENABLE mode.
1	ctRESET	Equivalent to first calling LockISAM() in the ctFREE mode followed by a call with the existing mode (or ctENABLE if the current mode was ctFREE).
2	ctENABLE	Once LockISAM() is called with lokmod set to ctENABLE, all subsequent data record reads attempt to get a write lock before proceeding. Write locks can be used to prevent more than one process from updating the record at the same time, since only one process may acquire a write lock on a record. Any number of processes may still read the record.
3	ctENABLE_BLK	Same as ctENABLE, but a process unable to get a write lock is “put to sleep” until the lock is available.
4	ctREADREC	Once LockISAM() is called with lokmod set to ctREADREC, all subsequent data record reads attempt to get a read lock before proceeding. Read locks can be used to prevent another process from acquiring a write lock on the record. Any number of processes may acquire read locks on the same record. Not supported by all platforms. See the note after this table.
5	ctSUSPEND	Temporarily suspend the attempt to get a lock on each ISAM record read.
6	ctRESTORE	Restore the ctENABLE mode after a previous call to suspend data record locks.
7	ctRESTRED	Restore the ctREADREC mode after a previous call to suspend data record locks.
8	ctRESTORE_BLK	Restore the ctENABLE_BLK mode after a previous call to suspend data record locks.
11	ctREADREC_BLK	Same as ctREADREC, but a process unable to get a read lock is “put to sleep” until the lock is available.
14	ctRESTRED_BLK	Restore the ctREADREC_BLK mode after a previous call to suspend data record locks.
128	ctGETLKISAM	Queries the current ISAM lock state. Returns the negative of the value of the current ISAM lock state. For example, if locks are enabled, -2 is returned.
512	ctLK_RECR	Enables recursive locking.

To ensure multi-user systems make consistent updates, each program should ctENABLE data record locks prior to updating data, and hold these locks until the operations associated with those data records are completed. At that time, a call to LockISAM() with the ctFREE mode cancels all outstanding ISAM locks. Locks created by LockCtData() will NOT be released. ctRESET is used when traversing the data in key sequential order when, after each update, the previous locks should be released and new locks enabled for the next transaction.

ctREADREC signals that the record is under review by one or more readers, and that no update should be performed. If records are read without read, or write, locks, another process may update the record while it is under review. Usually, this is acceptable.

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

Five LockISAM() modes toggle locking, avoiding unnecessary data record locks in the middle of a transaction. These modes are ctSUSPEND, ctRESTORE, ctRESTORE_BLK, ctRESTRED, and ctRESTRED_BLK. Use the ctSUSPEND mode to scan one or more data records which will NOT be updated, or for which READ LOCKS ARE NOT REQUIRED, in the middle of a transaction which has already enabled data record locks. After scanning these records and before returning to your update activities, either:

Call LockISAM() with the ctRESTORE mode to restore ctENABLE.
Call LockISAM() with the ctRESTORE_BLK mode to restore ctENABLE_BLK.
Call LockISAM() with the ctRESTRED mode to restore ctREADREC.
Call LockISAM() with the ctRESTRED_BLK mode to restore ctREADREC_BLK.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful call to LockISAM().
112	IPND_ERR	A call to ctENABLE locks found some pending record locks. This error check is made to ensure that program logic has not started a new transaction before clearing the locks associated with an old transaction. However, it will also cause an error if some locks are acquired and a redundant LockISAM() call in the ctENABLE mode is issued.
113	INOL_ERR	No more room left in the internal lock table maintained by LockISAM(). Insufficient system memory.

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

In the example below, a program performing updates to customer invoices does updates involving price extension computations. To perform the computations, the program searches a separate ISAM file maintaining the prices. Since the program does not modify the price records, it calls LockISAM(ctSUSPEND) before searching the price records, and LockISAM(ctRESTORE) before continuing with the invoice updates.

Example

FILNO inv_idx, inv_fil, price_idx, price_fil;

TEXT target[9];

struct invd {

TEXT delflg;

TEXT invn[8];

TEXT dscrp[60];

TEXT part[12];

float quant;

float price;

float exten;

} cur_info;

struct {

TEXT pdlflg;

TEXT ppart[12];

float pprice;

} price_rec;

main() {

printf("\nEnter invoice number: ");

scanf("%8s",target);

if (LockISAM(ctENABLE) ||

FirstInSet(inv_idx, target, &cur_info,8)) {

printf("\n\nError starting SCAN with codes %d %d",

isam_err,isam_fil);

LockISAM(ctFREE);

return;

}

while (!isam_err) {

LockISAM(ctSUSPEND); /* turn off lock acquisition */

get_price_extension();

LockISAM(ctRESTORE); /* restore lock acquisition */

ReWriteRecord(inv_fil,&cur_info);

ResetRecord(inv_fil,SWTCURI);

/* reset current ISAM record */

LockISAM(ctRESET);

NextInSet(inv_idx,&cur_info);

}

LockISAM(ctFREE);

}

void get_price_extension()

{

if (GetRecord(price_idx,cur_info.part,&price_rec)) {

printf("\nCould not find part# %s.",cur_info.part);

return;

}

new_info.exten = (cur_info.price = price_rec.pprice) *

cur_info.quant;

}

Limitations

The FairCom Server supports both read and write locks on records. When not using the Server for multi-user applications, read locks may show success even if read locks are not implemented.

When using Transaction functions, refer to “Data Integrity” in the c-tree Programmer’s Reference Guide for information on how transaction processing interacts with LockISAM().