Btrieve provides several concurrency control methods and tools to resolve conflicts that can occur when multiple Btrieve clients attempt to access or modify records in the same file concurrently:

Passive Concurrency

You may choose to rely on passive concurrency for resolving update conflicts if an application will perform single-record read and update operations in the following situations:

• While not inside a transaction
• From within a concurrent transaction

With passive concurrency, Btrieve allows a client to read a record without applying any lock bias for the operation. Then, if a second client changes the record between the time the first client reads it and the time the first client attempts to update or delete it, Btrieve returns Status Code 80 (Conflict).

In this situation, the modification initiated by the first client would be based on an outdated image of the record. Therefore, the first client must read the record again before performing the Update (3) or Delete (4) operation.

Table 13. Passive Concurrency (Non-transactional Example)

Application 1	Application 2
1. Open file.
	2. Open file.
3. Read Record A.
	4. Read Record A.
5. Update Record A.
	6. Update Record A. Btrieve returns Status Code 80 (Conflict).
	7. Reread Record A.
	8. Update Record A.

Table 14. Passive Concurrency (Concurrent Transaction Example)

Application 1	Application 2
1. Begin concurrent transaction.
	2. Begin concurrent transaction.
3. Read record A.
4. Update record A.
	5. Read record A.
6. End transaction.
	7. Update record A. Btrieve returns conflict status code.
	8. Reread record A.
	9. Update record A.
	10. End transaction.

NOTE:  Even though Application 2 reads record C after Application 1 has already executed the update operation, Btrieve correctly detects a conflict error in Step 7. This conflict exists because Application 1 does not commit the change it made to record A until ending its transaction in Step 6. By the time Application 2 attempts its update in Step 7, the image it read of record A (in Step 5) is outdated.

Records, pages, or even an entire Btrieve file may be locked. Once locked, a record, page, or file cannot be modified by any client other than the one responsible for the lock. Similarly, locks owned by one client can prevent record, page, or file locking by another client, as explained in the rest of this section.

Btrieve provides two kinds of locks:

• Explicit
• Implicit

When a client specifically requests the lock by including the lock request with a Btrieve operation code, that lock is called an explicit lock.

However, even when a client does not explicitly request a lock, Btrieve may lock an affected record or page as the result of some action performed by the client. In this situation, the lock requested by Btrieve is called an implicit lock.

• Records can be locked either explicitly or implicitly.
• Pages can only be locked implicitly.
• Files can be locked only explicitly.

The rest of this section discusses the various locks as they apply in both non-transactional and transactional environments.

Implicit Record Locks

When a client attempts to update or delete a record, either external to any transaction or from within a concurrent transaction, Btrieve implicitly tries to lock that record on behalf of the client (hence the term implicit record lock).

In an exclusive transaction, an implicit record lock is unnecessary because Btrieve locks the entire file prior to performing the update or delete operation.

Btrieve can grant an implicit record lock to a client as long as no other client

• Holds an explicit lock on the record
• Holds an implicit lock on the record
• Has locked the file containing the record

Btrieve tries, on behalf of the client, to implicitly lock the pages that are modified during execution of an insert, update, or delete operation if the modification occurs either outside of a transaction or from within a concurrent transaction.

NOTE:  In an exclusive transaction, an implicit page lock is unnecessary because Btrieve locks the entire file prior to performing an update or delete operation. In the case of an Insert operation, Btrieve requests a file lock if the client does not have one yet.

As with implicit record locks, implicit page locks are provided by Btrieve. The client does not explicitly request them.

The data page containing the record being modified (or that will contain the record being inserted) must always be locked. However, a single operation might need to lock several other pages as well.

For example, if the change made to a record involves one or more of the record's keys, then Btrieve must lock the index pages containing the affected key values. Btrieve must also lock all index pages modified by the action of balancing the B-tree(s) during the operation.

If a modification affects the variable-length portion of a record, Btrieve must lock the variable page(s) as well.

Implicit page locks allow multiple clients to modify different parts of the same file at the same time from within concurrent transactions, as long as those modifications do not affect other previously locked portions of the file.

File Locks

When a client "touches" a file for the first time in an exclusive transaction by performing an insert, update, or delete operation, that client tries to obtain a file lock.

NOTE:  As the preceding statement implies, Btrieve does not lock a file when the client performs a Begin Transaction operation. The lock occurs only when the client reads or modifies a record after performing the Begin Transaction operation.

A file lock, as its name suggests, locks the entire Btrieve file. A client's file locks remain in effect until that client ends or aborts the transaction, or until the client is reset (which implies performing an Abort Transaction operation).