sixd Thu, 10 Dec 2009 17:28:19 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=291958
Log: Remove text recently merged to online doc Changed paths: U php/php-src/branches/PHP_5_3/ext/oci8/README U php/php-src/trunk/ext/oci8/README
Modified: php/php-src/branches/PHP_5_3/ext/oci8/README =================================================================== --- php/php-src/branches/PHP_5_3/ext/oci8/README 2009-12-10 17:13:14 UTC (rev 291957) +++ php/php-src/branches/PHP_5_3/ext/oci8/README 2009-12-10 17:28:19 UTC (rev 291958) @@ -1,454 +1,12 @@ -Installing OCI8 ---------------- +The OCI8 Extension +------------------ -0. Overview -1. Common requirements -2. Installing as a shared extension -3. Installing as a statically compiled extension -4. Installing from PECL to an existing PHP -5. Testing OCI8 -6. Oracle DRCP and FAN Support +The OCI8 extension allows PHP to access Oracle databases. It can be +built using Oracle 9.2, 10, or 11 client libraries. It allows Oracle's +standard cross-version connectivity, for example PHP using Oracle 10.2 +libraries can connect to Oracle Database 9.2 onwards. +This release of OCI8 can be used with PHP versions 4.3.9 to 5.x. -0. Overview ------------ - -The OCI8 extension allows you to access Oracle databases. It can be -built using Oracle 9.2, 10.2, 11.1 or 11.2 client libraries, and -allows Oracle's standard cross-version connectivity. This release can -be used with PHP versions 4.3.9 to 5.x. - -The OCI8 extension is not related to, or used by, PDO_OCI, the PHP -Data Objects (PDO) extension for Oracle. - -1. Common requirements ----------------------- - -This version of PHP OCI8: - - - Will build with Oracle 9.2 (or more recent) client libraries. The - same (or more recent) version of Oracle libraries used when - building OCI8 must also be used at runtime. - - - Can be used with PHP versions 4.3.9 to 5.x. - -If you build PHP with the "ORACLE_HOME" Oracle database or full Oracle -client libraries: - - - you MUST set at least the ORACLE_HOME environment variable and - make it visible for your web server BEFORE it starts. - - - the Oracle software must be readable by the web server. With - Oracle 10.2, see the $ORACLE_HOME/install/changePerm.sh script - included in patch releases. - -If you build PHP with Oracle Instant Client libraries from -http://www.oracle.com/technology/tech/oci/instantclient/index.html - - - either the "basic" or "basic-lite" package is required. - - - the "devel" package is required. - - - you don't have to set ORACLE_HOME and many of the other - environment variables to build PHP with OCI8 support. - -For both ORACLE_HOME and Instant Client installs you may have to set: - - - LD_LIBRARY_PATH: it must include the $ORACLE_HOME/lib or Instant - Client library directory - - - NLS_LANG: if you want to change the default encoding used during - interaction with Oracle servers - -The most appropriate places to add the environment variables are: - - /etc/profile - /etc/profile.local - /etc/profile.d - - -2. Installing as a shared extension ------------------------------------ - -Configure OCI8 using one of the the following configure options: - - a) if you use an Oracle server or Oracle Client installation: - - ./configure --with-oci8=shared,$ORACLE_HOME - - b) with Oracle Instant Client: - - ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib - - If you use an RPM-based installation of Oracle Instant Client, - your configure line will look like this: - - ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib - -Follow the usual building procedure, e.g. "make install". The OCI8 -shared extension oci8.so will be created. It may need to be manually -moved to the PHP extension directory, specified by the extension_dir -option in your php.ini file. - -Edit php.ini file and add the line: - - extension=oci8.so - - -3. Installing as a statically compiled extension ------------------------------------------------- - -Configure OCI8 using one of the the following configure options: - - a) with a common Oracle server or full Oracle client installation - - ./configure --with-oci8=$ORACLE_HOME - - b) with Oracle Instant Client - - ./configure --with-oci8=instantclient,/path/to/instant/client/lib - -Run "make install". - -After successful compile, you do not need to add oci8.so to php.ini. -The module will be usable without any additional actions. - - -4. Installing from PECL to an existing PHP ------------------------------------------- - -The OCI8 extension is also available as a PECL module on -http://pecl.php.net/package/oci8. - -Install using either (a) or (b) below. - - a) Do an automated download and install: - - Set PEARs proxy, if necessary: - - pear config-set http_proxy http://my-proxy.example.com:80/ - - Run - - pecl install oci8 - - When prompted, enter either the value of $ORACLE_HOME, or - "instantclient,/path/to/instant/client/lib" (without quotes). - - b) Alternatively, manually download the PECL package, e.g. oci8-1.3.5.tgz - - Extract the package: - - tar -zxf oci8-1.3.5.tgz - cd oci8-1.3.5 - - Prepare the package: - - phpize - - Configure the package, either using $ORACLE_HOME or Instant Client - - ./configure -with-oci8=shared,$ORACLE_HOME - - or - - ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib - - Install the package: - - make install - -After either install, edit your php.ini file, e.g. /etc/php.ini, and -add the line: - - extension=oci8.so - -Make sure php.ini's "extension_dir" includes the directory that -oci8.so was installed in. - - -5. Testing OCI8 ---------------- - -OCI8 tests are in ext/oci8/tests. When OCI8 tests are run this -directory will contain logs of any failures. - -5.1. Running OCI8 tests on Linux - -5.1.1. Edit ext/oci8/tests/details.inc - - Set the username, password and connection string for the database. - Most tests have been developed using the SYSTEM account: some tests - might fail unless the user has permissions to create necessary - tables, views, procedures etc. - - If the database is on the same machine as PHP, set - $oracle_on_localhost to TRUE. - - If Oracle 11g Database Resident Connection Pooling is being tested, - set $test_drcp to TRUE and ensure the connection string uses an - appropriate pooled server (see section 6.2.2). - - An alternative to editing details.inc is the set the environment - variables - - PHP_OCI8_TEST_USER - PHP_OCI8_TEST_PASS - PHP_OCI8_TEST_DB - PHP_OCI8_TEST_DB_ON_LOCALHOST - PHP_OCI8_TEST_DRCP - - for example: - - $ export PHP_OCI8_TEST_USER=system - $ export PHP_OCI8_TEST_PASS=oracle - $ export PHP_OCI8_TEST_DB=localhost/XE - $ export PHP_OCI8_TEST_DB_ON_LOCALHOST=TRUE - $ export PHP_OCI8_TEST_DRCP=FALSE - -5.1.2. Set any necessary environment variables for the Oracle - database. With Oracle 10g XE do: - - $ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh - - For other versions of the Oracle database do: - - $ . /usr/local/bin/oraenv - -5.1.3. Check your php.ini has E in the variables_order parameter, for - example: - - variables_order = "EGPCS" - -5.1.4. Run the tests: - - $ cd <your php src directory> - $ make test TESTS=ext/oci8 - -5.2. The tests execute rapidly. On fast machines with a local - database configured for light load (e.g. Oracle 10g XE) you might - see random tests fail with ORA-12516 or ORA-12520 errors. To - prevent this, increase the database PROCESSES parameter using the - following steps. - -5.2.1. Connect as the oracle software owner: - - $ su - oracle - -5.2.2. Set the necessary environment variables as in 5.1.2. - -5.2.3. Start the SQL*Plus command line tool and increase PROCESSES - - $ sqlplus / as sysdba - SQL> alter system set processes=100 scope=spfile - -5.2.4. Restart the database: - - SQL> startup force - - -6. Oracle DRCP and FAN Support ------------------------------- - -The PHP OCI8 extension has support for the Oracle Database Resident -Connection Pool (DRCP) and Fast Application Notification (FAN). - -Questions and issues can be raised on the Oracle OTN forum (free -registration required): -http://www.oracle.com/technology/forums/php.html - - -6.1. Oracle Version Compatibility - -The OCI8 extension will compile with Oracle libraries from version -9iR2 onwards. However, full functionality (e.g. DRCP support) is only -available when Oracle 11g is used. - -For general database functionality the version of the Oracle libraries -used by PHP does not necessarily have to match the version of the -database. - - -6.2. Database Resident Connection Pooling (DRCP) - -DRCP allows more efficient use of database machine memory and provides -high scalability. - -For DRCP to be available in OCI8, Oracle client libraries used by PHP -and the version of the Oracle Database must both be 11g. - -Documentation on DRCP is found in several Oracle manuals. For example, -see "Configuring Database Resident Connection Pooling" in the Oracle -Database Administrator's Guide 11g Release 1 (11.1) -http://download.oracle.com/docs/cd/B28359_01/server.111/b28310/manproc004.htm#CHDGIDBA -for usage information. A whitepaper -http://www.oracle.com/technology/tech/oci/pdf/oracledrcp11g.pdf -contains background information on DRCP. - -After building PHP with the OCI8 extension and 11g libraries, follow -these steps: - -6.2.0 Important: if Oracle Database 11.1.0.6 with DRCP connections is - used, then the Oracle database patch for bug 6474441 must be - applied (see section 6.5). Without this patch, "ORA-01000: - maximum open cursors exceeded", "ORA-01001 invalid cursor" or - "ORA-01002 fetch out of sequence" errors may occur. - - If the Oracle 11.1.0.6 database patch cannot be applied, one of - the following three workarounds can be used to disable statement - caching instead: - - (i) Connect using Oracle dedicated or shared servers instead of DRCP. - - (ii) Set PHP's oci8.statement_cache_size to 0. - - (iii) Set an event in the database initialization parameter file: - event="56699 trace name context forever, level 128". - - -6.2.1. As a privileged database administrator, use a program like - SQL*Plus to start the connection pool in the database: - - SQL> execute dbms_connection_pool.start_pool; - - Optional settings control the size and characteristics of the - pool. - -6.2.2. For PHP applications that currently connect using a Network Alias - like: - - $c = oci_pconnect("myuser", "mypassword", "MYDB"); - - Modify your tnsnames.ora file and add the "(SERVER=POOLED)" - clause, for example: - - MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com) - (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales) - (SERVER=POOLED))) - - Alternatively, modify the Easy Connect syntax in PHP and add - ":POOLED" after the service name: - - $c = oci_pconnect("myuser", "mypassword", - "myhost.dom.com:1521/sales:POOLED"); - -6.2.3. Edit php.ini and choose a connection class name. This name - indicates a logical division of the connection pool and can be - used to isolate pooling for separate applications. Any PHP - instance with the same connection class value will share - connections in the pool. - - oci8.connection_class = "MY_APPLICATION_NAME" - -6.2.4. Run your application, connecting to the 11g database. - - -6.3. Fast Application Notification (FAN) Support - -FAN support gives fast connection failover, a high availability -feature. This allows PHP OCI8 scripts to be notified when a database -machine or database instance becomes unavailable. Without FAN, OCI8 -can hang until a TCP timeout occurs and an error is returned, which -might be several minutes. Enabling FAN in OCI8 can allow your -applications to detect errors and re-connect to an available database -instance without the web user being aware of an outage. - -FAN support is available when the Oracle client libraries that PHP -links with and the Oracle Database are either version 10gR2 or 11g. - -FAN benefits users of Oracle's clustering technology (RAC) because -connections to surviving database instances can be immediately made. -Users of Oracle's Data Guard with a broker will see the FAN events -generated when the standby database goes online. Standalone databases -will send FAN events when the database restarts. - -For active connections, when a machine or database instance becomes -unavailable, a connection failure error will be returned by the OCI8 -extension function currently being called. On a subsequent PHP script -re-connect, a connection to a surviving database instance will be -established. The OCI8 extension also transparently cleans up any idle -connections affected by a database machine or instance failure so PHP -connect calls will establish a fresh connection without the script -being aware of any service disruption. - -When oci8.events is On, it is suggested to set oci8.ping_interval to --1 to disable pinging, since enabling FAN events provide pro-active -connection management of idle connections made invalid by a service -disruption. - -To enable FAN support in PHP, after building PHP with Oracle 10gR2 or -11g libraries follow these steps: - -6.3.1. As a privileged database administrator, use a program like - SQL*Plus to enable the database service to post FAN events, for - example: - - SQL> execute dbms_service.modify_service( - SERVICE_NAME => 'sales', - AQ_HA_NOTIFICATIONS => TRUE); - -6.3.2. Edit php.ini and add - - oci8.events = On - -6.3.3. If your application does not already handle OCI8 error - conditions, modify it to detect failures and take appropriate - action. This may include re-connecting and re-executing - statements. - -6.3.4. Run your application, connecting to a 10gR2 or 11g database. - - -6.4. Recommendations and Known Limitations - -6.4.1 Changing Password for DRCP connections - -Changing a password over DRCP connections will fail with the error -"ORA-56609: Usage not supported with DRCP". This is an documented -restriction of Oracle Database 11g. - -6.4.2 Closing Connections - -With the PHP OCI8 extension, persistent connections can now be closed -by the user, allowing greater control over connection resource usage. -Persistent connections will now also be closed automatically when -there is no PHP variable referencing them, such as at the end of scope -of a PHP user function. This will rollback any uncommitted -transaction. These changes to persistent connections make them behave -similarly to non-persistent connections, simplifying the interface, -allowing for greater application consistency and predictability. Use -oci8.old_oci_close_semantics=1 to retain the historical behavior. - -6.4.3 LOGON Triggers can be used to set session properties - -The patch for Oracle Database 11.1.0.6 bug 6474441 (see section 6.5) -allows PHP applications with DRCP connection to use a database LOGON -trigger to set session properties at the time of session creation. -Examples of such settings are the NLS language and the date format. - -If the Oracle 11.1.0.6 database patch cannot be applied, one of the -following workarounds can be used: - -(i) After logon, explicitly set the session properties using PHP -application code. - -(ii) Connect using Oracle dedicated or shared servers instead of DRCP. - -With DRCP there is an connection management relationship between (i) -DRCP's automatic pool expansion and reduction, (ii) PHP's persistent -connection caching, (iii) with the way LOGON triggers fire with DRCP -authentication. Because of this interplay, LOGON triggers in PHP -(when DRCP is used) are only recommended for setting session -attributes and not for per-PHP connection events. - - -6.5. Patching Oracle Database 11g - -The patch for bug 6474441 is available from Oracle Support's Metalink -system. - -The bug is specific to Oracle 11.1.0.6 with DRCP connections. The -issues it fixes do not affect connections using Oracle's dedicated -(the default connection mode) or shared servers. They do not affect -earlier versions of Oracle. The bug is fixed in Oracle Database -11.1.0.7. +OCI8 installation instructions and documentation is available at +http://www.php.net/oci8 Modified: php/php-src/trunk/ext/oci8/README =================================================================== --- php/php-src/trunk/ext/oci8/README 2009-12-10 17:13:14 UTC (rev 291957) +++ php/php-src/trunk/ext/oci8/README 2009-12-10 17:28:19 UTC (rev 291958) @@ -1,454 +1,12 @@ -Installing OCI8 ---------------- +The OCI8 Extension +------------------ -0. Overview -1. Common requirements -2. Installing as a shared extension -3. Installing as a statically compiled extension -4. Installing from PECL to an existing PHP -5. Testing OCI8 -6. Oracle DRCP and FAN Support +The OCI8 extension allows PHP to access Oracle databases. It can be +built using Oracle 9.2, 10 or 11 client libraries. It allows Oracle's +standard cross-version connectivity, for example PHP using Oracle 10.2 +libraries can connect to Oracle Database 9.2 onwards. +This release of OCI8 can be used with PHP version 6. -0. Overview ------------ - -The OCI8 extension allows you to access Oracle databases. It can be -built using Oracle 9.2, 10.2, 11.1 or 11.2 client libraries, and allows -Oracle's standard cross-version connectivity. This release can be -used with PHP 6. - -The OCI8 extension is not related to, or used by, PDO_OCI, the PHP -Data Objects (PDO) extension for Oracle. - -1. Common requirements ----------------------- - -This version of PHP OCI8: - - - Will build with Oracle 9.2 (or more recent) client libraries. The - same (or more recent) version of Oracle libraries used when - building OCI8 must also be used at runtime. - - - Can be used with PHP versions 4.3.9 to 5.x. - -If you build PHP with the "ORACLE_HOME" Oracle database or full Oracle -client libraries: - - - you MUST set at least the ORACLE_HOME environment variable and - make it visible for your web server BEFORE it starts. - - - the Oracle software must be readable by the web server. With - Oracle 10.2, see the $ORACLE_HOME/install/changePerm.sh script - included in patch releases. - -If you build PHP with Oracle Instant Client libraries from -http://www.oracle.com/technology/tech/oci/instantclient/index.html - - - either the "basic" or "basic-lite" package is required. - - - the "devel" package is required. - - - you don't have to set ORACLE_HOME and many of the other - environment variables to build PHP with OCI8 support. - -For both ORACLE_HOME and Instant Client installs you may have to set: - - - LD_LIBRARY_PATH: it must include the $ORACLE_HOME/lib or Instant - Client library directory - - - NLS_LANG: if you want to change the default encoding used during - interaction with Oracle servers - -The most appropriate places to add the environment variables are: - - /etc/profile - /etc/profile.local - /etc/profile.d - - -2. Installing as a shared extension ------------------------------------ - -Configure OCI8 using one of the the following configure options: - - a) if you use an Oracle server or Oracle Client installation: - - ./configure --with-oci8=shared,$ORACLE_HOME - - b) with Oracle Instant Client: - - ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib - - If you use an RPM-based installation of Oracle Instant Client, - your configure line will look like this: - - ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<version>/client/lib - -Follow the usual building procedure, e.g. "make install". The OCI8 -shared extension oci8.so will be created. It may need to be manually -moved to the PHP extension directory, specified by the extension_dir -option in your php.ini file. - -Edit php.ini file and add the line: - - extension=oci8.so - - -3. Installing as a statically compiled extension ------------------------------------------------- - -Configure OCI8 using one of the the following configure options: - - a) with a common Oracle server or full Oracle client installation - - ./configure --with-oci8=$ORACLE_HOME - - b) with Oracle Instant Client - - ./configure --with-oci8=instantclient,/path/to/instant/client/lib - -Run "make install". - -After successful compile, you do not need to add oci8.so to php.ini. -The module will be usable without any additional actions. - - -4. Installing from PECL to an existing PHP ------------------------------------------- - -The OCI8 extension is also available as a PECL module on -http://pecl.php.net/package/oci8. - -Install using either (a) or (b) below. - - a) Do an automated download and install: - - Set PEARs proxy, if necessary: - - pear config-set http_proxy http://my-proxy.example.com:80/ - - Run - - pecl install oci8 - - When prompted, enter either the value of $ORACLE_HOME, or - "instantclient,/path/to/instant/client/lib" (without quotes). - - b) Alternatively, manually download the PECL package, e.g. oci8-1.3.5.tgz - - Extract the package: - - tar -zxf oci8-1.3.5.tgz - cd oci8-1.3.5 - - Prepare the package: - - phpize - - Configure the package, either using $ORACLE_HOME or Instant Client - - ./configure -with-oci8=shared,$ORACLE_HOME - - or - - ./configure -with-oci8=shared,instantclient,/path/to/instant/client/lib - - Install the package: - - make install - -After either install, edit your php.ini file, e.g. /etc/php.ini, and -add the line: - - extension=oci8.so - -Make sure php.ini's "extension_dir" includes the directory that -oci8.so was installed in. - - -5. Testing OCI8 ---------------- - -OCI8 tests are in ext/oci8/tests. When OCI8 tests are run this -directory will contain logs of any failures. - -5.1. Running OCI8 tests on Linux - -5.1.1. Edit ext/oci8/tests/details.inc - - Set the username, password and connection string for the database. - Most tests have been developed using the SYSTEM account: some tests - might fail unless the user has permissions to create necessary - tables, views, procedures etc. - - If the database is on the same machine as PHP, set - $oracle_on_localhost to TRUE. - - If Oracle 11g Database Resident Connection Pooling is being tested, - set $test_drcp to TRUE and ensure the connection string uses an - appropriate pooled server (see section 6.2.2). - - An alternative to editing details.inc is the set the environment - variables - - PHP_OCI8_TEST_USER - PHP_OCI8_TEST_PASS - PHP_OCI8_TEST_DB - PHP_OCI8_TEST_DB_ON_LOCALHOST - PHP_OCI8_TEST_DRCP - - for example: - - $ export PHP_OCI8_TEST_USER=system - $ export PHP_OCI8_TEST_PASS=oracle - $ export PHP_OCI8_TEST_DB=localhost/XE - $ export PHP_OCI8_TEST_DB_ON_LOCALHOST=TRUE - $ export PHP_OCI8_TEST_DRCP=FALSE - -5.1.2. Set any necessary environment variables for the Oracle - database. With Oracle 10g XE do: - - $ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh - - For other versions of the Oracle database do: - - $ . /usr/local/bin/oraenv - -5.1.3. Check your php.ini has E in the variables_order parameter, for - example: - - variables_order = "EGPCS" - -5.1.4. Run the tests: - - $ cd <your php src directory> - $ make test TESTS=ext/oci8 - -5.2. The tests execute rapidly. On fast machines with a local - database configured for light load (e.g. Oracle 10g XE) you might - see random tests fail with ORA-12516 or ORA-12520 errors. To - prevent this, increase the database PROCESSES parameter using the - following steps. - -5.2.1. Connect as the oracle software owner: - - $ su - oracle - -5.2.2. Set the necessary environment variables as in 5.1.2. - -5.2.3. Start the SQL*Plus command line tool and increase PROCESSES - - $ sqlplus / as sysdba - SQL> alter system set processes=100 scope=spfile - -5.2.4. Restart the database: - - SQL> startup force - - -6. Oracle DRCP and FAN Support ------------------------------- - -The PHP OCI8 extension has support for the Oracle Database Resident -Connection Pool (DRCP) and Fast Application Notification (FAN). - -Questions and issues can be raised on the Oracle OTN forum (free -registration required): -http://www.oracle.com/technology/forums/php.html - - -6.1. Oracle Version Compatibility - -The OCI8 extension will compile with Oracle libraries from version -9iR2 onwards. However, full functionality (e.g. DRCP support) is only -available when Oracle 11g is used. - -For general database functionality the version of the Oracle libraries -used by PHP does not necessarily have to match the version of the -database. - - -6.2. Database Resident Connection Pooling (DRCP) - -DRCP allows more efficient use of database machine memory and provides -high scalability. - -For DRCP to be available in OCI8, Oracle client libraries used by PHP -and the version of the Oracle Database must both be 11g. - -Documentation on DRCP is found in several Oracle manuals. For example, -see "Configuring Database Resident Connection Pooling" in the Oracle -Database Administrator's Guide 11g Release 1 (11.1) -http://download.oracle.com/docs/cd/B28359_01/server.111/b28310/manproc004.htm#CHDGIDBA -for usage information. A whitepaper -http://www.oracle.com/technology/tech/oci/pdf/oracledrcp11g.pdf -contains background information on DRCP. - -After building PHP with the OCI8 extension and 11g libraries, follow -these steps: - -6.2.0 Important: if Oracle Database 11.1.0.6 with DRCP connections is - used, then the Oracle database patch for bug 6474441 must be - applied (see section 6.5). Without this patch, "ORA-01000: - maximum open cursors exceeded", "ORA-01001 invalid cursor" or - "ORA-01002 fetch out of sequence" errors may occur. - - If the Oracle 11.1.0.6 database patch cannot be applied, one of - the following three workarounds can be used to disable statement - caching instead: - - (i) Connect using Oracle dedicated or shared servers instead of DRCP. - - (ii) Set PHP's oci8.statement_cache_size to 0. - - (iii) Set an event in the database initialization parameter file: - event="56699 trace name context forever, level 128". - - -6.2.1. As a privileged database administrator, use a program like - SQL*Plus to start the connection pool in the database: - - SQL> execute dbms_connection_pool.start_pool; - - Optional settings control the size and characteristics of the - pool. - -6.2.2. For PHP applications that currently connect using a Network Alias - like: - - $c = oci_pconnect("myuser", "mypassword", "MYDB"); - - Modify your tnsnames.ora file and add the "(SERVER=POOLED)" - clause, for example: - - MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com) - (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales) - (SERVER=POOLED))) - - Alternatively, modify the Easy Connect syntax in PHP and add - ":POOLED" after the service name: - - $c = oci_pconnect("myuser", "mypassword", - "myhost.dom.com:1521/sales:POOLED"); - -6.2.3. Edit php.ini and choose a connection class name. This name - indicates a logical division of the connection pool and can be - used to isolate pooling for separate applications. Any PHP - instance with the same connection class value will share - connections in the pool. - - oci8.connection_class = "MY_APPLICATION_NAME" - -6.2.4. Run your application, connecting to the 11g database. - - -6.3. Fast Application Notification (FAN) Support - -FAN support gives fast connection failover, a high availability -feature. This allows PHP OCI8 scripts to be notified when a database -machine or database instance becomes unavailable. Without FAN, OCI8 -can hang until a TCP timeout occurs and an error is returned, which -might be several minutes. Enabling FAN in OCI8 can allow your -applications to detect errors and re-connect to an available database -instance without the web user being aware of an outage. - -FAN support is available when the Oracle client libraries that PHP -links with and the Oracle Database are either version 10gR2 or 11g. - -FAN benefits users of Oracle's clustering technology (RAC) because -connections to surviving database instances can be immediately made. -Users of Oracle's Data Guard with a broker will see the FAN events -generated when the standby database goes online. Standalone databases -will send FAN events when the database restarts. - -For active connections, when a machine or database instance becomes -unavailable, a connection failure error will be returned by the OCI8 -extension function currently being called. On a subsequent PHP script -re-connect, a connection to a surviving database instance will be -established. The OCI8 extension also transparently cleans up any idle -connections affected by a database machine or instance failure so PHP -connect calls will establish a fresh connection without the script -being aware of any service disruption. - -When oci8.events is On, it is suggested to set oci8.ping_interval to --1 to disable pinging, since enabling FAN events provide pro-active -connection management of idle connections made invalid by a service -disruption. - -To enable FAN support in PHP, after building PHP with Oracle 10gR2 or -11g libraries follow these steps: - -6.3.1. As a privileged database administrator, use a program like - SQL*Plus to enable the database service to post FAN events, for - example: - - SQL> execute dbms_service.modify_service( - SERVICE_NAME => 'sales', - AQ_HA_NOTIFICATIONS => TRUE); - -6.3.2. Edit php.ini and add - - oci8.events = On - -6.3.3. If your application does not already handle OCI8 error - conditions, modify it to detect failures and take appropriate - action. This may include re-connecting and re-executing - statements. - -6.3.4. Run your application, connecting to a 10gR2 or 11g database. - - -6.4. Recommendations and Known Limitations - -6.4.1 Changing Password for DRCP connections - -Changing a password over DRCP connections will fail with the error -"ORA-56609: Usage not supported with DRCP". This is an documented -restriction of Oracle Database 11g. - -6.4.2 Closing Connections - -With the PHP OCI8 extension, persistent connections can now be closed -by the user, allowing greater control over connection resource usage. -Persistent connections will now also be closed automatically when -there is no PHP variable referencing them, such as at the end of scope -of a PHP user function. This will rollback any uncommitted -transaction. These changes to persistent connections make them behave -similarly to non-persistent connections, simplifying the interface, -allowing for greater application consistency and predictability. Use -oci8.old_oci_close_semantics=1 to retain the historical behavior. - -6.4.3 LOGON Triggers can be used to set session properties - -The patch for Oracle Database 11.1.0.6 bug 6474441 (see section 6.5) -allows PHP applications with DRCP connection to use a database LOGON -trigger to set session properties at the time of session creation. -Examples of such settings are the NLS language and the date format. - -If the Oracle 11.1.0.6 database patch cannot be applied, one of the -following workarounds can be used: - -(i) After logon, explicitly set the session properties using PHP -application code. - -(ii) Connect using Oracle dedicated or shared servers instead of DRCP. - -With DRCP there is an connection management relationship between (i) -DRCP's automatic pool expansion and reduction, (ii) PHP's persistent -connection caching, (iii) with the way LOGON triggers fire with DRCP -authentication. Because of this interplay, LOGON triggers in PHP -(when DRCP is used) are only recommended for setting session -attributes and not for per-PHP connection events. - - -6.5. Patching Oracle Database 11g - -The patch for bug 6474441 is available from Oracle Support's Metalink -system. - -The bug is specific to Oracle 11.1.0.6 with DRCP connections. The -issues it fixes do not affect connections using Oracle's dedicated -(the default connection mode) or shared servers. They do not affect -earlier versions of Oracle. The bug is fixed in Oracle Database -11.1.0.7. +OCI8 installation instructions and documentation is available at +http://www.php.net/oci8
-- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php