Btrieve Clients

Btrieve Clients

A Btrieve client is an application-defined entity that makes Btrieve calls. Each client can make Btrieve calls and has its own resources (such as files) that are registered with the MicroKernel. In addition, the MicroKernel maintains the status of transactions (both exclusive and concurrent) on a per-client basis.

When you need to support multiple clients concurrently, use the BTRVID or BTRCALLID function, which includes a Client ID parameter. The Client ID parameter is the address of a 16-byte structure that allows the MicroKernel to differentiate among the clients on a computer. Following are examples of situations in which using a Client ID might be useful:

•

You write a multi-threaded application that conducts several transactions, all in progress at the same time. For each Begin Transaction operation, the application specifies a different Client ID. The MicroKernel maintains separate transaction states for each Client ID.

•

You write an application that uses two Client IDs, and for each Client ID, opens several files. Your application can execute a Reset operation using BTRVID, BTRCALLID, or BTRCALLID32, causing the MicroKernel to close the files and free the resources for a single specified Client ID.

•

You write an application that allows multiple instances of itself to run simultaneously. For the integrity of your application’s data, all instances must appear to the MicroKernel as a single client. In this situation, your application provides the same Client ID parameter on each Btrieve call, regardless of which instance of the application is making that call.

•

You write an application that acts as a Dynamic Data Exchange (DDE) server. Your server application, which makes Btrieve calls, must divide the returned information between the applications originating the requests to your server application. In this situation, your application can assign a different Client ID to each requesting application, providing a way to track information to be distributed among several clients.

The MicroKernel provides several concurrency control methods and uses several implementation tools to resolve conflicts that can occur when multiple clients attempt to access or modify records in the same file concurrently.

The concurrency control methods are as follows:

•

Passive Concurrency (page 9-135)

•

Record Locking (page 9-137)

•

User Transactions (page 9-138)

The implementation tools are as follows:

•

Explicit Record Locks

•

Implicit Record Locks

•

Implicit Page Locks

•

The following sections discuss the MicroKernel’s concurrency control methods in detail. While reading each of the sections, refer to Table 35. This table summarizes the types of conflicts that can occur when two clients attempt to access or modify the same file. Table 35 describes the actions of local clients.

Note: If your application uses the BTRVID function to define and manage multiple clients within the same application, such clients are considered local clients.

In both tables, client 1 performs an action identified by an abbreviation in the far-left column of the table, and then client 2 attempts to perform one of the actions identified by an abbreviation in the top row of the table.

The actions represented by the abbreviations are described in Action Codes.

Table 35 assumes the following:

•

For a specific cell of the table, client 2 attempts to perform an action after client 1 starts performing an action. The first action must finish before the second action can start.

•

For any cell in which client 2 performs an update or delete operation, client 2 is assumed to have read the affected record before client 1 performs its action.

•

Unless explicitly stated in the action description for client 2 (as in actions MDR and MTDR), clients 1 and 2 always perform their actions on the same record, when both operations are reads or when both operations are updates or deletes.

•

Unless explicitly stated in the action description for client 2 (see action ITDP), when both client 1 and client 2 perform an insert, update, or delete operation, both clients change at least one of the pages they have in common.

•

When client 2 performs a modification following an insert operation by client 1, the modified record is not the inserted record, although both records share one or more data, index, or variable pages in the file.


RNL	Read without lock request, either non-transactional or in a concurrent transaction.
RWL	Read with lock request, either non-transactional or in a concurrent transaction.
INT	Insert, non-transactional.
ICT	Insert in a concurrent transaction.
ITDP	Insert in a concurrent transaction, changing different pages than those modified by an insert, update, or delete by client 1, who is also in a concurrent transaction.
MNT	Modify (update or delete), non-transactional.
MDR	Modify (non-transactional) a different record than the one modified by client 1.
MCT	Modify in concurrent transaction.
MTDR	Modify (in concurrent transaction) a different record than the one modified by client 1.
EXT	Read, insert, or modify in exclusive transaction.


N/A	Not applicable.
NC	No conflict or blocking between the actions of client 1 and client 2.
RB	Record-level blocking. Client 2 is blocked because of a record lock held by client 1.
PB	Page-level blocking. Client 2 is blocked because of a page lock held by client 1.
FB	File-level blocking. Client 2 is blocked because of a file lock held by client 1.
RC	Record conflict. Client 2 cannot execute the operation because the record has been modified by client 1 in the time since client 2 originally read the record. The MicroKernel returns Status Code 80.

For conflict codes RB, PB, and FB, the MicroKernel retries client 2’s action unless client 2 has specified a no-wait type operation (for example, a read with a no-wait lock or an insert/modify in a concurrent transaction that was started with a 500 bias). For a no-wait operation, the MicroKernel returns an error status code.

Table 35

Possible File Operation Conflicts Involving Local Clients

Client 2 Action

Following are examples for interpreting action code combinations in Table 35:

•

Combination EXT-RWL: Client 1 reads a record from the file from within an exclusive transaction. Client 2 receives Status Code 85 (FB, file-level blocking) when it tries to read a record from the file with a no-wait lock bias in a non-transactional mode. If client 2 specifies a wait lock bias, the MicroKernel retries the operation.

•

Combination ICT-ICT: Client 1 inserts a record from within a concurrent transaction. The MicroKernel retries the operation when client 2 attempts to insert a record into the same file, because one of the pages to be modified by the operation has already been changed by the insert operation performed by client 1. If client 2 starts the concurrent transaction with a 500 bias, the MicroKernel returns Status Code 84. (See the Assumptions (page 9-133) concerning this table.)

•

Combination ICT-ITDP: This combination resembles ICT-ICT, except that client 2 does not change any page that has already been modified by client 1. In this case, the operation attempted by client 2 is successful (NC, no blocking, no conflict).

•

Combination MCT-MTDR: Although client 1 and client 2 modify different records, client 2 is blocked by a page lock. This blockage results because the records being modified share a data page, index page, or variable page in the file. (See the Assumptions (page 9-133) concerning this table.)