<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry xml:id="function.db2-bind-param" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>db2_bind_param</refname>
  <refpurpose>
   Binds a PHP variable to an SQL statement parameter
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>db2_bind_param</methodname>
   <methodparam><type>resource</type><parameter>stmt</parameter></methodparam>
   <methodparam><type>int</type><parameter>parameter-number</parameter></methodparam>
   <methodparam><type>string</type><parameter>variable-name</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>parameter-type</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>data-type</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>scale</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>

  <para>
   Binds a PHP variable to an SQL statement parameter in a statement resource
   returned by <function>db2_prepare</function>. This function gives you more
   control over the parameter type, data type, precision, and scale for the
   parameter than simply passing the variable as part of the optional input
   array to <function>db2_execute</function>.
  </para>

 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stmt</parameter></term>
     <listitem>
      <para>
       A prepared statement returned from <function>db2_prepare</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>parameter-number</parameter></term>
     <listitem>
      <para>
       Specifies the 1-indexed position of the parameter in the prepared
       statement.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
    <term><parameter>variable-name</parameter></term>
     <listitem>
      <para>
       A string specifying the name of the PHP variable to bind to the
       parameter specified by <parameter>parameter-number</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>parameter-type</parameter></term>
     <listitem>
      <para>
       A constant specifying whether the PHP variable should be bound to the
       SQL parameter as an input parameter (<literal>DB2_PARAM_IN</literal>),
       an output parameter (<literal>DB2_PARAM_OUT</literal>), or as a
       parameter that accepts input and returns output
       (<literal>DB2_PARAM_INOUT</literal>). To avoid memory overhead, you can
       also specify <literal>DB2_PARAM_FILE</literal> to bind the PHP variable
       to the name of a file that contains large object (BLOB, CLOB, or DBCLOB)
       data.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data-type</parameter></term>
     <listitem>
      <para>
       A constant specifying the SQL data type that the PHP variable should be
       bound as: one of <literal>DB2_BINARY</literal>,
       <literal>DB2_CHAR</literal>, <literal>DB2_DOUBLE</literal>, or
       <literal>DB2_LONG</literal> .
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>precision</parameter></term>
     <listitem>
      <para>
       Specifies the precision with which the variable should be bound to the
       database. This parameter can also be used for retrieving XML output values 
       from stored procedures. A non-negative value specifies the maximum size of 
       the XML data that will be retrieved from the database. If this parameter 
       is not used, a default of 1MB will be assumed for retrieving the XML 
       output value from the stored procedure.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>scale</parameter></term>
     <listitem>
      <para>
       Specifies the scale with which the variable should be bound to the
       database.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Binding PHP variables to a prepared statement</title>
    <para>
     The SQL statement in the following example uses two input parameters in
     the WHERE clause. We call <function>db2_bind_param</function> to bind two
     PHP variables to the corresponding SQL parameters. Notice that the PHP
     variables do not have to be declared or assigned before the call to
     <function>db2_bind_param</function>; in the example,
     <literal>$lower_limit</literal> is assigned a value before the call to
     <function>db2_bind_param</function>, but <literal>$upper_limit</literal>
     is assigned a value after the call to
     <function>db2_bind_param</function>. The variables must be bound and, for
     parameters that accept input, must have any value assigned, before calling
     <function>db2_execute</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$sql = 'SELECT name, breed, weight FROM animals
    WHERE weight > ? AND weight < ?';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);

// We can declare the variable before calling db2_bind_param()
$lower_limit = 1;

db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

// We can also declare the variable after calling db2_bind_param()
$upper_limit = 15.0;

if (db2_execute($stmt)) {
    while ($row = db2_fetch_array($stmt)) {
        print "{$row[0]}, {$row[1]}, {$row[2]}\n";
    }
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Pook, cat, 3.2
Rickety Ride, goat, 9.7
Peaches, dog, 12.3
]]>
    </screen>
   </example>
   <example>
    <title>Calling stored procedures with IN and OUT parameters</title>
    <para>
     The stored procedure match_animal in the following example accepts
     three different parameters:
     <orderedlist>
      <listitem>
       <para>
        an input (IN) parameter that accepts the name of the first animal as
        input
       </para>
      </listitem>
      <listitem>
       <para>
        an input-output (INOUT) parameter that accepts the name of the second
        animal as input and returns the string <literal>TRUE</literal> if an
        animal in the database matches that name
       </para>
      </listitem>
      <listitem>
       <para>
        an output (OUT) parameter that returns the sum of the weight of the
        two identified animals
       </para>
      </listitem>
     </orderedlist>
     In addition, the stored procedure returns a result set consisting of the
     animals listed in alphabetic order starting at the animal corresponding
     to the input value of the first parameter and ending at the animal
     corresponding to the input value of the second parameter.
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$sql = 'CALL match_animal(?, ?, ?)';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);

$name = "Peaches";
$second_name = "Rickety Ride";
$weight = 0;

db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

print "Values of bound parameters _before_ CALL:\n";
print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

if (db2_execute($stmt)) {
    print "Values of bound parameters _after_ CALL:\n";
    print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

    print "Results:\n";
    while ($row = db2_fetch_array($stmt)) {
        print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
    }
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Values of bound parameters _before_ CALL:
  1: Peaches 2: Rickety Ride 3: 0

Values of bound parameters _after_ CALL:
  1: Peaches 2: TRUE 3: 22

Results:
  Peaches, dog, 12.3
  Pook, cat, 3.2
  Rickety Ride, goat, 9.7
]]>
    </screen>
   </example>
   <example>
    <title>Inserting a binary large object (BLOB) directly from a file</title>
    <para>
     The data for large objects are typically stored in files, such as XML
     documents or audio files. Rather than reading an entire file into a PHP
     variable, and then binding that PHP variable into an SQL statement, you
     can avoid some memory overhead by binding the file directly to the input
     parameter of your SQL statement. The following example demonstrates how
     to bind a file directly into a BLOB column.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

$picture = "/opt/albums/spook/grooming.jpg";
$rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
$rc = db2_execute($stmt);
?>
]]>
    </programlisting>
   </example>

  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>db2_execute</function></member>
    <member><function>db2_prepare</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:"~/.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
-->