Firebird 2.0
PHP5 Programming
Manual

FBIRD_TRANS

Purpose

Use the fbird_trans function to explicitly start a transaction on a single, or multiple connections.

Syntax

<trans> ::=
   fbird_trans( <trans_list> )

<trans_list> ::=
     <trans>
   | <trans>, <trans_list>

<trans> ::=
   <modifiers> , <connections>

<connections> ::=
     conn_hndl
   | conn_hndl, <connections>

<modifiers> ::=
     modifier
   | modifier, <modifiers>


Element 
Type
Description
modifier
int
A valid transaction modifier (see below)
conn_hndl
resource
A valid connection handle
<return>
mixed
A transaction handle on success, False on failure

Semantics

The fbird_trans function starts a new, separate transaction. To use this transaction, add the transaction handle to fbird_query or fbird_prepare function calls.

This function will accept multiple modifier and connection handle arguments. This allows transactions over multiple database connections, which are committed using a 2-phase commit algorithm. This means that you can rely on the updates to either succeed in every database, or fail in every database. If you use transactions over multiple databases, you will have to specify both the connection handle and the transaction handle in calls to fbird_query and fbird_prepare.

The modifiers can be used to specify the properties of the transaction, such as the ability to write, the isolation level and the action taken in conflict situations, as summarised in the following table.

Modifier
Meaning

IBASE_DEFAULT

The default transaction settings are to be used: IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT

IBASE_READ

Starts a read-only transaction

IBASE_WRITE

Starts a read-write transaction

IBASE_CONSISTENCY

Starts a transaction with the isolation level set to 'consistency', which means the transaction cannot read from tables that are being modified by other concurrent transactions.

IBASE_CONCURRENCY

Starts a transaction with the isolation level set to 'concurrency' (or 'snapshot'), which means the transaction has access to all tables, but cannot see changes that were committed by other transactions after the transaction was started.

IBASE_COMMITTED

Starts a transaction with the isolation level set to 'read committed'. This flag should be combined with either IBASE_REC_VERSION or IBASE_REC_NO_VERSION. This isolation level allows access to changes that were committed after the transaction was started.

IBASE_REC_VERSION

In combination with IBASE_COMMITTED, only the latest version of a row can be read.

IBASE_REC_NO_VERSION

In combination with IBASE_COMMITTED, a row can even be read when a modification to it is pending in a concurrent transaction.

IBASE_WAIT

Starts a transaction that should wait and retry when a conflict occurs.

IBASE_NOWAIT

Starts a transaction that should fail immediately when a conflict occurs.

If no modifiers are given, IBASE_DEFAULT is used instead.

If a connection handle is not provided, then the "default" connection will be used. The default connection is assigned every time you call fbird_connect or fbird_pconnect, so if you have multiple connections it will be whichever one was connected last.

Example

The below example code fragment executes a query in a read-only transaction:

$trx = fbird_trans(IBASE_READ, $conn);
$res = fbird_query($conn, $trx, “SELECT * FROM tab1”);



See also

fbird_prepare, fbird_query, fbird_commit, fbird_rollback


previous page goto index next page

Legal information