<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
  <refentry id="function.oci-bind-by-name">
   <refnamediv>
    <refname>oci_bind_by_name</refname>
    <refpurpose>
     Binds the PHP variable to the Oracle placeholder
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>oci_bind_by_name</methodname>
      <methodparam><type>resource</type><parameter>stmt</parameter></methodparam>
      <methodparam><type>string</type><parameter>ph_name</parameter></methodparam>
      <methodparam><type>mixed</type><parameter role="reference">variable</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>maxlength</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>type</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>oci_bind_by_name</function> binds the PHP variable
     <parameter>variable</parameter> to the Oracle placeholder
     <parameter>ph_name</parameter>.  Whether it will be used for
     input or output will be determined at run-time and the necessary
     storage space will be allocated. The <parameter>length</parameter> 
     parameter sets the maximum length for the bind. If you set 
     <parameter>length</parameter> to -1
     <function>oci_bind_by_name</function> will use the current length of
     <parameter>variable</parameter> to set the maximum length.
    </para>
    <para>
     If you need to bind an abstract datatype (LOB/ROWID/BFILE) you
     need to allocate it first using the
     <function>oci_new_descriptor</function> function. The
     <parameter>length</parameter> is not used for abstract datatypes
     and should be set to -1. The <parameter>type</parameter> parameter
     tells Oracle which descriptor is used. Possible
     values are: 
     <itemizedlist>
      <listitem>
       <para>
        <constant>SQLT_FILE</constant> - for BFILEs;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_CFILE</constant> - for CFILEs;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_CLOB</constant> - for CLOBs;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_BLOB</constant> - for BLOBs;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_RDD</constant> - for ROWIDs;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_NTY</constant> - for named datatypes;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_INT</constant> - for integers;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_CHR</constant> - for VARCHARs;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_BIN</constant> - for RAW columns;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_LNG</constant> - for LONG columns;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_LBI</constant> - for LONG RAW columns;
       </para>
      </listitem>
      <listitem>
       <para>
        <constant>SQLT_RSET</constant> - for cursors, that were created
        before with <function>oci_new_cursor</function>.
       </para>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     <example>
      <title><function>oci_bind_by_name</function>example</title>
      <programlisting role="php">
<![CDATA[
<?php
/* oci_bind_by_name example thies at thieso dot net (980221)
  inserts 3 records into emp, and uses the ROWID for updating the 
  records just after the insert.
*/

$conn = oci_connect("scott", "tiger");

$stmt = oci_parse($conn, "
                          INSERT INTO 
                                     emp (empno, ename) 
                                              VALUES 
                                     (:empno,:ename) 
                            RETURNING 
                                     ROWID 
                                 INTO 
                                     :rid
                                         ");

$data = array(
              1111 => "Larry", 
              2222 => "Bill", 
              3333 => "Jim"
             );

$rowid = oci_new_descriptor($conn, OCI_D_ROWID);

oci_bind_by_name($stmt, ":empno", $empno, 32);
oci_bind_by_name($stmt, ":ename", $ename, 32);
oci_bind_by_name($stmt, ":rid",   $rowid, -1, OCI_B_ROWID);

$update = oci_parse($conn, "
                            UPDATE
                                  emp 
                               SET 
                                  sal = :sal 
                             WHERE 
                                  ROWID = :rid
                             ");
oci_bind_by_name($update, ":rid", $rowid, -1, OCI_B_ROWID);
oci_bind_by_name($update, ":sal", $sal,   32);

$sal = 10000;

foreach ($data as $empno => $ename) {
    oci_execute($stmt);
    oci_execute($update);
} 

$rowid->free();

oci_free_statement($update);
oci_free_statement($stmt);

$stmt = oci_parse($conn, "
                          SELECT 
                                * 
                            FROM 
                                emp 
                           WHERE 
                                empno 
                              IN 
                                (1111,2222,3333)
                              ");
oci_execute($stmt);
                              
while ($row = oci_fetch_assoc($stmt)) {
    var_dump($row);
}

oci_free_statement($stmt);

/* delete our "junk" from the emp table.... */
$stmt = oci_parse($conn, "
                          DELETE FROM
                                     emp 
                                WHERE 
                                     empno 
                                   IN 
                                     (1111,2222,3333)
                                   ");
oci_execute($stmt);
oci_free_statement($stmt);

oci_close($conn);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Remember, this function strips trailing whitespaces. See the following
     example:
    </para>
    <para>
     <example>
      <title><function>oci_bind_by_name</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
    $connection = oci_connect('apelsin','kanistra');
    $query = "INSERT INTO test_table VALUES(:id, :text)";

    $statement = oci_parse($query);
    oci_bind_by_name($statement, ":id", 1);
    oci_bind_by_name($statement, ":text", "trailing spaces follow     ");
    oci_execute($statement);
    /*
     This code will insert into DB string 'trailing spaces follow', without
     trailing spaces
    */
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title><function>oci_bind_by_name</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
    $connection = oci_connect('apelsin','kanistra');
    $query = "INSERT INTO test_table VALUES(:id, 'trailing spaces follow      ')";

    $statement = oci_parse($query);
    oci_bind_by_name($statement, ":id", 1);
    oci_execute($statement);
    /*
     And this code will add 'trailing spaces follow      ', preserving
     trailing whitespaces
    */
?>
]]>
      </programlisting>
     </example>
    </para>
    <warning>
     <para>
      Do not use <link
       linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> or 
      <function>addslashes</function> and <function>oci_bind_by_name</function> 
      simultaneously as no quoting is needed and any magically applied quotes 
      will be written into your database as <function>oci_bind_by_name</function> 
      is not able to distinguish magically added quotings from those added
      intentionally.
     </para> 
    </warning>
    <para>
     &return.success;
    </para>
    <note>
     <para>
      In PHP versions before 5.0.0 you must use <function>ocibindbyname</function> instead. 
      This name still can be used, it was left as alias of
      <function>oci_bind_by_name</function> for downwards compatability. 
      This, however, is deprecated and not recommended.
     </para>
    </note>
   </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
-->