<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="pdostatement.execute" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>PDOStatement::execute</refname>
  <refpurpose>
   Executes a prepared statement
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="PDOStatement">
   <modifier>public</modifier> <type>bool</type><methodname>PDOStatement::execute</methodname>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>params</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Execute the <link linkend="pdo.prepared-statements">prepared
   statement</link>. If the prepared statement included parameter markers, either:
   <itemizedlist>
    <listitem><para><methodname>PDOStatement::bindParam</methodname> and/or
     <methodname>PDOStatement::bindValue</methodname> has to be called to bind either variables or
     values (respectively) to the parameter markers. Bound variables pass
     their value as input and receive the output value, if any, of their
     associated parameter markers</para></listitem>
    <listitem>
     <para>or an array of input-only parameter values has to be passed</para>
    </listitem>
   </itemizedlist>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>params</parameter></term>
     <listitem>
      <para>
       An array of values with as many elements as there are bound
       parameters in the SQL statement being executed.
       All values are treated as <constant>PDO::PARAM_STR</constant>.
      </para>
      <para>
       Multiple values cannot be bound to a single parameter; for example,
       it is not allowed to bind two values to a single named parameter in an IN()
       clause.
      </para>
      <para>
       Binding more values than specified is not possible; if more keys exist in 
       <parameter>params</parameter> than in the SQL specified 
       in the <methodname>PDO::prepare</methodname>, then the statement will 
       fail and an error is emitted.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &pdo.errors;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example><title>Execute a prepared statement with a bound variable and value</title>
   <programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement by binding a variable and value */
$calories = 150;
$colour = 'gre';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE calories < :calories AND colour LIKE :colour');
$sth->bindParam('calories', $calories, PDO::PARAM_INT);
/* Names can be prefixed with colons ":" too (optional) */
$sth->bindValue(':colour', "%$colour%");
$sth->execute();
?>
]]>
   </programlisting>
  </example>

  <example><title>Execute a prepared statement with an array of named values</title>
   <programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement by passing an array of insert values */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE calories < :calories AND colour = :colour');
$sth->execute(array('calories' => $calories, 'colour' => $colour));
/* Array keys can be prefixed with colons ":" too (optional) */
$sth->execute(array(':calories' => $calories, ':colour' => $colour));
?>
]]>
   </programlisting>
  </example>

  <example><title>Execute a prepared statement with an array of positional values</title>
   <programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement by passing an array of insert values */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE calories < ? AND colour = ?');
$sth->execute(array($calories, $colour));
?>
]]>
   </programlisting>
  </example>

  <example><title>Execute a prepared statement with variables bound to positional placeholders</title>
   <programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement by binding PHP variables */
$calories = 150;
$colour = 'red';
$sth = $dbh->prepare('SELECT name, colour, calories
    FROM fruit
    WHERE calories < ? AND colour = ?');
$sth->bindParam(1, $calories, PDO::PARAM_INT);
$sth->bindParam(2, $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>
]]>
   </programlisting>
  </example>

  <example><title>Execute a prepared statement using array for IN clause</title>
   <programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement using an array of values for an IN clause */
$params = array(1, 21, 63, 171);
/* Create a string for the parameter placeholders filled to the number of params */
$place_holders = '?' . str_repeat(', ?', count($params) - 1);

/*
    This prepares the statement with enough unnamed placeholders for every value
    in our $params array. The values of the $params array are then bound to the
    placeholders in the prepared statement when the statement is executed.
    This is not the same thing as using PDOStatement::bindParam() since this
    requires a reference to the variable. PDOStatement::execute() only binds
    by value instead.
*/
$sth = $dbh->prepare("SELECT id, name FROM contacts WHERE id IN ($place_holders)");
$sth->execute($params);
?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Some drivers require to <link linkend="pdostatement.closecursor">close
    cursor</link> before executing next statement.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>PDO::prepare</methodname></member>
    <member><methodname>PDOStatement::bindParam</methodname></member>
    <member><methodname>PDOStatement::fetch</methodname></member>
    <member><methodname>PDOStatement::fetchAll</methodname></member>
    <member><methodname>PDOStatement::fetchColumn</methodname></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->