diff --git a/reference/oci8/book.xml b/reference/oci8/book.xml
index 75d87d1009..aa144de42b 100644
--- a/reference/oci8/book.xml
+++ b/reference/oci8/book.xml
@@ -11,11 +11,13 @@
&reftitle.intro;
- These functions allow you to access Oracle 11G, 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
- defined variables.
+ These functions allow you to access Oracle Database 11g, 10g, 9i
+ and 8i. They support SQL and PL/SQL statements. Basic features
+ include transaction control, binding of PHP variables to Oracle
+ placeholders, and support for large object (LOB) types and
+ collections. Oracle's scalability features such as Database
+ Resident Connection Pooling (DRCP) and result caching are also
+ supported.
diff --git a/reference/oci8/ini.xml b/reference/oci8/ini.xml
index 422b3a1849..0ee8f82491 100644
--- a/reference/oci8/ini.xml
+++ b/reference/oci8/ini.xml
@@ -17,46 +17,58 @@
- oci8.privileged_connect
- "0"
+ oci8.connection_class
+ ""
+ PHP_INI_ALL
+ Available since PHP 5.3 (PECL OCI8 1.3).
+
+
+ oci8.default_prefetch
+ "100"
PHP_INI_SYSTEM
- Available since PHP 5.1.2.
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
+
+
+ oci8.events
+ Off
+ PHP_INI_SYSTEM
+ Available since PHP 5.3 (PECL OCI8 1.3).
oci8.max_persistent
"-1"
PHP_INI_SYSTEM
- Available since PHP 5.1.2.
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
+
+
+ oci8.old_oci_close_semantics
+ Off
+ PHP_INI_SYSTEM
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
oci8.persistent_timeout
"-1"
PHP_INI_SYSTEM
- Available since PHP 5.1.2.
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
oci8.ping_interval
"60"
PHP_INI_SYSTEM
- Available since PHP 5.1.2.
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
+
+
+ oci8.privileged_connect
+ Off
+ PHP_INI_SYSTEM
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
oci8.statement_cache_size
"20"
PHP_INI_SYSTEM
- Available since PHP 5.1.2.
-
-
- oci8.default_prefetch
- "10"
- PHP_INI_SYSTEM
- Available since PHP 5.1.2.
-
-
- oci8.old_oci_close_semantics
- "0"
- PHP_INI_SYSTEM
- Available since PHP 5.1.2.
+ Available since PHP 5.1.2 (PECL OCI8 1.1).
@@ -67,15 +79,108 @@
-
+
- oci8.privileged_connect
+ oci8.connection_class
+ string
+
+
+
+ This user defined text is used by Oracle 11g Database
+ Resident Connection Pooling (DRCP) connections to
+ sub-partition the connection pool. It allows OCI8 persistent
+ connections from an application to reuse database sessions
+ from a previous PHP script, giving better scalability. When
+ an application uses a database pooled process previously used
+ with a different connection class, the session settings such
+ as the default Oracle date format are reset. This prevents
+ accidental sharing of information between different
+ applications.
+
+
+ The value can be set at runtime
+ with ini_set prior to connecting.
+
+
+ To use DRCP, OCI8 must be linked with Oracle 11g libraries
+ and the database must be Oracle 11g. The connection pool
+ must be enabled in the database,
+ the oci8.connection_class should be set to
+ the same string for all web servers running the same
+ application, and the OCI8 connection string must specify to
+ use a pooled server.
+
+
+
+
+
+ oci8.default_prefetch
+ int
+
+
+
+ This option sets the default number of extra rows that will
+ be fetched and cached automatically whenever a low-level
+ request for data from the database is made. Setting a value
+ of 0 turns off prefetching.
+
+
+ The prefetch value does not alter the number of rows that
+ functions like oci_fetch_array return to
+ the user; the prefetching and caching of rows is handled
+ internally in OCI8.
+
+
+ The value can be set per-statement
+ with oci_set_prefetch prior to statement
+ execution.
+
+
+ In PHP 5.3 (PECL OCI8 1.3.4) the default value was increased
+ from 10 to 100.
+
+
+ In PHP 5.3.2 (PECL OCI8 1.4) the minimum value settable was
+ reduced from 1 to 0,
+ allowing prefetching to be turned off.
+
+
+
+ A larger prefetch can result in improved performance, at the
+ cost of some increased memory usage. For queries that return
+ large amounts of data, the performance benefit can be
+ significant.
+
+
+
+
+
+
+ oci8.events
boolean
- This option enables privileged connections using external credentials
- (OCI_SYSOPER, OCI_SYSDBA).
+ Using On allows PHP to be notified of
+ database Fast Application Notification (FAN) events.
+
+
+ Without FAN, when a database instance or machine node fails
+ unexpectedly, PHP applications may be blocked waiting for a
+ database response until a TCP timeout expires. With FAN
+ events, PHP applications are quickly notified of failures
+ that affect their established database connections. The OCI8
+ extension will clean up unusable connections in the
+ persistent connection cache.
+
+
+ When using On, the database must also be
+ configured to post FAN events.
+
+
+ FAN support is available when OCI8 is linked with Oracle
+ 10gR2 (or later) libraries and connected to Oracle Database
+ 10gR2 (or later).
@@ -86,84 +191,12 @@
- The maximum number of persistent OCI8 connections per process.
- Setting this option to -1 means that there is no limit.
+ The maximum number of persistent OCI8 connections per PHP
+ process. Setting this option to -1 means that there is no
+ limit.
-
-
- oci8.persistent_timeout
- int
-
-
-
- The maximum length of time (in seconds) that a given process is
- allowed to maintain an idle persistent connection.
- Setting this option to -1 means that idle persistent connections will
- be maintained forever.
-
-
-
-
-
- oci8.ping_interval
- int
-
-
-
- The length of time (in seconds) that must pass before issuing a ping
- during oci_pconnect. When set to 0, persistent
- connections will be pinged every time they are reused. To disable
- pings completely, set this option to -1.
-
-
-
- Disabling pings will cause oci_pconnect calls to operate at the
- highest efficiency, but may cause PHP to not detect faulty connections,
- such as those caused by network partitions, or if the Oracle server has
- gone down since PHP connected, until later in the script. Consult the
- oci_pconnect documentation for more information.
-
-
-
-
-
-
- oci8.statement_cache_size
- int
-
-
-
- This option enables statement caching, and specifies how many
- statements to cache. To disable statement caching just set this option to 0.
-
-
-
- A larger cache can result in improved performance, at the cost of
- increased memory usage.
-
-
-
-
-
-
- oci8.default_prefetch
- int
-
-
-
- This option enables statement prefetching and sets the default number
- of rows that will be fetched automatically after statement execution.
-
-
-
- A larger prefetch can result in improved performance, at the cost of
- increased memory usage.
-
-
-
-
oci8.old_oci_close_semantics
@@ -177,11 +210,115 @@
closed until the end of the script. This is for backward
compatibility only. If you find that you need to enable this
setting, you are strongly encouraged to
- remove the oci_close calls from your
+ adjust the oci_close calls in your
application instead of enabling this option.
+
+
+ oci8.persistent_timeout
+ int
+
+
+
+ The maximum number of seconds that a PHP process is allowed
+ to keep an idle persistent connection open. Setting this
+ option to -1 means that idle persistent connections will be
+ retained until the PHP process terminates or the connection
+ is explicitly closed with oci_close.
+
+
+
+ In PHP, the expiry of idle resources is not alarm-based. It
+ occurs when PHP finishes processing a script and checks the
+ last-used timestamp of resources. Hence there is a paradox
+ that idle connections can only be closed when there is some
+ activity (though not necessarily OCI8 related) in the PHP
+ process. The introduction of Database Resident Connection
+ Pooling (DRCP) in Oracle 11g resolves the memory and
+ resource issues that oci8.max_persistent
+ and oci8.persistent_timeout previously
+ attempted to overcome.
+
+
+
+
+ In PHP 5.3 (PECL OCI8 1.3), persistent connections can be
+ closed with oci_close.
+
+
+
+
+
+
+ oci8.ping_interval
+ int
+
+
+
+ The number of seconds that must pass before issuing a ping
+ during oci_pconnect. A ping ensures
+ that the database connection is valid. When set to 0,
+ persistent connections will be pinged every
+ time oci_pconnect is called. To disable
+ pings completely, set this option to -1.
+
+
+
+ Disabling pings allows oci_pconnect to
+ operate at the highest efficiency, but PHP may not be able
+ to detect unusable connections, such as caused by network
+ dropout, or if the Oracle database has gone down since PHP
+ connected, until the connection is used later in the
+ script. Consult the
+ oci_pconnect documentation for more information.
+
+
+
+
+
+
+ oci8.privileged_connect
+ boolean
+
+
+
+ This option enables privileged connections using external credentials
+ OCI_SYSOPER or OCI_SYSDBA.
+
+
+
+ Seting this On can allow scripts on web
+ servers running with the appropriate OS user privileges to
+ connect as privileged database users without requiring a
+ database password. This can be a security risk.
+
+
+
+
+
+
+ oci8.statement_cache_size
+ int
+
+
+
+ This option enables statement caching, and specifies how many
+ statements to cache. To disable statement caching just set
+ this option to 0.
+
+
+ Set this value to the size of the working set of statements
+ used by your application. Setting too small a value can cause
+ statements to be flushed from the cache before they are
+ reused.
+
+
+ This option is of most use with persistent connections.
+
+
+