<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 331130 $ -->

<refentry xml:id="function.cubrid-bind" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>cubrid_bind</refname>
  <refpurpose>Bind variables to a prepared statement as parameters</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>cubrid_bind</methodname>
   <methodparam><type>resource</type><parameter>req_identifier</parameter></methodparam>
   <methodparam><type>int</type><parameter>bind_index</parameter></methodparam>
   <methodparam><type>mixed</type><parameter>bind_value</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>bind_value_type</parameter></methodparam>
  </methodsynopsis>
  <para>
   The <function>cubrid_bind</function> function is used to bind values to a
   corresponding named or question mark placeholder in the SQL statement that
   was passed to <function>cubrid_prepare</function>. If
   <parameter>bind_value_type</parameter> is not given, string will be the
   default.
  </para>
  <note>
   <para>
    If the type of data to be bound is BLOB/CLOB, CUBRID will try to map the
    data as a PHP stream. If the actually bind value type is not stream,
    CUBRID will convert it to string, and use it as the full path and file
    name of a file on the client filesystem.
   </para>
   <para>
    If the type of data to be bound explicitly is ENUM, the $bind_value
    argument should be the enum element which is in string format.
   </para>
   <para>
    In CUBRID shard envrioment, the $bind_value_type must be included in 
    the cubrid_bind function.
   </para>
  </note>
  <para>
  The following table shows the types of substitute values.
  </para>
  <para>
   <table>
    <title>CUBRID Bind Date Types</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Support</entry>
       <entry>Bind Type</entry>
       <entry>Corresponding SQL Type</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Supported</entry>
       <entry>STRING</entry>
       <entry>CHAR, VARCHAR</entry>
      </row>
      <row>
       <entry></entry>
       <entry>NCHAR</entry>
       <entry>NCHAR, NVARCHAR</entry>
      </row>
      <row>
       <entry></entry>
       <entry>BIT</entry>
       <entry>BIT, VARBIT</entry>
      </row>
      <row>
       <entry></entry>
       <entry>NUMERIC or NUMBER</entry>
       <entry>SHORT, INT, NUMERIC</entry>
      </row>
      <row>
       <entry></entry>
       <entry>FLOAT</entry>
       <entry>FLOAT</entry>
      </row>
      <row>
       <entry></entry>
       <entry>DOUBLE</entry>
       <entry>DOUBLE</entry>
      </row>
      <row>
       <entry></entry>
       <entry>TIME</entry>
       <entry>TIME</entry>
      </row>
      <row>
       <entry></entry>
       <entry>DATE</entry>
       <entry>DATE</entry>
      </row>
      <row>
       <entry></entry>
       <entry>TIMESTAMP</entry>
       <entry>TIMESTAMP</entry>
      </row>
      <row>
       <entry></entry>
       <entry>OBJECT</entry>
       <entry>OBJECT</entry>
      </row>
      <row>
       <entry></entry>
       <entry>ENUM</entry>
       <entry>ENUM</entry>
      </row>
      <row>
       <entry></entry>
       <entry>BLOB</entry>
       <entry>BLOB</entry>
      </row>
      <row>
       <entry></entry>
       <entry>CLOB</entry>
       <entry>CLOB</entry>
      </row>
      <row>
       <entry></entry>
       <entry>NULL</entry>
       <entry>NULL</entry>
      </row>
      <row>
       <entry>Not supported</entry>
       <entry>SET</entry>
       <entry>SET</entry>
      </row>
      <row>
       <entry></entry>
       <entry>MULTISET</entry>
       <entry>MULTISET</entry>
      </row>
      <row>
       <entry></entry>
       <entry>SEQUENCE</entry>
       <entry>SEQUENCE</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>

 <refsect1 role="parameters">
 &reftitle.parameters;
 <para>
  <variablelist>
    <varlistentry>
  <term><parameter>req_identifier</parameter></term>
  <listitem><para>Request identifier as a result of
    <function>cubrid_prepare</function>.</para></listitem>
   </varlistentry>
   <varlistentry>
  <term><parameter>bind_index</parameter></term>
  <listitem><para>Location of binding parameters. It starts with 1.</para></listitem>
   </varlistentry>
   <varlistentry>
  <term><parameter>bind_value</parameter></term>
  <listitem><para>Actual value for binding.</para></listitem>
   </varlistentry>
   <varlistentry>
  <term><parameter>bind_value_type</parameter></term>
  <listitem><para>A type of the value to bind. (It is omitted by default.
    Thus, the system internally uses string by default. However, you need to
    specify the exact type of the value as an argument when they are NCHAR,
    BIT, or BLOB/CLOB).</para></listitem>
   </varlistentry>
  </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
    &true;, when process is successful.
  </para>
  <para>
    &false;, when process is unsuccessful.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.3.1</entry>
       <entry>
        Added BLOB/CLOB data types support.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>cubrid_bind</function> example</title>
   <programlisting role="php">
<![CDATA[
<?php
$conn = cubrid_connect("localhost", 33000, "demodb", "dba");

$result = cubrid_execute($conn, "SELECT code FROM event WHERE sports='Basketball' and gender='M'");
$row = cubrid_fetch_array($result, CUBRID_ASSOC);
$event_code = $row["code"];

cubrid_close_request($result);

$game_req = cubrid_prepare($conn, "SELECT athlete_code FROM game WHERE host_year=1992 and event_code=? and nation_code='USA'");
cubrid_bind($game_req, 1, $event_code, "number");
cubrid_execute($game_req);

printf("--- Dream Team (1992 United States men's Olympic basketball team) ---\n");
while ($athlete_code = cubrid_fetch_array($game_req, CUBRID_NUM)) {
    $athlete_req = cubrid_prepare($conn, "SELECT name FROM athlete WHERE code=? AND nation_code='USA' AND event='Basketball' AND gender='M'");
    cubrid_bind($athlete_req, 1, $athlete_code[0], "number");
    cubrid_execute($athlete_req);
    $row = cubrid_fetch_assoc($athlete_req);
    printf("%s\n", $row["name"]);
}

cubrid_close_request($game_req);
cubrid_close_request($athlete_req);

cubrid_disconnect($conn);
?>
]]>
   </programlisting>
&example.outputs;
    <screen>
<![CDATA[
--- Dream Team (1992 United States men's Olympic basketball team) ---
Stockton John
Robinson David
Pippen Scottie
Mullin C.
Malone Karl
Laettner C.
Jordan Michael
Johnson Earvin
Ewing Patrick
Drexler Clyde
Bird Larry
Barkley Charles
]]>
   </screen>
  </example>

  <example>
   <title><function>cubrid_bind</function> BLOB/CLOB example</title>
   <programlisting role="php">
<![CDATA[
<?php
$con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
if ($con) {
    cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
    cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (doc_content CLOB)");
    $sql = "INSERT INTO php_cubrid_lob_test(doc_content) VALUES(?)"; 
    $req = cubrid_prepare($con, $sql); 

    $fp = fopen("book.txt", "rb");

    cubrid_bind($req, 1, $fp, "clob"); 
    cubrid_execute($req);  
}
?>
]]>
   </programlisting>
  </example>

  <example>
   <title><function>cubrid_bind</function> BLOB/CLOB example</title>
   <programlisting role="php">
<![CDATA[
<?php
$con = cubrid_connect("localhost", 33000, "demodb", "dba", "");
if ($con) {
    cubrid_execute($con,"DROP TABLE if exists php_cubrid_lob_test");
    cubrid_execute($con,"CREATE TABLE php_cubrid_lob_test (image BLOB)");
    $sql = "INSERT INTO php_cubrid_lob_test(image) VALUES(?)"; 
    $req = cubrid_prepare($con, $sql); 

    cubrid_bind($req, 1, "cubrid_logo.png", "blob"); 
    cubrid_execute($req);  
}
?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>cubrid_execute</function></member>
    <member><function>cubrid_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
-->