php-doc-en/reference/pdo/functions/PDOStatement-bindParam.xml

<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.11 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
  <refentry id="function.PDOStatement-bindParam">
   <refnamediv>
    <refname>PDOStatement::bindParam</refname>
    <refpurpose>
     Binds a parameter to the specified variable name
    </refpurpose>
   </refnamediv>
   <refsect1 role="description">
    &reftitle.description;
    <methodsynopsis>
     <type>bool</type><methodname>PDOStatement::bindParam</methodname>
     <methodparam><type>mixed</type><parameter>parameter</parameter></methodparam>
     <methodparam><type>mixed</type><parameter role="reference">variable</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>data_type</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
     <methodparam choice="opt"><type>mixed</type><parameter>driver_options</parameter></methodparam>
    </methodsynopsis>
    <para>
     Binds a PHP variable to a corresponding named or question mark placeholder
     in the SQL statement that was use to prepare the statement.  Unlike
     <function>PDOStatement::bindValue</function>, the variable is bound as a
     reference and will only be evaluated at the time that
     <function>PDOStatement::execute</function> is called.
    </para>
    <para>
     Most parameters are input parameters, that is, parameters that are used
     in a read-only fashion to build up the query.  Some drivers support the
     invocation of stored procedures that return data as output parameters,
     and some also as input/output parameters that both send in data and are
     updated to receive it.
    </para>

   </refsect1>

   <refsect1 role="parameters">
    &reftitle.parameters;
    <para>
     <variablelist>
      <varlistentry>
       <term><parameter>parameter</parameter></term>
        <listitem>
         <para>
          Parameter identifier. For a prepared statement using named
          placeholders, this will be a parameter name of the form
          <varname>:name</varname>. For a prepared statement using
          question mark placeholders, this will be the 1-indexed position of
          the parameter. 
         </para>
        </listitem>
       </varlistentry>
      <varlistentry>
       <term><parameter>variable</parameter></term>
        <listitem>
         <para>
          Name of the PHP variable to bind to the SQL statement parameter.
         </para>
        </listitem>
       </varlistentry>
      <varlistentry>
       <term><parameter>data_type</parameter></term>
        <listitem>
         <para>
          Explicit data type for the parameter using the PDO::PARAM_*
          constants. To return an INOUT parameter from a stored procedure, 
          use the bitwise OR operator to set the PDO::PARAM_INPUT_OUTPUT bits
          for the <parameter>data_type</parameter> parameter.
         </para>
        </listitem>
       </varlistentry>
      <varlistentry>
       <term><parameter>length</parameter></term>
        <listitem>
         <para>
          Length of the data type. To indicate that a parameter is an OUT
          parameter from a stored procedure, you must explicitly set the
          length.
         </para>
        </listitem>
       </varlistentry>
      <varlistentry>
       <term><parameter>driver_options</parameter></term>
       <listitem>
        <para>
         
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>

   <refsect1 role="examples">
    &reftitle.examples;
    <example><title>Execute a prepared statement with named 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 < :calories AND colour = :colour');
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);
$sth->bindParam(':colour', $colour, PDO::PARAM_STR, 12);
$sth->execute();
?>
]]>
     </programlisting>
    </example>

    <example><title>Execute a prepared statement with question mark 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>Pass a NULL value into a prepared statement</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 < :calories AND colour = :colour');
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);

/* Find fruit with a NULL value in the colour column */
$sth->bindParam(':colour', $colour, PDO::PARAM_NULL);

$sth->execute();
?>
]]>
     </programlisting>
    </example>
-->
    <example><title>Call a stored procedure with an INOUT parameter</title>
     <programlisting role='php'>
<![CDATA[
<?php
/* Call a stored procedure with an INOUT parameter */
$colour = 'red';
$sth = $dbh->prepare('CALL puree_fruit(?)');
$sth->bindParam(1, $colour, PDO::PARAM_STR|PDO::PARAM_INPUT_OUTPUT, 12);
$sth->execute();
print("After pureeing fruit, the colour is: $colour");
?>
]]>
     </programlisting>
    </example>

   </refsect1>

   <refsect1 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>PDO::prepare</function></member>
      <member><function>PDOStatement::execute</function></member>
      <member><function>PDOStatement::bindValue</function></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:"../../../../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
-->