Creating a Transaction Parameter Buffer

From InterBase

Go Up to Starting Transactions


The transaction parameter buffer (TPB) is an optional, application-defined byte vector that is passed as an argument to isc_start_transaction(). It sets up the attributes of a transaction, its operating characteristics, such as whether the transaction has read and write access to tables, or read-only access, and whether or not other simultaneously active transactions can share table access with the transaction. Each transaction may have its own TPB, or transactions that share operating characteristics can use the same TPB.

Note:
If a TPB is not created for a transaction, a NULL pointer must be passed to isc_start_transaction() in its place. A default set of attributes is automatically assigned to such transactions. For more information about the default TPB, see Using the Default TPB.

A TPB is declared in a C program as a char array of one-byte elements. Each element is a parameter that describes a single transaction attribute. A typical declaration is as follows:

static char isc_tpb[] = {isc_tpb_version3,
isc_tpb_write,
isc_tpb_read_committed,
isc_tpb_no_rec_version,
isc_tpb_wait};

This example makes use of parameter constants defined in the InterBase header file, f. The first element in every TPB must be the isc_tpb_version3 constant.

The following table lists available TPB constants, describes their purposes, and indicates which constants are assigned as a default set of attributes when a NULL TPB pointer is passed to isc_start_transaction():

TPB Constants
Parameter Description

isc_tpb_version3

InterBase version 3 transaction

isc_tpb_consistency

Table-locking transaction model. This mode is serializable.

isc_tpb_concurrency

High throughput, high concurrency transaction with repeatable read consistency. This mode takes full advantage of the InterBase multi-generational transaction model [Default].

isc_tpb_shared

Concurrent, shared access of a specified table among all transactions; use in conjunction with isc_tpb_lock_read and isc_tpb_lock_write to establish the lock option [Default].

isc_tpb_protected

Concurrent, restricted access of a specified table; use in conjunction with isc_tpb_lock_read and isc_tpb_lock_write to establish the lock option.

isc_tpb_exclusive

Used to specify exclusive table access when calling isc_start_transaction() at the API level.

isc_tpb_wait

Specifies that the transaction is to wait until the conflicting resource is released before retrying an operation [Default].

isc_tpb_wait_time

It is followed by the literal "4" denoting a byte count and four bytes in little endian format denoting the wait period in seconds.

isc_tpb_nowait

Specifies that the transaction is not to wait for the resource to be released, but instead, should return an update conflict error immediately.

isc_tpb_read

Read-only access mode that allows a transaction only to select data from tables.

isc_tpb_write

Read-write access mode of that allows a transaction to select, insert, update, and delete table data [Default].

isc_tpb_lock_read

Read-only access of a specified table. Use in conjunction with isc_tpb_shared, isc_tpb_protected, and isc_tpb_exclusive to establish the lock option.

isc_tpb_lock_write

Read-write access of a specified table. Use in conjunction with isc_tpb_shared, isc_tpb_protected, and isc_tpb_exclusive to establish the lock option [Default].

isc_tpb_read_committed

High throughput, high concurrency transaction that can read changes committed by other concurrent transactions. Transactions in this mode do not provide repeatable read.

isc_tpb_rec_version

Enables an isc_tpb_read_committed transaction to read the most recently committed version of a record even if other, uncommitted versions are pending.

isc_tpb_no_rec_version

Enables an isc_tpb_read_committed transaction to read only the latest committed version of a record. If an uncommitted version of a record is pending and isc_tpb_wait is also specified, then the transaction waits for the pending record to be committed or rolled back before proceeding. Otherwise, a lock conflict error is reported at once.

Important:
The combination of the options isc_tpb_read_commited, isc_tpb_no_rec_version, and isc_tpb_nowait will cause frequent deadlocks. This combination is not recommended.

TPB parameters specify the following classes of information:

  • Transaction version number is used internally by the InterBase engine. It is always be the first attribute specified in the TPB, and must always be set to ­isc_tpb_version3.
  • Access mode describes the actions that can be performed by the functions associated with the transaction. Valid access modes are:
isc_tpb_read
isc_tpb_write
  • Isolation level describes the view of the database given a transaction as it relates to actions performed by other simultaneously occurring transactions. Valid isolation levels are:
isc_tpb_concurrency
isc_tpb_exclusive
isc_tpb_consistency
isc_tpb_read_committed, isc_tpb_rec_version
isc_tpb_read_committed, isc_tpb_no_rec_version
  • Lock resolution describes how a transaction should react if a lock conflict occurs. Valid lock resolutions are:
isc_tpb_wait
isc_tpb_wait_time
isc_tpb_nowait
  • Table reservation optionally describes an access method and conflict resolution for a specified table that the transaction accesses. When table reservation is used, tables are reserved for the specified access when the transaction is started, rather than when the transaction actually accesses the table. Valid reservations are:
isc_tpb_shared, isc_tpb_lock_write
isc_tpb_shared, isc_tpb_lock_read
isc_tpb_protected, isc_tpb_lock_write
isc_tpb_protected, isc_tpb_lock_read

TPB parameters are described in detail in the following sections.

Note:
Reserving tables is a way to produce programs that are guaranteed to be deadlock-free. If your application uses short TP-style transactions, reserving all tables required for protected read or write, as necessary, can improve performance. This method should not be used for interactive applications. A transaction that reserves tables will receive an error if it attempts to access any tables that are not reserved.

Topics

Advance To: