FBIRD_PREPARE

Purpose

Use the fbird_prepare function to prepare a SQL statement for later execution with fbird_execute.

Syntax

<prepare> ::=
     fbird_prepare( sql )
   | fbird_prepare( conn_hndl, sql )
   | fbird_prepare( trx_hndl, sql )
   | fbird_prepare( conn_hndl, trx_hndl, sql )

Element 

Type

Description

sql

string

A valid SQL statement

conn_hndl

resource

A valid connection handle

trx_hndl

resource

A valid transaction handle

<return>

mixed

A query handle on success, False on failure

Semantics

The fbird_prepare function prepares a SQL statement for later execution by fbird_execute. If the same statement is to be executed multiple times, perhaps using different parameters, then using prepare/execute is much faster than dynamically constructing SQL strings and using fbird_query. This is because the Firebird server will only have to analyse, optimise and compile the statement once for all subsequent executions.

If neither a connection handle nor a transaction 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.

If a transaction handle is provided, the driver will determine which connection handle it is associted with. If the transaction spans multiple connections, the function will fail.

If a transaction handle is not provided, then the "default" transaction will be used. If no default transaction exists, a new default transaction is started. A default transaction ends on commit or rollback. The default transaction parameters are: IBASE_CONCURRENCY, IBASE_WRITE and, IBASE_WAIT.

The function returns a query handle on success and False on failure. The query handle is used in fbird_execute, fbird_num_params and fbird_param_info.

Example

The below example prepares an update query and excutes it three times, using different parameters on each invocation:

$updates = array(1001 => 'Eric', 1005 => 'Filip', 1007 => 'Larry');
$conn = fbird_connect($host, $username, $password);
$query = fbird_prepare($conn, "UPDATE STAFF SET name=? WHERE id=?");
foreach ($updates as $id => $name) {
   fbird_execute($query, $id, $name);
}

See also

fbird_execute, fbird_query