<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- Purpose: database.vendors -->
<!-- Membership: bundled, external -->

 <reference id="ref.oci8">
  <title>Oracle Functions</title>
  <titleabbrev>OCI8</titleabbrev>

  <partintro>
   <section id="oci8.intro">
    &reftitle.intro;
    <para>
     These functions allow you to access Oracle 10, Oracle 9, Oracle 8 and
     Oracle 7 databases using the Oracle Call Interface (OCI). They
     support binding of PHP variables to Oracle placeholders, have full
     LOB, FILE and ROWID support, and allow you to use user-supplied
     define variables.
    </para>
   </section>

   <section id="oci8.requirements">
    &reftitle.required;
   <para>
    You will need the Oracle client libraries to use this extension.
    Windows users will need libraries with version at least 10 to use the
    <filename>php_oci8.dll</filename>.
   </para>
   <para>
    The most convenient way to install all the required files
    is to use Oracle Instant Client, which is available from here:
    <ulink url="&url.oracle.instant.client;">&url.oracle.instant.client;</ulink>.
    To work with OCI8 module "basic" version of Oracle Instant Client is
    enough. Instant Client does not need ORACLE_SID or ORACLE_HOME environment
    variables set. You still may need to set LD_LIBRARY_PATH and NLS_LANG, though.
   </para>
   <para>
    Before using this extension, make sure that you have set up your
    Oracle environment variables properly for the Oracle user, as well
    as your web daemon user. These variables should be set up
    <emphasis>before</emphasis> you start your web-server. The
    variables you might need to set are as follows:
    <itemizedlist>
     <listitem>
      <simpara>
       ORACLE_HOME
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       ORACLE_SID
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       LD_PRELOAD
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       LD_LIBRARY_PATH
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       NLS_LANG
      </simpara>
     </listitem>
    </itemizedlist>
     For less frequently used Oracle environment variables such as
     TNS_ADMIN, TWO_TASK, ORA_TZFILE, and the various Oracle
     globalization settings like ORA_NLS33, ORA_NLS10 and the NLS_*
     variables refer to Oracle documentation.
   </para>
   <para>
    After setting up the environment variables for your webserver user,
    be sure to also add the webserver user (nobody, www) to the oracle
    group.
   </para>
   <note>
    <title>If your webserver doesn't start or crashes at startup</title>
    <para>
     Check that Apache is linked with the pthread library:
    </para>
    <para>
     <informalexample>
      <screen>
<![CDATA[
# ldd /www/apache/bin/httpd
    libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
    libm.so.6 => /lib/libm.so.6 (0x4002f000)
    libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
    libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
    libc.so.6 => /lib/libc.so.6 (0x4007e000)
    /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
]]>
      </screen>
     </informalexample>
    </para>
    <para>
     If the libpthread is not listed you have to reinstall Apache:
    </para>
    <para>
     <informalexample>
      <screen>
<![CDATA[
# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install
]]>
      </screen>
     </informalexample>
    </para>
    <para>
      Please note that on some systems, like UnixWare it is libthread
      instead of libpthread. PHP and Apache have to be configured
      with EXTRA_LIBS=-lthread.
    </para>
   </note>
   </section>

   &reference.oci8.ini;

   &reference.oci8.constants;

   <section id="oci8.examples">
    &reftitle.examples;
    <para>
     <example>
      <title>Basic query</title>
       <programlisting role="php">
<![CDATA[
<?php

  $conn = oci_connect('hr', 'hr', 'orcl');
  if (!$conn) {
    $e = oci_error();
    print htmlentities($e['message']);
    exit;
  }

  $query = 'SELECT * FROM DEPARTMENTS';

  $stid = oci_parse($conn, $query);
  if (!$stid) {
    $e = oci_error($conn);
    print htmlentities($e['message']);
    exit;
  }

  $r = oci_execute($stid, OCI_DEFAULT);
  if (!$r) {
    $e = oci_error($stid);
    echo htmlentities($e['message']);
    exit;
  }

  print '<table border="1">';
  while ($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) {
    print '<tr>';
       foreach ($row as $item) {
         print '<td>'.($item?htmlentities($item):'&nbsp;').'</td>';
       }
       print '</tr>';
  }
  print '</table>';

  oci_close($conn);
?>
]]>
       </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>Insert with bind variables</title>
       <programlisting role="php">
<![CDATA[
<?php

  // Before running, create the table:
  //   CREATE TABLE MYTABLE (mid NUMBER, myd VARCHAR2(20));

  $conn = oci_connect('scott', 'tiger', 'orcl');

  $query = 'INSERT INTO MYTABLE VALUES(:myid, :mydata)';

  $stid = oci_parse($conn, $query);

  $id = 60;
  $data = 'Some data';

  oci_bind_by_name($stid, ':myid', $id);
  oci_bind_by_name($stid, ':mydata', $data);

  $r = oci_execute($stid);

  if ($r)
    print "One row inserted";

  oci_close($conn);

?>
]]>
       </programlisting>
     </example>
    </para>


    <para>
    <example>
     <title>Inserting data into a CLOB column</title>
      <programlisting role="php">
<![CDATA[
<?php

// Before running, create the table:
//     CREATE TABLE MYTABLE (mykey NUMBER, myclob CLOB);

$conn = oci_connect('scott', 'tiger', 'orcl');

$mykey = 12343;  // arbitrary key for this example;

$sql = "INSERT INTO mytable (mykey, myclob)
        VALUES (:mykey, EMPTY_CLOB())
        RETURNING myclob INTO :myclob";

$stid = oci_parse($conn, $sql);
$clob = oci_new_descriptor($conn, OCI_D_LOB);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
oci_execute($stid, OCI_DEFAULT);
$clob->save("A very long string");

oci_commit($conn);

// Fetching CLOB data

$query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';

$stid = oci_parse ($conn, $query);
oci_bind_by_name($stid, ":mykey", $mykey, 5);
oci_execute($stid, OCI_DEFAULT);

print '<table border="1">';
while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
  $result = $row['MYCLOB']->load();
  print '<tr><td>'.$result.'</td></tr>';
}
print '</table>';

?>
]]>
     </programlisting>
    </example>
    </para>
    <para>
     You can easily access stored procedures in the same way as you
     would from the command line.
    <example>
     <title>Using Stored Procedures</title>
      <programlisting role="php">
<![CDATA[
<?php
// by webmaster at remoterealty dot com
$sth = oci_parse($dbh, "begin sp_newaddress( :address_id, '$firstname',
 '$lastname', '$company', '$address1', '$address2', '$city', '$state',
 '$postalcode', '$country', :error_code );end;");

// This calls stored procedure sp_newaddress, with :address_id being an
// in/out variable and :error_code being an out variable.
// Then you do the binding:

   oci_bind_by_name($sth, ":address_id", $addr_id, 10);
   oci_bind_by_name($sth, ":error_code", $errorcode, 10);
   oci_execute($sth);

?>
]]>
      </programlisting>
    </example>
    </para>
   </section>

   <section id="oci8.connection">
    <title>Connecting Handling</title>
    <para>
     The oci8 extension provides you with 3 different functions for
     connecting to Oracle.  It is up to you to use the most appropriate
     function for your application, and the information in this section is
     intended to help you make an informed choice.
    </para>
    <para>
     Connecting to an Oracle server is a reasonably expensive operation, in
     terms of the time that it takes to complete.  The <function>oci_pconnect</function>
     function uses a persistent cache of connections that can be re-used
     across different script requests.  This means that you will typically
     only incur the connection overhead once per php process (or apache child).
    </para>
    <para>
     If your application connects to Oracle using a different set of
     credentials for each web user, the persistent cache employed by
     <function>oci_pconnect</function> will become less useful as the
     number of concurrent users increases, to the point where it may
     start to adversely affect the overall performance of your Oracle
     server due to maintaining too many idle connections. If your
     application is structured in this way, it is recommended that
     you either tune your application using the <link
      linkend="ini.oci8.max_persistent">oci8.max_persistent</link> and <link
      linkend="ini.oci8.persistent_timeout">oci8.persistent_timeout</link>
     configuration settings (these will give you control over the
     persistent connection cache size and lifetime) or use
     <function>oci_connect</function> instead.
    </para>
    <para>
     Both <function>oci_connect</function> and <function>oci_pconnect</function>
     employ a connection cache; if you make multiple calls to
     <function>oci_connect</function>, using the same parameters, in a
     given script, the second and subsequent calls return the existing
     connection handle.  The cache used by <function>oci_connect</function>
     is cleaned up at the end of the script run, or when you explicitly close
     the connection handle. <function>oci_pconnect</function> has similar
     behaviour, although its cache is maintained separately and survives
     between requests.
    </para>
    <para>
     This caching feature is important to remember, because it gives the
     appearance that the two handles are not transactionally isolated (they
     are in fact the same connection handle, so there is no isolation of any
     kind).  If your application needs two separate, transactionally isolated
     connections, you should use <function>oci_new_connect</function>.
    </para>
    <para>
     <function>oci_new_connect</function> always creates a new connection to
     the Oracle server, regardless of what other connections might already exist.
     High traffic web applications should try to avoid using
     <function>oci_new_connect</function>, especially in the busiest sections of
     the application.
    </para>
   </section>

   <section id="oci8.datatypes">
    <title>Datatypes supported by the driver</title>
    <table>
     <title>The driver supports the following types when binding parameters using
      <function>oci_bind_by_name</function> function:</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Type</entry>
        <entry>Mapping</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>SQLT_NTY</entry>
        <entry>Maps a native collection type from a PHP collection object,
         such as those created by <function>oci_new_collection</function>.</entry>
       </row>
       <row>
        <entry>SQLT_BFILEE</entry>
        <entry>Maps a native descriptor, such as those created by
         <function>oci_new_descriptor</function>.</entry>
       </row>
       <row>
        <entry>SQLT_CFILEE</entry>
        <entry>Maps a native descriptor, such as those created by
         <function>oci_new_descriptor</function>.</entry>
       </row>
       <row>
        <entry>SQLT_CLOB</entry>
        <entry>Maps a native descriptor, such as those created by
         <function>oci_new_descriptor</function>.</entry>
       </row>
       <row>
        <entry>SQLT_BLOB</entry>
        <entry>Maps a native descriptor, such as those created by
         <function>oci_new_descriptor</function>.</entry>
       </row>
       <row>
        <entry>SQLT_RDD</entry>
        <entry>Maps a native descriptor, such as those created by
         <function>oci_new_descriptor</function>.</entry>
       </row>
       <row>
        <entry>SQLT_NUM</entry>
        <entry>Converts the PHP parameter to a 'C' long type, and binds to
         that value.</entry>
       </row>
       <row>
        <entry>SQLT_RSET</entry>
        <entry>Maps a native statement handle, such as those created by
         <function>oci_parse</function> or those retrieved from other OCI queries.</entry>
       </row>
       <row>
        <entry>SQLT_CHR and any other type</entry>
        <entry>Converts the PHP parameter to a string type and binds as a
         string.</entry>
       </row>
      </tbody>
     </tgroup>
    </table>

    <table>
     <title>The following types are supported when retrieving columns from a result set:</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Type</entry>
        <entry>Mapping</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>SQLT_RSET</entry>
        <entry>Creates an oci statement resource to represent the the cursor.</entry>
       </row>
       <row>
        <entry>SQLT_RDD</entry>
        <entry>Creates a ROWID object.</entry>
       </row>
       <row>
        <entry>SQLT_BLOB</entry>
        <entry>Creates a LOB object.</entry>
       </row>
       <row>
        <entry>SQLT_CLOB</entry>
        <entry>Creates a LOB object.</entry>
       </row>
       <row>
        <entry>SQLT_BFILE</entry>
        <entry>Creates a LOB object.</entry>
       </row>
       <row>
        <entry>SQLT_LNG</entry>
        <entry>Bound as SQLT_CHR, returned as a string</entry>
       </row>
       <row>
        <entry>SQLT_LBI</entry>
        <entry>Bound as SQLT_BIN, returned as a string</entry>
       </row>
       <row>
        <entry>Any other type</entry>
        <entry>Bound as SQLT_CHR, returned as a string</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </section>

  </partintro>

&reference.oci8.functions;

 </reference>
<!-- 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
-->