mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 10:28:54 +00:00
dbf9bacd68
clarify that "basic" package is enough git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@205508 c90b9560-bf6c-de11-be94-00142212c4b1
479 lines
14 KiB
XML
479 lines
14 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.18 $ -->
|
|
<!-- 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):' ').'</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
|
|
-->
|
|
|
|
|