PEAR Manual
Prev |  | Next

# DB_common::execute()

DB_common::execute() -- Executes a prepared SQL statment

## Synopsis

``mixed &execute` (resource $stmt [, mixed $data = array()])`

## Description

Merges the SQL statment you submitted to prepare() with the information in `$data` and then sends the query to the database.

## Parameter

resource `$stmt`

  query handle from prepare()

mixed `$data`

  array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

## Return value

mixed - a new DB_result object for queries that return results (such as SELECT queries), `DB_OK` for queries that manipulate data (such as INSERT queries) or a DB_Error object on failure

## Throws

Table 33-1. Possible PEAR_Error values

Error code | Error message | Reason | Solution
--- | --- | --- | ---
`DB_ERROR_INVALID` | invalid | SQL statment handle is not valid. | Check correct processing of the SQL statment with prepare(). Note that execute() requires a handle to the statement returned by prepare(), not the statment itself.
`DB_ERROR_MISMATCH` | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statment. | Check that the number of placeholders in the prepare() statement passed to `$query` equals the count of entries passed to `$params`.
`DB_ERROR_NODBSELECTED` | no database selected | No database was choosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP-Manual to detect the reason for this error. In the most cases a misformed SQL statment. Ie. using LIMIT in a SQL-Statment for an Oracle database.

## Note

This function can not be called statically.

Warning
The values passed in `$data` must be literals. Do not submit SQL functions (for example `CURDATE()`). SQL functions that should be performed at execution time need to be put in the prepared statement.

## Example

Example 33-1. Passing a scalar to execute()
    <?php
    // Once you have a valid DB object named $db...
    $sth = $db->prepare('INSERT INTO numbers (number) VALUES (?)');
    if (PEAR::isError($sth)) {
        die($sth->getMessage());
    }

    $res =& $db->execute($sth, 1);
    if (PEAR::isError($res)) {
        die($res->getMessage());
    }
    ?>

Example 33-2. Passing an array to execute()
    <?php
    // Once you have a valid DB object named $db...
    $sth = $db->prepare('INSERT INTO numbers VALUES (?, ?, ?)');

    $data = array(1, 'one', 'en');
    $db->execute($sth, $data);
    ?>

## See

"Intro - Prepare & Execute", "Intro - autoPrepare & autoExecute", prepare(), executeMultiple()

Prev | Home | Next
DB_common::escapeSimple() | Up | DB_common::executeMultiple()