From 0912b4f4c5f9fb53eb1f24bc0ad41abc2cc61c78 Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Sun, 23 Dec 2007 21:31:43 +0000 Subject: [PATCH] MFB: Upgrade to the new-reference-structure - Split reference.xml into book.xml, setup.xml, connection.xml, datatypes.xml, examples.xml - Moved from reference.xml: - To book.xml: The intro text (partintro), and link to various pages - To setup.xml: requirements, configuration, and added installation and resources - To connection.xml: The connection handling section to a new chapter - To datatypes.xml: The data type section to a new chapter - To examples.xml: The examples section to a new chapter - Changed the constants section to be an - Changed the intro ID from .intro to intro. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248868 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/oci8/book.xml | 51 ++++ reference/oci8/connection.xml | 80 ++++++ reference/oci8/constants.xml | 6 +- reference/oci8/datatypes.xml | 133 ++++++++++ reference/oci8/examples.xml | 184 ++++++++++++++ reference/oci8/reference.xml | 465 +--------------------------------- reference/oci8/setup.xml | 151 +++++++++++ 7 files changed, 607 insertions(+), 463 deletions(-) create mode 100644 reference/oci8/book.xml create mode 100644 reference/oci8/connection.xml create mode 100644 reference/oci8/datatypes.xml create mode 100644 reference/oci8/examples.xml create mode 100644 reference/oci8/setup.xml diff --git a/reference/oci8/book.xml b/reference/oci8/book.xml new file mode 100644 index 0000000000..4647a34d9d --- /dev/null +++ b/reference/oci8/book.xml @@ -0,0 +1,51 @@ + + + + + + + Oracle/OCI8 + + + + &reftitle.intro; + + 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. + + + + + &reference.oci8.setup; + &reference.oci8.constants; + &reference.oci8.examples; + &reference.oci8.connection; + &reference.oci8.datatypes; + &reference.oci8.reference; + + + + + diff --git a/reference/oci8/connection.xml b/reference/oci8/connection.xml new file mode 100644 index 0000000000..63d25c6dd6 --- /dev/null +++ b/reference/oci8/connection.xml @@ -0,0 +1,80 @@ + + + + Connecting Handling + + 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. + + + Connecting to an Oracle server is a reasonably expensive operation, in + terms of the time that it takes to complete. The oci_pconnect + 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). + + + If your application connects to Oracle using a different set of + credentials for each web user, the persistent cache employed by + oci_pconnect 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 oci8.max_persistent and oci8.persistent_timeout + configuration settings (these will give you control over the + persistent connection cache size and lifetime) or use + oci_connect instead. + + + Both oci_connect and oci_pconnect + employ a connection cache; if you make multiple calls to + oci_connect, using the same parameters, in a + given script, the second and subsequent calls return the existing + connection handle. The cache used by oci_connect + is cleaned up at the end of the script run, or when you explicitly close + the connection handle. oci_pconnect has similar + behaviour, although its cache is maintained separately and survives + between requests. + + + 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 oci_new_connect. + + + oci_new_connect 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 + oci_new_connect, especially in the busiest sections of + the application. + + + + + diff --git a/reference/oci8/constants.xml b/reference/oci8/constants.xml index 6758a61920..f28adfb2e3 100644 --- a/reference/oci8/constants.xml +++ b/reference/oci8/constants.xml @@ -1,6 +1,6 @@ - -
+ + &reftitle.constants; &extension.constants; @@ -621,7 +621,7 @@ -
+ + + Supported Datatypes + + The driver supports the following types when binding parameters using + <function>oci_bind_by_name</function> function: + + + + Type + Mapping + + + + + SQLT_NTY + Maps a native collection type from a PHP collection object, + such as those created by oci_new_collection. + + + SQLT_BFILEE + Maps a native descriptor, such as those created by + oci_new_descriptor. + + + SQLT_CFILEE + Maps a native descriptor, such as those created by + oci_new_descriptor. + + + SQLT_CLOB + Maps a native descriptor, such as those created by + oci_new_descriptor. + + + SQLT_BLOB + Maps a native descriptor, such as those created by + oci_new_descriptor. + + + SQLT_RDD + Maps a native descriptor, such as those created by + oci_new_descriptor. + + + SQLT_NUM + Converts the PHP parameter to a 'C' long type, and binds to + that value. + + + SQLT_RSET + Maps a native statement handle, such as those created by + oci_parse or those retrieved from other OCI queries. + + + SQLT_CHR and any other type + Converts the PHP parameter to a string type and binds as a + string. + + + +
+ + + The following types are supported when retrieving columns from a result set: + + + + Type + Mapping + + + + + SQLT_RSET + Creates an oci statement resource to represent the the cursor. + + + SQLT_RDD + Creates a ROWID object. + + + SQLT_BLOB + Creates a LOB object. + + + SQLT_CLOB + Creates a LOB object. + + + SQLT_BFILE + Creates a LOB object. + + + SQLT_LNG + Bound as SQLT_CHR, returned as a string + + + SQLT_LBI + Bound as SQLT_BIN, returned as a string + + + Any other type + Bound as SQLT_CHR, returned as a string + + + +
+ + + + + diff --git a/reference/oci8/examples.xml b/reference/oci8/examples.xml new file mode 100644 index 0000000000..026b6a1bbf --- /dev/null +++ b/reference/oci8/examples.xml @@ -0,0 +1,184 @@ + + + + &reftitle.examples; +
+ + + Basic query + +'; + while ($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) { + print ''; + foreach ($row as $item) { + print ''.($item?htmlentities($item):' ').''; + } + print ''; + } + print ''; + + oci_close($conn); +?> +]]> + + + + + + Insert with bind variables + + +]]> + + + + + + + + Inserting data into a CLOB column + +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 ''; +while ($row = oci_fetch_array($stid, OCI_ASSOC)) { + $result = $row['MYCLOB']->load(); + print ''; +} +print '
'.$result.'
'; + +?> +]]> + + + + + You can easily access stored procedures in the same way as you + would from the command line. + + Using Stored Procedures + + +]]> + + + +
+ + + + diff --git a/reference/oci8/reference.xml b/reference/oci8/reference.xml index abe227a6a8..b99736659e 100644 --- a/reference/oci8/reference.xml +++ b/reference/oci8/reference.xml @@ -1,467 +1,12 @@ - - - - - - - Oracle Functions + + + + Oracle &Functions; OCI8 - -
- &reftitle.intro; - - 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. - -
- -
- &reftitle.required; - - You will need the Oracle client libraries to use this extension. - Windows users will need libraries with version at least 10 to use the - php_oci8.dll. - - - - This extension does not support Oracle 8 client libraries anymore. - Though you still can connect to Oracle 8 servers as long as - the client library (v.9+) supports this. - - - - The most convenient way to install all the required files - is to use Oracle Instant Client, which is available from here: - &url.oracle.instant.client;. - 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. - - - 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 - before you start your web-server. The - variables you might need to set are as follows: - - - - ORACLE_HOME - - - - - ORACLE_SID - - - - - LD_PRELOAD - - - - - LD_LIBRARY_PATH - - - - - NLS_LANG - - - - 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. - - - After setting up the environment variables for your web server user, - be sure to also add the web server user (nobody, www) to the oracle - group. - - - If your web server doesn't start or crashes at startup - - Check that Apache is linked with the pthread library: - - - - - /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) -]]> - - - - - If the libpthread is not listed you have to reinstall Apache: - - - - - - - - - - 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. - - -
- - &reference.oci8.ini; - - &reference.oci8.constants; - -
- &reftitle.examples; - - - Basic query - -'; - while ($row = oci_fetch_array($stid, OCI_RETURN_NULLS)) { - print ''; - foreach ($row as $item) { - print ''.($item?htmlentities($item):' ').''; - } - print ''; - } - print ''; - - oci_close($conn); -?> -]]> - - - - - - Insert with bind variables - - -]]> - - - - - - - - Inserting data into a CLOB column - -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 ''; -while ($row = oci_fetch_array($stid, OCI_ASSOC)) { - $result = $row['MYCLOB']->load(); - print ''; -} -print '
'.$result.'
'; - -?> -]]> - - - - - You can easily access stored procedures in the same way as you - would from the command line. - - Using Stored Procedures - - -]]> - - - -
- -
- Connecting Handling - - 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. - - - Connecting to an Oracle server is a reasonably expensive operation, in - terms of the time that it takes to complete. The oci_pconnect - 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). - - - If your application connects to Oracle using a different set of - credentials for each web user, the persistent cache employed by - oci_pconnect 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 oci8.max_persistent and oci8.persistent_timeout - configuration settings (these will give you control over the - persistent connection cache size and lifetime) or use - oci_connect instead. - - - Both oci_connect and oci_pconnect - employ a connection cache; if you make multiple calls to - oci_connect, using the same parameters, in a - given script, the second and subsequent calls return the existing - connection handle. The cache used by oci_connect - is cleaned up at the end of the script run, or when you explicitly close - the connection handle. oci_pconnect has similar - behaviour, although its cache is maintained separately and survives - between requests. - - - 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 oci_new_connect. - - - oci_new_connect 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 - oci_new_connect, especially in the busiest sections of - the application. - -
- -
- Datatypes supported by the driver - - The driver supports the following types when binding parameters using - <function>oci_bind_by_name</function> function: - - - - Type - Mapping - - - - - SQLT_NTY - Maps a native collection type from a PHP collection object, - such as those created by oci_new_collection. - - - SQLT_BFILEE - Maps a native descriptor, such as those created by - oci_new_descriptor. - - - SQLT_CFILEE - Maps a native descriptor, such as those created by - oci_new_descriptor. - - - SQLT_CLOB - Maps a native descriptor, such as those created by - oci_new_descriptor. - - - SQLT_BLOB - Maps a native descriptor, such as those created by - oci_new_descriptor. - - - SQLT_RDD - Maps a native descriptor, such as those created by - oci_new_descriptor. - - - SQLT_NUM - Converts the PHP parameter to a 'C' long type, and binds to - that value. - - - SQLT_RSET - Maps a native statement handle, such as those created by - oci_parse or those retrieved from other OCI queries. - - - SQLT_CHR and any other type - Converts the PHP parameter to a string type and binds as a - string. - - - -
- - - The following types are supported when retrieving columns from a result set: - - - - Type - Mapping - - - - - SQLT_RSET - Creates an oci statement resource to represent the the cursor. - - - SQLT_RDD - Creates a ROWID object. - - - SQLT_BLOB - Creates a LOB object. - - - SQLT_CLOB - Creates a LOB object. - - - SQLT_BFILE - Creates a LOB object. - - - SQLT_LNG - Bound as SQLT_CHR, returned as a string - - - SQLT_LBI - Bound as SQLT_BIN, returned as a string - - - Any other type - Bound as SQLT_CHR, returned as a string - - - -
-
- - - &reference.oci8.entities.functions; - + + + + &reftitle.setup; + + +
+ &reftitle.required; + + You will need the Oracle client libraries to use this extension. + Windows users will need libraries with version at least 10 to use the + php_oci8.dll. + + + The most convenient way to install all the required files + is to use Oracle Instant Client, which is available from here: + &url.oracle.instant.client;. + 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. + + + 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 + before you start your web-server. The + variables you might need to set are as follows: + + + + ORACLE_HOME + + + + + ORACLE_SID + + + + + LD_PRELOAD + + + + + LD_LIBRARY_PATH + + + + + NLS_LANG + + + + 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. + + + After setting up the environment variables for your web server user, + be sure to also add the web server user (nobody, www) to the oracle + group. + + + If your web server doesn't start or crashes at startup + + Check that Apache is linked with the pthread library: + + + + + /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) +]]> + + + + + If the libpthread is not listed you have to reinstall Apache: + + + + + + + + + + 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. + + +
+ + + +
+ &reftitle.install; + &no.install; +
+ + + + &reference.oci8.ini; + + + +
+ &reftitle.resources; + &no.resource; +
+ + + + + +