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
|
