The Underground PHP and Oracle® Manual

Release 1.4

CHRISTOPHER JONES AND ALISON HOLLOWAY

The Underground PHP and Oracle® Manual, Release 1.4 Copyright © 2007, Oracle. All rights reserved. Authors: Christopher Jones and Alison Holloway Contributors and acknowledgements: Vladimir Barriere, Luxi Chidambaran, Robert Clevenger, Sue Harper, Ken Jacobs, Srinath Krishnaswamy, Shoaib Lari, Simon Law, Krishna Mohan, Kevin Neel, Charles Poulsen, Roy Rossebo, Sreekumar Seshadri, Makoto Tozawa, Todd Trichler, Simon Watt The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose. U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs. The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of thirdparty products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party. Oracle, JD Edwards, and PeopleSoft are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Contents
Chapter 1 ..................................................................................................................................9 Introduction..............................................................................................................................9 Who Should Read This Book? ........................................................................................ 9 Introduction to Oracle...................................................................................................... 9 Databases and Instances ............................................................................................. 10 Tablespaces ................................................................................................................ 10 Schemas and Users..................................................................................................... 10 Introduction to PHP ....................................................................................................... 11 Chapter 2 ................................................................................................................................13 PHP Oracle Extensions .........................................................................................................13 Choosing a PHP Oracle Extension ................................................................................ 13 PHP Oracle Extensions.................................................................................................. 13 Oracle Extension ........................................................................................................ 13 OCI8 Extension .......................................................................................................... 13 PDO Extension........................................................................................................... 15 PHP Database Abstraction Libraries ............................................................................. 15 ADOdb ....................................................................................................................... 15 PEAR DB ................................................................................................................... 16 PEAR MDB2 ............................................................................................................. 16 Getting the OCI8 and PDO_OCI Extensions ................................................................ 16 OCI8 and PDO_OCI Installation Options ..................................................................... 17 Zend Core for Oracle ..................................................................................................... 19 OCI8 and PDO_OCI Development Cycle..................................................................... 19 Chapter 3 ................................................................................................................................21 Installing Oracle Database 10g Express Edition.................................................................21 Oracle Database Editions............................................................................................... 21 Oracle Database XE....................................................................................................... 21 Installing Oracle Database XE on Linux ....................................................................... 22 Installing Oracle Database XE on Debian, Ubuntu, and Kubuntu ................................ 23 Installing Oracle Database XE on Windows ................................................................. 24 Testing the Oracle Database XE Installation................................................................. 26 Configuring Oracle Database XE .................................................................................. 28 Setting the Oracle Database XE Environment Variables on Linux ........................... 28 Enabling Database Startup and Shutdown from Menus on Linux ............................. 28 Starting and Stopping the Listener and Database....................................................... 28 Enabling Remote Client Connection.......................................................................... 32 Chapter 4 ................................................................................................................................33

....................................................................... 33 Logging In To Oracle Application Express ................................................79 Installing OCI8 with PHP 5.........89 Zend Core for Oracle 2..................................................................................................................................... 85 Installing PDO .............................................. 52 Oracle SQL Developer ...................... 56 Editing Data....................................... 81 Installing PHP 4 on Linux........................................................................................................................................................................ 76 Starting and Stopping Apache HTTP Server .................................................................................................................................................................................................................................................................. 86 Installing PDO on Windows ............................................................................................... 65 Running Reports..............................................................................................................................................75 Installing Apache HTTP Server on Linux .... Compiling and Running PL/SQL .............................................................................................................................................................................................................................................................................................................................................................................................. 76 Chapter 6 ...........79 Installing PHP ......................................................................89 Installing Zend Core for Oracle .......................................................................................................................... 75 Installing Apache HTTP Server on Windows ........................................................................................................................................................... 82 Installing OCI8 With Oracle Instant Client .................................................. 68 Creating Reports............. 89 ..........................33 Oracle Application Express .................................................................................. 70 Chapter 5 ............................................................... 36 Working with SQL Scripts.............................................................................................. 47 Monitoring Database Sessions ............................................................ 79 Installing OCI8 on Linux ..............................75 Installing Apache HTTP Server ................................................................. 59 Executing a SQL Query ...................................................................................................................................................................................................................................................................... 45 Creating a Database User ........ 61 Editing............................. 35 Creating Database Objects ................................................................................................. 83 Installing OCI8 with Instant Client on Linux .............................................................................Using Oracle Database 10g ........................................................................... 83 Installing OCI8 with Instant Client on Windows.................................................. 50 Database Backup and Recovery......... 79 Installing OCI8 on Windows..................................................................................................................... 87 Chapter 7 .............................................................................................. 56 Creating a Database Connection .................................................................................................................................. 75 Starting and Stopping Apache HTTP Server ...................................... 42 Creating a PL/SQL Procedure............................. 81 Installing PHP 4 on Windows ................................................................ 58 Creating a Table ...................................................................................................................... 80 Installing OCI8 with PHP 4............. 33 Unlocking the HR User ......................................... 85 Installing PDO on Linux ................................0 ................................................................................................................................

.................. 102 Optional Connection Parameters .................................................... 119 The Transactional Behavior of Connections......................................................................................................................................................................................................................................................... 103 Tuning Oracle Connections in PHP.......................... 97 Persistent Connections ........................................................................... 97 Oracle Database Name Connection Strings.................. 92 Testing the Zend Core for Oracle Installation on Windows ....................................................................................................................................................................................................................................................................................... 106 Tuning Persistent Connections......... 117 Autonomous Transactions.................................................................................................................................... 115 Insert..................................... 122 ............................................................. 103 Connection Privilege Level.................... 99 Oracle Environment Variables for Connections......................................................................... 97 Standard Connections................ Create and Drop.................................................................... 111 Chapter 9 ....................................................................................................................................................................................................................................... 89 Installing Zend Core for Oracle on Linux......................................................................................................................................................................................................................................................................................................... 90 Testing the Zend Core for Oracle Installation on Linux ...................................................................................................................................................................................................................................... 97 Multiple Unique Connections ...................................................97 Connecting to Oracle Using OCI8....... 93 Chapter 8 ............................ 120 Tuning SQL Statements in PHP Applications............................................................................................................................................. 119 Handling OCI8 Errors ....................................................................................................................................................................................................... 100 Closing Oracle Connections ............113 SQL Statement Execution Steps.............................. 117 Transactions............................. 98 Easy Connect String .... 93 Configuring Zend Core for Oracle .............................. 91 Installing Zend Core for Oracle on Windows .113 Executing SQL Statements With OCI8 ................................................................................. Update.... 103 Connection Character Set............... Delete............................................................................................. 110 Connection Management in Scalable Systems................................................................................................ 98 Full Database Connection String.................................................................................................................................... 109 Other Oracle Net Optimizations.................................... 101 Connection Cleanliness with Persistent Connections......................................................... 113 Oracle Datatypes ...Installing Zend Core for Oracle..................................................................................... 105 Connection Decisions..... 113 Query Example.............................................................................................................................................. 110 Tracing Oracle Net ......................... 99 Database Alias........................... 107 Tuning Oracle Net................................ 114 Fetch Functions...............................................................................97 Oracle Connection Types ...............................................................................................................

..............................153 Fetching Relational Rows as XML ...................................................159 Globalization .................................................................................................. 144 Chapter 11 ...............................................................................................................................147 Working with LOBs ........................ 125 Auto-Increment Columns ................................................................... 134 PL/SQL Errors in PHP ............................. 155 XQuery XML Query Language................................................ 135 End of Line Terminators in PL/SQL with Windows PHP ........................................................ 125 Limiting Rows and Creating Paged Datasets ........................................................................................................................................................................................................................................................................................ 129 Regular Expressions in SQL .................................................131 Using PL/SQL with OCI8 ................................................................................................................................. 149 Chapter 12 ........................................................................................................ 132 Packages ..................................................................................................................................................................................................................................................................................................... 133 Calling PL/SQL Procedures and Functions......................................159 Establishing the Environment Between Oracle and PHP .............................................................................147 Using Large Objects in OCI8 ............................................................................................................................................... 129 Chapter 10 ...................................................................................................................... Procedures........................ 148 Working with BFILEs ....................................................... 153 Fetching Rows as Fully Formed XML .... 128 Exploring SQL............................... 132 Stored or Standalone Procedures and Functions ................................................................................................ 147 Other LOB Methods.................................................................................................................................................. 157 Chapter 13 .................................................................. 159 ....... 129 Analytic Functions in SQL........................................................................ 124 Default Statement Cache Size ................................................................................................. 139 Using PL/SQL Types in PHP.............................................Using Bind Variables .......................... 135 PL/SQL Success With Information Warnings .............................................................................................................................................................................................................................. 141 Using REF CURSORS for Result Sets....................................................................131 PL/SQL Overview ..................................................................................................................................... 133 Creating PL/SQL Procedures in PHP ........................................... 156 Accessing Data from Oracle over HTTP ............ 136 Oracle Collections in PHP ....................... 154 Using the SimpleXML Extension in PHP.......... 133 Triggers ................ Packages and Triggers ............................................................................................................................................................................. 132 Anonymous Blocks ................................................................... 131 Blocks............................................................................................................................... 122 Default Prefetch Size.....................................................................................................................................................153 Using XML with Oracle and PHP........ 137 Array Binding and PL/SQL Bulk Processing ...... 143 Getting Output with DBMS_OUTPUT ........................................................................

............... 164 Strings in PHP .171 Testing PHP and the OCI8 Extension................................................................................................ 174 Configuring the Database For Testing...................................................................................................................................................................... 186 PHP and Oracle Books .................................................................................................................. 163 Specifying the Page Encoding in PHP ................................................ 161 Developing Locale Awareness .............................................................................................................. 186 Articles and Other References ............ 165 Oracle Number Formats .................................................................................169 Enabling OCI8 Debugging output ............................ 164 Static Files ..................................................Manipulating Strings ........................................................................................................................ 186 Documentation................................................................................. 166 Oracle Linguistic Sorts.......................................................................................................... 162 Specifying the Encoding in the HTTP Header.......................181 Oracle and OCI8 Comparison ....................................................177 Chapter 17 .................................................................................................................................................................................................................................................................. 186 PHP ............... 168 Chapter 14 .................................................................................................................................................................................................................................................................................. 174 Running a Single Test....................................................................................................................................................................................................................................... 181 Glossary ........................................................................................................................................171 Running OCI8 Tests ............................................................................................................................................................................................................... 160 Determining the Locale of the User ........... 163 Specifying the Encoding in the HTML Page Header...................................................................... 169 Chapter 15 .. 167 Oracle Error Messages ................... 186 Source and Binaries ................................. 186 ................................................................................................... 173 OCI8 Test Helper Scripts ...................................177 OCI8 Function Names in PHP 4 and PHP 5 ..................................................... 163 Organizing the Content of HTML Pages for Translation............................. 171 Tests that Fail...............................................................................169 Tracing OCI8 Internals...................................185 Resources ............................................................................................................................................................................................................................................................. 162 Specifying the Page Encoding for HTML Pages ................................................................................................................. 164 Presenting Data Using Conventions Expected by the User.........................................................................186 General Information and Forums ..................................181 The Obsolete Oracle Extension ... 164 Oracle Date Formats.................................................................................................................... 175 Chapter 16 ......................................... 161 Encoding HTML Pages .......................................................................................... 164 Data from the Database .................................................................................................................. 172 Creating a Test....................................................................................................................................................................................................................................................................

...................................................................................Utilities ................................ 186 ......

They are worthwhile additions to your library. Since the first release of the Underground PHP and Oracle Manual there have been several commercially available books on PHP and Oracle published. This book aims to remove any confusion. It is assumed that you already have basic PHP and SQL knowledge and want best practices in using PHP against an Oracle database. You may be starting out with PHP database development. against all editions of the Oracle database as well. this book covers PHP and Oracle together in detail and shows how to make them work well. This book is not a complete PHP or Oracle guide. and shows how to use them together efficiently. However. 9 . Introduction to Oracle The Oracle Database is well known for its scalability. but everything covered in this book also applies to the other editions of the Oracle database. It is the leading database and is available on many platforms. It covers installation of both Oracle and PHP. The book contains much new material on PHP’s Oracle OCI8 and PDO_OCI extensions. The installation and database discussion in this book highlights the Oracle Database 10g Express Edition. You may be unsure how to install PHP and Oracle. which walks through building a PHP application against an Oracle database. The PHP you write against Oracle Database 10g Express Edition can be run. Oracle’s documentation is freely available online. reliability and features. including Oracle’s own extensive set of documentation you can read for more in-depth information on the architecture and commands to use with Oracle.CHAPTER 1 Introduction This book shows how to use the PHP scripting language with the Oracle database. For newcomers we suggest reading the Oracle Database Express Edition 2 Day Plus PHP Developer Guide. Who Should Read This Book? This book is aimed at PHP developers who are developing applications against an Oracle database. It also incorporates several updated installation guides previously published on the Oracle Technology Network web site. Extensive PHP documentation and resources are also online and in books. The chapter on globalization is derived from the Oracle Database Express Edition 2 Day Plus PHP Developer Guide. URLs to the online resources and most useful books are listed in the Resources chapter. There are many great books on Oracle. without change. for the first time. We gratefully acknowledge all the Oracle staff that contributed to this book. You may already be using another database and have a requirement or a preference to move to Oracle. Sue Harper contributed the chapter on SQL Developer.

Some of the most common schema objects are: * * * Tables Indexes Views Although you may have more than one database per machine. Every time a server is started. Check the Glossary for more descriptions. Instead threads run within the Oracle image. Each database consists of one or more data files. Multiple applications can use the same database without any conflict by using different schemas. On some operating systems. An Oracle database server consists of an Oracle database and an Oracle instance. Instead of using a CREATE DATABASE command for new applications. The combination of the background processes and SGA is called an Oracle instance.Introduction There are some subtle differences between the terminology used when describing an Oracle database and a database from other software vendors. The following overview of the main Oracle terms might help you to understand the Oracle terminology. to connect to the HR schema. typically a single Oracle database contains multiple schemas. Databases and Instances An Oracle database stores and retrieves data. Users are assigned a default tablespace that holds all the data the users creates. you would use the username hr in PHP’s connection string. Schemas and Users A schema is a collection of database objects such as tables and indexes. there are no separate background processes. Many people use the words schema and user interchangeably. Tablespaces Tablespaces are the logical units of data storage made up of one or more datafiles. A database is made up of default and DBA-created tablespaces. For example. a shared memory region called the system global area (SGA) is allocated and the Oracle background processes are started. In Oracle Database Express Edition (known as “Oracle XE”) there is a wizard to create new users in the Application Express management console. you need to connect as the owner of the schema that contains the objects you want to interact with. use the CREATE USER command to create a new schema in the database. A schema is owned by a database user and has the same name as that user. like Windows. 10 . Tablespaces are often created for individual applications because tablespaces can be conveniently managed. Once you have installed PHP and want to write scripts that interact with Oracle.

making it corporation-friendly. it executes the PHP code and outputs any results. PHP code is commonly embedded in HTML: <?php echo "<p>Hello</p>". When the PHP parser processes a file. and is great for creating Web 2. PHP is perfect for rapidly developing applications both big and small. The HTML output from the above script would therefore be: <p>Hello</p><p>World</p> The PHP command line interface (CLI) can also be used to run PHP scripts from an operating system shell window. PHP 5 introduced strong object orientated capabilities. 11 . The HTML sections are echoed to the web browser verbatim. It powers over twenty million web sites on the Internet and has a huge user community behind it. or run by the web server using FastCGI. PHP is open source and free. It runs on many platforms.0 applications. ?> <p>World</p> PHP is typically installed as an Apache module. interpreted scripting language commonly used for web applications. PHP comes with many extensions offering all kinds of functionality such as database access.Introduction to PHP Introduction to PHP PHP is a hugely popular. The language is dynamically typed and easy to use. and has a BSD-style license.

.

You can also use the ODBC extension. This extension accessed the database using Oracle’s obsolete C code OCI7 API. 4. 13 . the OCI8 extension. Oracle Extension The extension called “Oracle” was included in PHP 3. The extensions are: * * * Oracle OCI8 PDO They are all included in the PHP source code with PHP’s open source license. For basic database operations your PHP application will work with different database vendors simply by changing the extension driver. It is also in PHP 6. If you want to make full use of Oracle features and want high performance use PHP’s main Oracle extension. and 5. Basic database access in each extension and abstraction library is very similar. OCI8 Extension The OCI8 extension is included in PHP 3. which is in the early stage of development. The differences are in their support for advanced features and the programming methodology promoted.CHAPTER 2 PHP Oracle Extensions There are various ways PHP can connect to Oracle. is no longer in PHP and is not maintained. It had limited functionality. New development using this extension is not recommended. Although this book concentrates on the OCI8 extension for PHP. If you want database independence. consider using the PHP Data Object (PDO) extension or ADOdb. Choosing a PHP Oracle Extension Several PHP extensions provide PHP functions for accessing Oracle databases and there are also database abstraction layers written in PHP which are popular. PHP Oracle Extensions The PHP Oracle extensions can be compiled into the PHP binary. it is worth knowing the alternative libraries and extensions you can use. 4 and 5.0.

If you are using PHP 4 and cannot upgrade to PHP 5.php <?php $c = oci_connect('hr'. it connects to Oracle as the demonstration user hr of the Oracle XE database running on the local machine. 'hrpwd'. you should replace the OCI8 code with the new version to get improved stability and performance optimizations.1. and released as open source.2. } oci_close($c). oci_execute($s). The PHP interfaces are the same as the original OCI8 extension but there are new connection management and performance settings. ?> When invoked in a web browser. 'select city from locations'). OCI8 was refactored by Zend and Oracle to increase stability and performance. while ($res = oci_fetch_array($s)) { echo $res['CITY'] .PHP Oracle Extensions For PHP 5. The 14 . PHP 4 functions like OCILogin() became oci_connect(). An example script that finds city names from the locations table using OCI8: connectoci8. "<br>". The query is executed and a web page of results is displayed in the browser: Figure 2. '//localhost/XE').1 PHP output in a web browser In PHP 5. Steps for this are shown later in this book. The refactored extension builds and runs with PHP 4 too. OCIParse() became oci_parse() and so on. the OCI8 extension function names were standardized. $s = oci_parse($c.

A table showing old and new names appears later in this book. $s = $dbh->prepare("select city from locations").php <?php $dbh = new PDO('oci:dbname=//localhost/XE'. they use functionality provided by the OCI8 extension. so PHP 4 scripts do not need to be changed. PDO Extension PHP Data Objects (PDO) is a data abstraction layer that provides PHP functions for accessing databases using a common core of database independent methods.1 onwards. There is an optional C extension plug-in if you need extra performance. 'hr'.PHP Database Abstraction Libraries old names still exist as aliases. All unqualified references to OCI8 in this book refer to the PHP extension. An example script that finds city names from the locations table using ADOdb: 15 . The abstraction libraries are: * * * ADOdb PEAR DB PEAR MDB2 You can freely download and use the PHP code for these libraries.sourceforge. 'hrpwd'). } $dbh = null. The PDO extension is included in PHP 5. An example script that finds city names from the locations table using PDO_OCI: connectpdo. // release the connection ?> The output is the same as the previous OCI8 example. "<br>". They are written in PHP and when configured for Oracle. PDO_OCI provides the Oracle functionality for PDO. which may also support vendor specific functionality. ADOdb The popular ADOdb library is available from http://adodb. The name “OCI8” is also the name for Oracle’s Call Interface API used by C programs including the PHP OCI8 extension. PDO_OCI has no code in common with OCI8. Each database has its own driver.net. $s->execute(). PHP Database Abstraction Libraries There are three main database abstraction libraries for PHP. while ($r = $s->fetch(PDO::FETCH_ASSOC)) { echo $r['CITY'] .

"hrpwd").php. "hr". It is available from http://pear. OCI8 was available in PHP releases prior to PHP 5.1.php"). } $mdb2->disconnect(). ?> Getting the OCI8 and PDO_OCI Extensions The OCI8 and PDO_OCI extensions are included in various PHP bundles. Zend Core for Oracle.inc. while ($r = $s->FetchRow()) { echo $r['CITY'] . It is a library aiming to combine the best of PEAR DB and the PHP Metabase abstraction packages.php <?php require("MDB2.1 shows the locations and files to download for Linux and Windows. "</br>". $res = $mdb2->query("select city from locations"). "<br>".php"). which contains PHP extensions as individual downloads.PHP Oracle Extensions connectadodb. while ($row = $res->fetchRow(MDB2_FETCHMODE_ASSOC)) { echo $row['city'] . 16 . $s = $db->Execute("select city from locations"). $db = ADONewConnection("oci8"). $mdb2 = MDB2::connect('oci8://hr:hrpwd@//localhost/XE'). and the PHP Extension Community Library (PECL) site. There are three main distribution channels for PHP: the PHP releases.net/package/DB. but it is strongly recommended to upgrade the old OCI8 extension to the refactored version in PECL. Table 2. } $conn->Close().php.net/package/MDB2. PEAR MDB2 The PEAR MDB2 package is available from http://pear. PEAR DB is a package for database abstraction. PEAR DB has been superceded by PEAR MDB2.php <?php require_once("adodb. $db->Connect("//localhost/XE". ?> PEAR DB The PHP Extension and Application Repository (PEAR) contains many useful packages that extend PHP’s functionality. An example script that finds city names from the locations table using MDB2: connectpear.2.

com/technology/t ech/php/zendcore/ No ZendCoreForOracle-v2.php/php _pdo_oci.php. which may be local or remote on your network.OCI8 and PDO_OCI Installation Options Table 2. there are several configuration options you could use when installing PHP.10 Yes onwards - http://pecl4win.2.net/package/oci8 oci8-1.1.tgz - Yes http://pecl.net/ext.1 or 5.3.1 OCI8 andPDO_OCI Availability Matrix Bundle PHP Release Source Code PHP Release Windows Binaries PHP Version Contains OCI8 Contains PDO_OCI Location and Current Release PHP 5.dll php_pdo_oci.0 for Oracle used PHP 5.0 PECL Source PHP 4.zip Earlier Zend Core for versions of Zend Core Yes Oracle 2.tar.2.php.0.3 Code onwards PECL Windows Binaries PECL Windows Binaries http://www. If they need a specific bug fix they use PECL or PHP’s latest development source code to get it.tar.3 onwards - Yes http://pecl4win. Many PHP users install the full PHP source or binaries and do their own custom configuration.10 Yes Code onwards PECL Source PHP 5.net/downloads php-5.net/package/PDO_O CI PDO_OCI-1.0.net/downloads Yes Yes php-5.0.gz ZendCoreforOracle-v.3.2.php.2 onwards http://www.php. 17 .zip Other platforms are also available - http://pecl.2 onwards PHP 5.2-Win32. For Oracle database access the PHP binary is linked with Oracle client libraries.php. and what you want to achieve.0.net/ext.3.gz Compiles and runs on many platforms PHP 5.tgz PHP 4.dll OCI8 and PDO_OCI Installation Options Depending what software you have already installed.2 Yes Yes http://www.0.dll php_oci8.1-Windowsx86.php.1-Linuxx86. The extensions are available in several forms because of the differing needs of the community. These provide underlying connectivity to the database.dll PHP 5.2.php/php _oci8.2.oracle.2.1.

9i. 9i. 10g Oracle Database Version 8i.1. 9i.3.10 onwards. On Windows you can use the Windows PHP binaries with Oracle Instant Client. 9i. 9i. Table 2. 9i.2 Refactored OCI8 and Oracle Compatibility Matrix Bundle containing OCI8 PHP Release Source Code PHP Release Windows Binaries Zend Core for Oracle 2.3 PDO_OCI and Oracle Compatibility Matrix Bundle containing PDO_OCI PHP Version PHP Release Source Code PHP 5. you can compile your own PHP and link with Oracle’s libraries used by the database.2 onwards PHP 5.1 onwards Oracle Client Version 8i. 10g 10g Inbuilt Oracle 10g client 8i. If you do not want to compile PHP. 10g 8i.1.2 shows the compatibility of the refactored OCI8 extension with PHP and Oracle. 10g 8i. 10g Table 2. If your database is installed on another machine on your network. or this is your first time with PHP and Oracle. Table 2. 10g 10g Oracle Database Version 8i. 9i.dll PHP Version PHP 5. 9i.0 PECL OCI8 Source Code PECL Windows php_oci8. 10g 8i.2 onwards PHP 5. On Windows you can use PHP’s pre-supplied binaries.3 shows the compatibility of the PDO_OCI extension with PHP and Oracle.3.2 PHP links with Oracle client libraries If your database is installed on the same machine as the web server and PHP.PHP Oracle Extensions Figure 2. 10g 18 . 10g 8i. PHP 4. Table 2.2 PHP 4.10 onwards Oracle Client Version 8i. 9i. install Zend Core for Oracle. you can install the small Oracle Instant Client and compile PHP with that.

dll library may be used with Oracle 8i or 9i clients. 9i. Zend Core for Oracle Zend Core for Oracle is the result of a joint project between Oracle and Zend. Zend Core for Oracle is free to download and use. It has a simple installer. After several months of development the PHP release manager will release a new stable version of PHP.net/. OCI8 and PDO_OCI Development Cycle PHP’s source code is under continual development in a CVS source code control system viewable at http://cvs. It supports Oracle 8i and 9i clients 8i. The code is open source and anyone can access the code in CVS or seek approval to contribute too. 9i. 10g If OCI8 or PDO_OCI are linked with Oracle 8i or 9i client libraries.dll library is 8i. It is a pre-built release of PHP that comes enabled with the OCI8 extension.php. PECL source code snapshots are taken from CVS at infrequent intervals.3 onwards PHP 5. Zend Core for Oracle is available for many platforms and has a convenient browser-based management console for configuration and getting updates. The snapshots may be relatively unstable because the code is in flux.0. A support package that includes support for the PHP language is available from Zend.net/.dll library is 8i.Zend Core for Oracle 10g PHP Release Windows Binaries PECL PDO_OCI Source Code PECL Windows php_pdo_oci.php. Not all functionality may be available unless the Oracle client and server are both Oracle 10g. comes with Oracle Instant Client 10g and includes an optional Apache web server. It supports Oracle 8i and 9i clients 8i. It uses the most current CVS code at the time of release. 9i. On Windows the php_pdo_oci8. You can update your PHP environment by getting this source code and recompiling. or by downloading the Windows binaries. Bugs are rapidly fixed and the code changes made available via CVS.dll PHP 5. 10g also available. 10g also included. 10g 10g A php_pdo_oci8. Zend Core for Oracle can connect to local and remote Oracle databases. The code in CVS is used to create the various PHP distributions: * Two-hourly snap-shots are created containing a complete set of all PHP’s source in CVS at the time the snapshot was created.0.3 onwards A php_pdo_oci8. connecting to Oracle 7 databases is possible.1 onwards PHP 5. PECL Windows binaries of the OCI8 and PDO_OCI DLLs for various versions of PHP are built from the latest CVS source at frequent intervals 19 * * * . The snapshots are located at http://snaps. 9i.

PHP Oracle Extensions * * Zend Core for Oracle also takes snapshots of PHP from CVS. the PECL source snapshots. often with various critical patches applied. Various operating systems bundle the version of PHP current at the time the OS is released. and Zend Core for Oracle are not synchronized. The schedules of PHP releases. the PECL Windows binary builds. 20 .

com/database/product_editions. Debian. whereas the Express Edition has a limited feature set. that is free.html. There’s a comprehensive list of the features for each Oracle edition at http://www. The installation instructions are given for Linux. You could do this without changing any of your underlying table structure or code. licensing options and costs. This is the free edition. You could start off with the Express Edition. Free to distribute with your applications. Oracle Database XE is a good choice for development of PHP applications that require a free. Free to download. Enterprise Edition has all the bells and whistles. as needed.oracle. The Oracle database edition names are: * * * * Express Edition Standard Edition One Standard Edition Enterprise Edition All the editions are built using the same code base. small footprint database. Just change the Oracle software and you’re away.oracle. Windows. Oracle Database 10g Express Edition (Oracle Database XE). Free to develop against. Oracle Database XE is available on the Oracle Technology Network (http://otn. and installation instructions for. free! Oracle Database XE Oracle Database XE is available on 32-bit Windows and Linux platforms. That is. move up to another edition as your scalability and support requirements change. free. Oracle Database Editions There are a number of editions of the Oracle database. they all have the same source code. each with different features. Ubuntu and Kubuntu. and. This book discusses working with Oracle Database XE.CHAPTER 3 Installing Oracle Database 10g Express Edition This chapter contains an overview of. but still has all the reliability and performance of the Enterprise Edition. but different features are implemented in each edition.com/xe) for the following operating systems: * * * Windows 2000 Service Pack 4 or later Windows Server 2003 Windows XP Professional Service Pack 1 or later 21 . Yes.

Configure the database 22 . you’ll need to pay Oracle for the license costs. Oracle Application Express.0.2. You cannot buy support from Oracle for Oracle Database XE. you should consider Oracle Standard Edition or Enterprise Edition.Installing Oracle Database 10g Express Edition * * * * * Red Hat Enterprise Linux RHEL3 and RHEL4 Suse SLES-9 Fedora Core 4 Red Flag DC Server 5.3. and use these for application development and testing.1 The following libraries are required for the Linux-based operating systems: * * glibc release 2.oracle. Download the Oracle Database XE from http://otn.i386. 4. Support for Oracle Database XE is through an Oracle Technology Network (http://otn. but when you go production.1-1.3. you need to install this library before you can install Oracle Database XE.com/) discussion forum.3.96 There are some limitations with Oracle Database XE: * * * * 4GB of data Single database instance Single CPU used.0.96. Log in or su as root su Password: 3. To install Oracle Database XE: 1.oracle.rpm Oracle Database XE installs. If you need a fully supported version for the Oracle database. even if multiple CPUs exist 1GB RAM used.2 libaio release 0. Installing Oracle Database XE on Linux If you do not have a version of libaio over release 0. which is populated by peers and product experts. even if more RAM is installed Oracle Database XE has a browser-based management interface. You can download all the editions of the Oracle Database from the Oracle Technology Network. 2.0/MIRACLE LINUX V4. Install the RPM rpm -ivh oracle-xe-univ-10.0/Haansoft Linux 2006 Server (Asianux 2.com/xe.0 Inside) Debian 3.

7. If you use the Oracle Unbreakable Linux Network and have the Oracle Software channel enabled. 3. follow these steps: 1. and will be installed from the repository if you do not already have them installed. the bc package is installed by default on the desktop version. you can install Oracle XE with: up2date oracle-xe After this download completes. To install Oracle Database XE on Debian.1-1. you need to make sure that you have already installed the libaio and bc packages. If you are using Ubuntu or Kubuntu. Ubuntu and Kubuntu.deb Oracle Database XE installs.oracle. Enter and confirm the password for the default users. If you download Oracle Database XE from the Oracle Technology Network (http://otn. Configure the database /etc/init.oracle.list: deb http://oss.2.Kubuntu /etc/init. but not on the server version. Enter Y or N for whether you want the database to start automatically on reboot. and 5. and run the following command to begin the install: dpkg -i downloads/oracle-xe-universal_10. Installing Oracle Database XE on Debian. Ubuntu.com/xe).d/oracle-xe configure 23 . and 1521 for the Database Listener. Ubuntu. add the following to the file /etc/apt/sources.0.d/oracle-xe configure Installing Oracle Database XE on Debian. To include this repository.com/debian unstable main non-free libaio and bc are included in the repository. Log in or su as root su Password: 2. The database and database listener are configured and started. follow the configuration step 4 onwards. Install Oracle Database XE apt-get update apt-get install oracle-xe If you have not added the apt-get repository.oracle. 6. Accept the default ports of 8080 for Application Express.0_i386.com/xe. and Kubuntu There is an Advanced Package Tool (apt-get) repository available on the Oracle Open Source web site for Oracle Database XE. you can download Oracle Database XE from http://otn.

click Next. 6.Installing Oracle Database 10g Express Edition 4. 5. Installing Oracle Database XE on Windows To install Oracle Database XE on Windows.com/xe. In the Oracle Database XE . In the License Agreement window. 24 . In the Choose Destination Location window. Log on to Windows as a user with Administrative privileges. 6. 5. The database and database listener are configured and started. 3. Double click on the OracleXEUniv. Download the Oracle Database XE from http://otn. either accept the default or click Browse to select a different installation directory. and 1521 for the Database Listener. delete it using the Control Panel > System dialog. follow these steps: 1. 2. 4. Click Next. If the ORACLE_HOME environment variable has been set. Accept the default ports of 8080 for Application Express. Figure 3-1 Oracle Database XE install welcome dialog.oracle.Install Wizard welcome window. Enter and confirm the password for the default users.exe file. select I accept and click Next. 2. Enter Y or N for whether you want the database to start automatically on reboot.

If these ports are already being used. Oracle Database XE requires a number of ports and selects a number of default ports. Click Next. Figure 3-3 Oracle Database XE database password dialog 25 . 8.Installing Oracle Database XE on Windows Figure 3-2 Oracle Database XE install location dialog. In the Specify Database Passwords window. 7. you are prompted to enter another port number. enter and confirm the password to use for the sys and system database accounts.

In the InstallShield Wizard Complete window. Figure 3-4 Oracle Database 10g install summary dialog. Click Install. If you do not already have the Database homepage displayed in your web browser. click Launch the Database homepage to display the Database Home Page. 26 . review the installation settings. Click Finish. 10. Testing the Oracle Database XE Installation To test the installation of Oracle Database XE: 1.Installing Oracle Database 10g Express Edition 9. In the Summary window.0.0.1:8080/apex The Database homepage is displayed. open a web browser and enter: http://127.

Log in as user system with the password you entered during the installation. You should now be logged into the Oracle Database homepage.Testing the Oracle Database XE Installation Figure 3-5 Database home page login screen 2. Figure 3-6 Oracle Database XE home page 27 .

Setting the Oracle Database XE Environment Variables on Linux On Linux platforms. Run the appropriate script for your shell to set your Oracle XE environment variables.Installing Oracle Database 10g Express Edition Configuring Oracle Database XE There are a number of environment settings and configuration options you can set for Oracle Database XE. and oracle_env. Bash or Korn shell. This applies to all the methods of starting and stopping the database. The database is another process that runs in memory. there are a number of environment variables that should be set when you start up the database.bashrc file: export OH=/usr/lib/oracle/xe/app/oracle/product/10. A script is provided to enable you to set the Oracle environment variables when you log in. 28 . The script is located in: /usr/lib/oracle/xe/app/oracle/product/10.sh To add the script to your login profile for C and tcsh shells.2.sh for Bourne. $OH/bin/oracle_env.cshrc file: setenv OH /usr/lib/oracle/xe/app/oracle/product/10.0/server .0/server/bin and named oracle_env. the listener and database should already be running.2. This is because your user is not a member of the operating system dba group. you must log in as a user who is a member of the operating system dba user group. add the user name to the dba group using the System Settings. Bash and Korn shells. and you may have requested during the installation that the listener and database should be started when the operating system starts up. The database listener must be running to handle these requests. To add the script to your Bourne.2. Starting and Stopping the Listener and Database The database listener is an Oracle Net program that listens for and responds to requests to the database.login or . If you need to manually start or stop the database listener. To start the database.csh for C and tcsh shells. The more commonly used settings are discussed here. the options and commands for this are listed below.0/server source $OH/bin/oracle_env. You can also add this script to your login profile to have the environment variables set up automatically when you log in.csh Enabling Database Startup and Shutdown from Menus on Linux You may not be able to start and stop the database using the menu on Linux platforms. add the following lines to your . After installing Oracle Database XE.bash_profile or . add the following lines to your . and needs to be started before Oracle Net can handle connection requests to it. To enable this functionality.

d/oracle-xe stop You can also use the Services dialog from the Desktop to start and stop the listener and database. To stop the listener and database from the Desktop Services dialog. select Applications > System Settings > Server Settings > Services. run the following command in your shell: /etc/init. Starting and Stopping the Listener and Database on Windows To start the listener and database on Windows platforms.Configuring Oracle Database XE Starting and Stopping the Listener and Database on Linux To start up the listener and database on Linux platforms using the desktop. On Linux with KDE: Select K Menu > Oracle Database 10g Express Edition > Start Database. To start the listener and database on Linux platforms using the command line. Select oracle-xe from the list of services and select Stop. run the following command in your shell: /etc/init. 29 .d/oracle-xe start To stop the listener and database on Linux platforms using the command line. To start the listener and database from the Desktop Services dialog. do one of the following: * * On Linux with Gnome: Select Applications > Oracle Database 10g Express Edition > Start Database. A Window is displayed showing the status of the listener and database startup process. select Applications > System Settings > Server Settings > Services. Select oracle-xe from the list of services and select Start. select Start > Oracle Database 10g Express Edition > Start Database. To shut down the database on Linux platforms using the desktop. do one of the following: * * On Linux with Gnome: Select Applications > Oracle Database 10g Express Edition > Stop Database. On Linux with KDE: Select K Menu > Oracle Database 10g Express Edition > Stop Database.

Right click on the Listener service.8 Stop Database Dialog Type exit and press Enter to close the Window. A Window is displayed showing the status of the listener and database shutdown process. 30 . and select the OracleXETNSListener service. You can also start and stop the listener separately on Windows platforms using the Services dialog. Figure 3. open the Services dialog using Start > Settings > Control Panel > Administrative Tools > Services. The listener and database are now started.Installing Oracle Database 10g Express Edition Figure 3. To stop the listener and database on Windows platforms. The listener and database are now stopped. and select Start.7 Start Database Dialog Type exit and press Enter to close the Window. To start the listener on Windows platforms. select Start > Oracle Database 10g Express Edition > Stop Database.

At the SQL*Plus command line prompt. Right click on the Listener service. you also need to start the database using SQL*Plus. To use SQL*Plus to start and stop the database. Starting and Stopping the Listener and Database Using SQL*Plus You can also use the command line shell and SQL*Plus command line to start and stop the listener and database. enter the following commands to connect to the database and start it up: SQL>connect / as sysdba SQL>startup The database is started. This is the sys user in default installations. you need to log in as sysdba. and select Start.Configuring Oracle Database XE To stop the listener on Windows platforms. so if you want one single set of commands to use for all your operating systems. You can also start SQL*Plus from the Applications > Oracle Database 10g Express Edition > Run SQL Command Line on Linux. or Start > Programs > Oracle Database 10g Express Edition > Run SQL Command Line on Windows. and select Stop. open the Services dialog using Start > Settings > Control Panel > Administrative Tools > Services. You can use SQL*Plus on all operating systems. To start up the listener. you use the similar command from the operating system command prompt: lsnrctl stop After starting the listener. To start up a database using SQL*Plus. Make sure that you have your operating system environment set up correctly as discussed in an earlier section of this chapter. Log into SQL*Plus as before and issue the following command: SQL>connect / as sysdba SQL>shutdown immediate The SQL*Plus User’s Guide and Reference gives you the full syntax for starting up and shutting down the database if you need more help. Right click on the database service. and select the OracleServiceXE service. open a command line window and run the following command: lsnrctl start Oracle Net starts the listener and it is ready to take database requests. or you can use operating system authentication if you are on the local machine. and select the OracleXETNSListener service. you must log in as a user with the sysdba role. If you want to shut down the listener manually. To stop the database using the Services dialog on Windows platforms. You can also start and stop the database separately on Windows platforms using the Services dialog. To shut down the database. open the Services dialog using Start > Settings > Control Panel > Administrative Tools > Services. this is a useful option for you. and select the OracleServiceXE service. and issue the SHUTDOWN IMMEDIATE command. enter the following at the command line prompt: sqlplus /nolog SQL*Plus command line starts. open the Services dialog using Start > Settings > Control Panel > Administrative Tools > Services. To start the database using the Services dialog on Windows platforms. 31 . Right click on the database service. and select Stop.

1:8080/apex 2. To use SQL*Plus command line to change this setting. follow these steps: 1.0. it is more secure to leave it as the default setup. log into SQL*Plus as system. Select Administration from the home page.SETLISTENERLOCALACCESS(FALSE). and are not encrypted. Open a web browser and load the Oracle Database XE home page: http://127. To enable connection to the Oracle Database XE home page from remote machines. you should be aware that HTTPS cannot be used (only HTTP).Installing Oracle Database 10g Express Edition Enabling Remote Client Connection The Oracle Database XE home page is only available from the local machine. Log in as the system user. 4. so if you don’t need to set this up. Check the Available from local server and remote clients radio button. If you want to enable access from a remote client. so your login credentials are sent in clear text. 5. Click Apply Changes. Select Manage HTTP Access from the Tasks option. 32 . You can also use SQL*Plus command line to enable access from remote clients. and run the following command: EXEC DBMS_XDB.0. not remotely. 3.

33 .com) as a standalone product.0. and Oracle SQL Developer. Logging In To Oracle Application Express To start and log in to Oracle Application Express: 1. Oracle Application Express Oracle Application Express is a browser-based interface to the Oracle Express Edition database. Open a web browser and enter the URL: http://127.oracle. and we will show you both the GUI and command line tools in this book. Oracle Application Express enables you to perform database administration.CHAPTER 4 Using Oracle Database 10g This chapter contains an overview of Oracle Application Express. It is also available for download from Oracle’s Technology Network (http://otn. Command line utilities are also available. just the database management and scripting components. monitoring and maintenance. two applications that you can use to perform database development and administration with Oracle Database 10g Express Edition. Oracle Application Express also contains a database development tool.0.1:8080/apex The Oracle Application Express login screen is displayed. but this book does not cover that part of the product.

The password you enter here is the password you entered when you installed Oracle. Log in as system. Figure 4-2 Oracle Application Express Interface 34 . There is no default system password set by the Oracle Installer. 2.Using Oracle Database 10g Figure 4-1 Oracle Application Express login screen.

35 . which is automatically installed and configured during an Oracle database installation. You may want to unlock this user now so that many of the examples in this book work correctly. Select Administration > Database Users > Manage Users. Select the HR icon. Log in to Oracle Application Express as shown in the previous section. Figure 4-3 Manage Database Users menu 3. To unlock the hr user: 1. and other Oracle books use the hr user.Oracle Application Express Unlocking the HR User Many of the examples in this book. 2.

enter a password in the Password and Confirm Password fields. To unlock the hr user. Creating Database Objects The Oracle Application Express Object Browser can be used to create or edit the following objects: * Table 36 . and click the Alter User button.Using Oracle Database 10g Figure 4-4 Manage Database Users screen 4. Figure 4-5 User screen The hr account is now unlocked. Change Account Status to Unlocked.

click the Object Browser icon. To create a new table: 1. The following example covers creating a table. On the Database home page. 37 .Oracle Application Express * * * * * * * * * * * View Index Sequence Collection Type Package Procedure Function Trigger Database Link Materialized View Synonym Oracle Application Express uses wizards to guide you through creating these database objects. The Object Browser page is displayed. but you will see that the interface is wizard-based and creating and editing different objects can all be performed through the Object Browser.

Using Oracle Database 10g Figure 4-6 Oracle Application Express create object screen 38 .

Oracle Application Express

2. Click Create.
Figure 4-7 Oracle Application Express create table object screen

3. From the list of object types, select Table.

39

Using Oracle Database 10g

Figure 4-8 Oracle Application Express table definition screen

4. Enter a table name in the Table Name field, and details for each column. Click Next. 6. Define the primary key for this table (optional). 7. Add foreign keys (optional). 8. Add a constraint (optional). 9. Click Finish. To view the SQL used to create the table, click SQL Syntax.

40

Oracle Application Express

Figure 4-9 Oracle Application Express confirm create table screen.

The SQL that is generated to create the table is:
CREATE table "MYTABLE" ( "FIRST_NAME" CHAR(100) NOT NULL, "SECOND_NAME" CHAR(100) NOT NULL, "SALARY" NUMBER, "BIRTHDATE" DATE ) /

You could also run this command in SQL*Plus command line to create the table.

41

click the SQL icon. Click the Query Builder icon. 42 . 2. This example uses the Query Builder to graphically create a SQL script to query data. On the Database home page.Using Oracle Database 10g 10. Click Create. Working with SQL Scripts The SQL Console enables you to: * * * Write SQL and PL/SQL Load and save SQL scripts Graphically build SQL The following example guides you through creating a SQL script. The table is created and a description of the table is displayed. Figure 4-10 Oracle Application Express table created confirmation screen. To get a better set of tables to work with in this example. To access Query Builder: 1. log in as the hr user.

43 .Oracle Application Express Figure 4-11 Oracle Application Express SQL options screen.

Click Run to execute the query and view the results. Select columns from the objects in the Design pane to select which columns to include in the query results. 4. Establish relationships between objects by clicking on the right-hand column of each table (optional). Select objects from the Object Selection pane. When you click on the object name. it is displayed in the Design pane. 6. Create query conditions (optional). Figure 4-12 Oracle Application Express SQL query builder screen. 44 . 7. 5.Using Oracle Database 10g 3.

create or replace package emp_sal as procedure emp_stat. On the Database home page. 2. averages the salary for departments in the hr schema. Click the SQL Commands icon to display the SQL Commands page. Here is some PL/SQL code to try if you aren’t familiar with PL/SQL. Creating a PL/SQL Procedure To enter and run PL/SQL code in the SQL Commands page: 1. enter some PL/SQL code.Oracle Application Express Figure 4-13 Oracle Application Express SQL query results screen. end emp_sal. / 45 . emp_stat. On the SQL Commands page. and is encapsulated in a PL/SQL package called emp_sal. and click Run. You need to enter each block separately. click the SQL icon to display the SQL page. 8. 3. You can save your query using the Save button. This procedure.

END.' ')|| TO_CHAR(EmpStatVar. Dept_avg number).'999. END LOOP. Click Run to execute the PL/SQL.department_id group by d.99')).department_name) LOOP DBMS_OUTPUT.b.16. For EmpStatVar in (select round(avg(e. EmpStatVar EmpStatTyp.PUT_LINE(RPAD(EmpStatVar.999.999.salary).department_id=e.2) a. end emp_sal.d. DBMS_OUTPUT. BEGIN DBMS_OUTPUT.Using Oracle Database 10g Figure 4-14 Oracle Application Express PL/SQL and SQL command screen.PUT_LINE('Department Avg Salary'). employees e where d. The PL/SQL code is executed. 46 . Click Run.PUT_LINE('-------------------------').department_name b from departments d. Then enter the following code: create or replace package body emp_sal as Procedure emp_stat is TYPE EmpStatTyp is record (Dept_name varchar2(20).a.

To create a database user: 47 .emp_stat. This account is considered an administrator account because it has DBA privileges (SYSDBA). To perform database administration such as creating new users. If you want to save the PL/SQL code for future use. begin emp_sal. 5. Creating a Database User The Administration console is used to manage database: * * * * Storage Memory Users Activity of sessions and operations The installation process creates an account named system. end. click Save.Oracle Application Express 4. log into Oracle Application Express as the system user. You can execute the stored procedure by entering the following PL/SQL code and clicking Run.

Figure 4-15 Oracle Application Express Administration screen.Using Oracle Database 10g 1. Click the Database Users icon. On the Database home page. 48 . click the Administration icon. Figure 4-16 Oracle Application Express Manage Database Users screen.

The Create Database User page is displayed. click Create. enter a password. gives the user the ability to create schema objects in other users' schemas. enter a username. On the Manage Database Users page.2 3. Enter user information into text fields: 3.3 3.Oracle Application Express 2. In the Password and Confirm Password fields. Figure 4-17 Oracle Application Express Create Database User screen. Grant all create object system privileges by clicking Check All at the lower right-hand corner of the User Privileges box. The DBA role is by default not selected. 49 . 3.1 3.4 In the Username field. and to create other users. The DBA privilege.

Using Oracle Database 10g 4. The Manage Database Users page displays a confirmation that the user was created. To view the current sessions: 50 . Click Create. This enables you to determine the users who are currently logged in to the database and what applications they are running. you can view: * * * All sessions Active sessions only Sessions that match a search string You should be logged in as the system user to perform any database administration. When you view sessions. Monitoring Database Sessions You can use the Oracle Database XE graphical user interface to monitor the current database sessions. You can also use the Oracle Database XE graphical user interface to kill a session—to cause it to be disconnected and its resources to be relinquished. Figure 4-18 Oracle Application Express Manage Database Users screen.

Figure 4-19 Oracle Application Express Administration screen.Oracle Application Express 1. 3. click Sessions. Figure 4-20 Oracle Application Express Administration Monitor screen. 51 . click the Administration icon. On the Database Monitor page. On the Database home page. Click Monitor.

Figure 4-21 Oracle Application Express Sessions screen. if in ARCHIVELOG mode. the server parameter file (SPFILE). and. and store backup files in the flash recovery area. The Session Details page enables you to kill the session. database backup and recovery is handled by Recovery Manager (RMAN). select All. 6. In ARCHIVELOG mode. the redo log files.) 5. The page displays all sessions. Database Backup and Recovery Backing up and restoring Oracle Database XE is based on protecting the physical files that make up the database: the datafiles. 7. all archived logs required for media recovery from either backup are also retained. Oracle Database XE includes backup and restore scripts that you access using menu on your desktop. Oracle Database XE implements a backup retention policy that dictates that two complete backups of the database must be retained. Machine. including idle sessions. running SQL statements. click a session ID to view the Session Details page for that session. (Optional) In the Status list. Client Information. and open cursors. and click Go. Database User. (Optional) Click any of the hyperlinks above the Search field to view the following information for all sessions: Locks. OS User. The database automatically 52 . In Oracle Database XE. (An example of an idle session is a SQL*Plus command line session that is not currently running a command. Waits. Client Identifier. (Optional) Narrow down the sessions list by entering search text into the Search field and clicking Go. the control file.Using Oracle Database 10g The Sessions page is displayed and shows the current active sessions. These scripts perform a full backup and restore of the entire database. A session is shown if any of the following fields contain the search text: SID. (Optional) Under the SID column. Input/Output (I/O). and Module. 4.

and deletes obsolete backups and archived logs at the end of each backup job. Log in to the Oracle Database XE host computer as a user who is a member of the dba user group. select K Menu > Oracle Database 10g Express Edition > Backup Database. and then uses the online and archived redo log files to recover the database to the state it was in before the software or media failure occurred. Log archiving on (ARCHIVELOG mode) restores the backed up database files. and any uncommitted transactions that were under way when the failure took place are rolled back (using undo data from the restored undo tablespace). the script displays the following output: 53 . Do one of the following: * On Linux with Gnome. Backing Up The Database To back up the database: 1. The restore script restores the database differently depending on whether log archiving is on or off. If running in ARCHIVELOG mode.Oracle Application Express manages backups and archived logs in the flash recovery area. * On Windows. * On Linux with KDE. The backup script performs online backups of databases in ARCHIVELOG mode and offline backups of databases in NOARCHIVELOG mode. A console window opens so that you can interact with the backup script. All committed transactions that took place after the last backup are recovered. 2. select Applications > Oracle Database 10g Express Edition > Backup Database. Online backups are backups that can run while the database is running. Log archiving off (NOARCHIVELOG mode) restores the database to its state at the last backup. select Start > Programs > Oracle Database 10g Express Edition > Backup Database. Any transactions that took place after the last backup are lost. Offline backups are backups that run when the database is shut down.

If prompted.Using Oracle Database 10g Figure 4-22 Oracle Application Express backup dialog 3. After the backup is complete. Log in to the Oracle Database XE host computer as a user who is a member of the dba user group. Press any key to close the Backup Database window. 54 .log $ORACLE_HOME/oxe_backup_previous. the script displays the following output: Figure 4-23 Oracle Application Express backup successful message 4. Logs containing the output from the backups are stored in the following locations: $ORACLE_HOME/oxe_backup_current.log Restoring the Database To restore a database from a backup: 1. answer y to confirm the database shutdown and begin the backup.

Oracle Application Express 2. Answer y to confirm the database shutdown and begin the restore. * On Linux with KDE. select K Menu > Oracle Database 10g Express Edition > Restore Database. Press any key to close the Restore Database window. The script displays the following output: Figure 4-24 Oracle Application Express restore dialog 3. Do one of the following: * On Linux with Gnome. select Start > Programs > Oracle Database 10g Express Edition > Restore Database. A console window opens so that you can interact with the restore script. the script displays the following output: Figure 4-25 Oracle Application Express restore successful message 4. * On Windows. After the restore is complete. select Applications > Oracle Database 10g Express Edition > Restore Database. 55 .

and to run a few SQL*Plus commands (like DESCRIBE).log.2. you can also use Oracle SQL Developer for database development and maintenance. The default SQL Developer screen is shown in figure 4-26. Oracle SQL Developer is a free. and give feedback to the SQL Developer product team.oracle. You can download SQL Developer from the Oracle Technology Network at http://www. and you can create and save your own reports. There is also a discussion forum for you to ask questions of other users.1 onwards. SQL Developer can connect to Oracle databases from version 9. thick client graphical tool for database development. Oracle SQL Developer In addition to Oracle Application Express. You can use SQL Developer to execute SQL statements.0. documentation. and is available on Linux. You can also download patches. Creating a Database Connection When you start SQL Developer for the first time.Using Oracle Database 10g A log containing the output from the restore is stored in $ORACLE_HOME/oxe_restore. there are no database connections configured. extensions. Windows and Mac OSX. Figure 4-26 Oracle SQL Developer login screen 56 . execute and debug PL/SQL statements.com/technology/products/database/sql_developer. and other resources from this site. SQL Developer includes some prebuilt reports. so the first thing you need to do is create one.

A message is displayed at the bottom left side of the dialog to tell you whether the test connection succeeded. Click the Test button to test the connection. Click the Connect button to save the connection and connect to it.Oracle SQL Developer To create a database connection to the local Oracle XE database: 1. and password you created for the hr user. the hostname localhost. Figure 4-27 Oracle SQL Developer Connection screen 2. and the SID XE. 57 . right click and select New Connection. Select Connections in the left pane. Enter the login credentials for the Oracle Database XE with the username hr.

58 . the employees table is displayed. Throughout SQL Developer. Select the Data tab for the employees table to display the records available. there are context sensitive menus.Using Oracle Database 10g Figure 4-28 Oracle SQL Developer main screen When you have connected to a database. the records are marked with an asterisk. If you make any changes. and the right pane shows the contents of the object. update data and delete rows using the data grid. In Figure 4-28. Editing Data You can view and edit data using the Data tab for a table definition. you can browse through the database objects displayed in the left pane. You can add rows. Fig 4-26 shows the choice of context menus available in the data grid.

To create a new table: 1. You can use this method to create any of the database objects displayed in the left pane. Enter the column names. 59 . indexes.Oracle SQL Developer Figure 4-29 Oracle SQL Developer Data Grid Creating a Table You can create database objects such as tables. right click and select Create Table. The Create Table dialog is displayed. and PL/SQL procedures using SQL Developer. right click on the database object type you want to create. and follow the dialogs. Select Tables in the left pane. types and other parameters as required. To create a database object. views.

indexes. Click OK to create the table.Using Oracle Database 10g Figure 4-30 Oracle SQL Developer Create Table screen Click the Advanced check box to see more advanced options like constraints. 60 . foreign keys. Figure 4-31 Oracle SQL Developer Advanced Create Table screen 2. and partitions. The new table mytable is now listed in the left pane.

If the tab is not available. 61 . Select the Database Connection tab in the right hand pane. Some SQL*Plus commands can also be executed. To execute a SQL statement in SQL Developer: 1. mytable Click on the tabs displayed in the right pane to see the options available on the table. The SQL Worksheet component is displayed. Executing a SQL Query The SQL Worksheet component included in SQL Developer can be used to execute SQL and PL/SQL statements. and filter rows in the table.Oracle SQL Developer Figure 4-32 Oracle SQL Developer screen showing the new table. sort. such as the Data tab. select the menu Tools >SQL Worksheet. modify. which enables you to add. You are prompted for the database connection name. This is the connection created earlier in Creating a Database Connection. delete. and a set of tabs below that for further options. and shows an area to enter statements.

Click the Run Script icon (the second from the left in the right hand pane). 62 . If you have used Oracle’s command line tool SQL*Plus. You can view the output of the SELECT statement in the Results tab. by using F5.EMPLOYEES. using F9. Enter the following two statements in the SQL Worksheet: DESCRIBE HR. and the output of the whole script (including the DESCRIBE and SELECT statements) in the Script Output tab.Using Oracle Database 10g Figure 4-33 Oracle SQL Developer screen showing SQL Worksheet 2. Both the lines of this script are run and the output is displayed in tabs below. or press F5. the output in the Script Output window is likely to be familiar to you.EMPLOYEES SELECT * FROM HR.

Oracle SQL Developer Figure 4-34 Oracle SQL Developer screen showing SQL Worksheet with output 63 .

In this case.Using Oracle Database 10g 3. or press F9. and the results are shown in the Results tab. 64 . select the line you want to execute and click on the Execute Statement icon (the first from the left in the right hand pane). Figure 4-35 Oracle SQL Developer screen showing SQL Worksheet with output You should also take a moment to click on the Snippets on the top right hand of the interface. If you want to execute a single line of the two-line statement. Snippets are a handy set of SQL and PL/SQL code snippets that you can drag into the SQL Worksheet component. the SELECT statement (second line) is selected.

Add the name ADD_DEPT and click OK. compile. run. edit. 65 . Right click the Procedures node and select New Procedure from the context menu. Compiling and Running PL/SQL You can use SQL Developer to browse. 1. create. and debug PL/SQL.Oracle SQL Developer Figure 4-36 Oracle SQL Developer screen showing code snippets Editing.

The PL/SQL Editor is opened. LOCATION_ID) VALUES(DEPARTMENTS_SEQ. LOC IN DEPARTMENTS.Using Oracle Database 10g Figure 4-37 SQL Developer new procedure dialog 1.NEXTVAL. they will appear in the Message-Log window below 66 . LOC). NAME. Replace or add the text so that your code is as follows: CREATE OR REPLACE PROCEDURE ADD_DEPT (NAME IN DEPARTMENTS. If there are errors. 2. DEPARTMENT_NAME. Compile the code by selecting the compile icon in the toolbar.LOCATION_ID%TYPE) IS BEGIN INSERT INTO DEPARTMENTS(DEPARTMENT_ID. END ADD_DEPT.DEPARTMENT_NAME%TYPE.

Oracle SQL Developer Figure 4-38 SQL Developer PL/SQL Code Editor 3. SQL Developer provides dialog with an anonymous block to help test and run your code. Training and 1800. Run the procedure. 67 . for example. 4. Find and replace the NULL values with values of your own. Query the Departments table to see the results added. The green arrow icon runs the code.

You can also create your own reports (using SQL and PL/SQL). all the tables owned by a user. getting lists of all users in a database. for example. To display the version numbers of the database components using one of the supplied reports: 68 . and include them in SQL Developer. or all the views available in the data dictionary.Using Oracle Database 10g Figure 4-39 SQL Developer Run PL/SQL dialog Running Reports There are a number of reports included with SQL Developer that may be useful to you.

The report is run and the results are displayed in the right hand pane. Click the Run Report in SQL Worksheet icon (next to Refresh). You can also export the supplied reports to edit and add back as user defined reports. Figure 4-40 Oracle SQL Developer screen showing output from a report 2. Navigate down to Reports > Data Dictionary Reports > About Your Database > Version Banner.Oracle SQL Developer 1. Select the Reports tab in the left hand pane. 69 . The source code is written to the SQL Worksheet.

1. select User Defined Reports. to categorize them. and right click. Complete the details in the dialog. You can use this folder to import or add new reports. It is good practice to create folder for your reports. Right click the User Defined Reports node and select Add Folder. 70 .Using Oracle Database 10g Figure 4-41 Oracle SQL Developer screen showing the source code of a report Creating Reports To create your own reports.

LOCATIONS L. DEPARTMENT_NAME 7.DEPARTMENT_ID= D.LOCATION_ID = L. 71 .DEPARTMENT_ID) order by CITY. 6. You can test the report to ensure your SQL is correct. Notice that the default style is table. without leaving the dialog. CITY FROM DEPARTMENTS D.MANAGER_ID= E. EMPLOYEES E WHERE(D. Click the Test button on the Details tab.Oracle SQL Developer Figure 4-42 SQL Developer User Defined Reports 5. Give the report a name and description and enter the following SQL text.LOCATION_ID) AND(D. SELECT Last_name. Select the folder you created and right click to select Add Report. DEPARTMENT_NAME.EMPLOYEE_ID) AND(E.

select it in the Reports Navigator. 72 . 9. You are prompted for a database connection. To run the report.Using Oracle Database 10g Figure 4-43 SQL Developer Create Report Dialog 8. Click Apply to save and close.

For all reports. charts. Tabular Report You can create tabular reports. 73 . supplied and user defined.Oracle SQL Developer Figure 4-44 SQL Developer User Defined. drill down reports and master/detail reports. import and share your reports. you can export.

.

cgi.59 available from http://httpd. you may be wondering why we did not need to invoke bunzip2 to extract the .apache.gz gzipped file. To start Apache HTTP Server: /usr/local/apache/bin/apachectl start 75 . Use this script to start and stop Apache HTTP Server. If you downloaded the . The procedure to install on other Linux platforms is the same as for Oracle Enterprise Linux. Log in as the root user and execute the following commands: tar -jxvf httpd-2.59.tar.tar.0. If you already have Apache installed.59. Linux includes the GNU version of tar.0. If you are familiar with the tar command on UNIX systems. you should use the default pre-fork MPM (“Multi-Processing Module”). which has a new j flag to automatically uncompress a bzipped .apache. The version used in this installation is httpd-2. The installation shows Oracle Enterprise Linux and Windows XP Professional Edition and uses Apache HTTP Server Release 2. Note: With Apache 2.bz2 cd httpd-2. Installing Apache HTTP Server on Linux To install the Apache HTTP Server for use with PHP on Oracle Enterprise Linux.org/download.0.tar file. because threadsafety of many of the PHP libraries is not known. the --prefix= option sets where Apache HTTP Server will be installed during the command make install.CHAPTER 5 Installing Apache HTTP Server This chapter gives you the steps needed to install and configure the Apache HTTP Server for use with PHP.bz2. Starting and Stopping Apache HTTP Server The apachectl script is installed in the Apache bin directory. 2./configure --prefix=/usr/local/apache --enable-module=so make make install When configuring the web server.cgi. Download the Apache HTTP Server from http://httpd.tar file. Also. the option --enable-module=so allows PHP to be compiled as a Dynamic Shared Object (DSO). you could have used the z flag instead.org/download. you can use it instead.0.59 . 1.

Double click the downloaded file apache_2. 2.ini configuration files for any incorrect settings. Any other required Oracle environment variables must be set before Apache HTTP Server starts as well.apache.0. and make corrections. When you start Apache HTTP Server. check your httpd.msi.2.0. Follow the Apache HTTP Server installation wizards. for example: start_apache #!/bin/sh ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10. Download the Apache HTTP Server Windows binaries from http://www.2. you must at least have the environment variable $ORACLE_HOME defined. and the downloaded file is named apache_2.59win32-x86-no_ssl. there is a script located in $ORACLE_HOME/install/changePerm. With Oracle 10g Release 10. If there are errors. on Port 80.0.sh to do this.org/dist/httpd/binaries/win32/. because the only for the Current User alternative will clash with Oracle Database Express Edition’s default port 8080. If you have problems. 1. 76 . Now stop Apache so it can be configured for PHP: /usr/local/apache/bin/apachectl stop Note: If you are using Oracle 10g Release 10.0. you may create a script to start Apache HTTP Server.conf and php.sh or the /usr/local/bin/oraenv scripts.msi. you must give the nobody user access to the Oracle directory. the Apache HTTP Server is started. You should now test that Apache HTTP Server has been installed properly and started on your machine by opening your web browser to http://localhost/ to display the Apache home page. To simplify things. The release used in this installation is Apache HTTP Server 2. You should select to install Apache HTTP Server for All Users.2.Installing Apache HTTP Server You should test that Apache has been installed properly and is started on your machine by opening your web browser to http://localhost/ to display the Apache home page. 3. These are the same variables set by the $ORACLE_HOME/bin/oracle_env. they are displayed on your screen. but not the Express Edition.59-win32-x86-no_ssl.59.0/server export ORACLE_HOME echo "Oracle Home: $ORACLE_HOME" echo Starting Apache /usr/local/apache/bin/apachectl start Installing Apache HTTP Server on Windows The following procedure describes how to install the Apache HTTP Server on Windows. Starting and Stopping Apache HTTP Server As part of installation. Errors may also be recorded in /usr/local/apache/logs/error_log.2.

Alternatively. 77 . use the Apache options added to your Windows Start menu.Installing Apache HTTP Server on Windows Your system tray has an Apache Monitor control that makes it easy to stop and restart the Apache HTTP Server when needed.

.

CHAPTER 6

Installing PHP
This chapter discusses installing PHP as an Apache module on Linux and Windows using a local Oracle database. It also discusses installing OCI8 with Oracle Instant Client if have a remote database. You can use either the OCI8 extension for native access to Oracle, or the PHP Data Object (PDO) abstraction layer extension. PDO is a new PHP extension that enables you to abstract the database code and have the extension handle the translation and execution of that code with the native database extension, in this case, OCI8.

Note: The Oracle database and Apache HTTP Server need to be installed before following the steps in this chapter. Alternatively, if you have a remote database, you can use the Oracle Instant Client configuration steps. If you installed Apache to a different location or use a pre-installed version, you will need to adjust the path to its location in the installation steps.

Installing OCI8 with PHP 5
The OCI8 extension is included with PHP 5.1.2 onwards, or available from the PECL download site. This section gives steps on installing the OCI8 extension with PHP 5. The installation uses PHP 5.2.2, Oracle Enterprise Linux, and Windows XP Professional Edition.

Installing OCI8 on Linux
To install OCI8 on Oracle Enterprise Linux: 1. Download PHP 5.2.2 from http://www.php.net/downloads.php. 2. Log in as the root user and extract the PHP source code:
tar -jxvf php-5.2.2.tar.bz2 cd php-5.2.2

3. Configure PHP with OCI8 and Oracle:
export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/ 10.2.0/server ./configure \ --with-apxs2=/usr/local/apache/bin/apxs \ --with-config-file-path=/usr/local/apache/conf \ --with-oci8=$ORACLE_HOME \ --enable-sigchild 79

Installing PHP

If you are using the default Apache on Oracle Enterprise Linux, the path to the Apache extension tool is /usr/sbin/apxs. If you have installed Apache 1.3 instead of Apache 2, change the option to –-withapxs.

4. Make and install PHP.
make make install

5. Copy PHP’s supplied initialization file, php.ini-recommended:
cp php.ini-recommended /usr/local/apache/conf/php.ini

6. For testing it is helpful to edit /usr/local/apache/conf/php.ini and set display_errors to On so you see any problems in your code. Make sure you change this configuration option to Off before you make your application available to users. 7. Edit Apache’s configuration file /usr/local/apache/conf/httpd.conf and add the following lines:
# # This section will call PHP for .php, .phtml, and .phps files # AddType application/x-httpd-php .php AddType application/x-httpd-php .phtml AddType application/x-httpd-php-source .phps # # This is the directory containing php.ini # PHPIniDir "/usr/local/apache/conf"

8. If a LoadModule line was not already inserted by the PHP install, add it too:
LoadModule php5_module modules/libphp5.so

9. Set any required Oracle environment variables, such as NLS_LANG. 10. Restart Apache.
/usr/local/apache/bin/apachectl start

If you are using an Oracle Database 10g Release 2 database other than the Express Edition (“XE”), you may need to give the Apache process access to Oracle’s libraries and globalization data. Refer to the $ORACLE_HOME/install/changePerm.sh script. Each time you restart Apache, make sure you have the same environment variables set for Oracle. In particular ORACLE_HOME should always be set.

Installing OCI8 on Windows
To install OCI8 on Windows XP Professional Edition: 1. Download the PHP 5.2.2 installer package from http://www.php.net/downloads.php.
80

Installing OCI8 with PHP 4

2. Double click on the downloaded file php-5.2.2-win32-installer.msi. The PHP Windows installer starts. 3. Click Next on the Welcome screen. The license agreement is displayed. 4. Accept the license agreement by checking the box and click Next. 5. Select the installation location of the PHP files and click Next. 6. In the Web Server Setup screen, select the web server you want to use. This installation uses the Apache 2.0 module option. Select Apache 2.0.x Module and click Next. 7. In the Apache Configuration Directory screen, select the location of the Apache conf directory and click Next. 8. In the Choose Items to Install screen, scroll down to the Extensions branch and add the Oracle 8 extension to the installation. Click Next. 9. In the Ready to Install PHP 5.2.2 screen, click Install. The installer installs PHP. 10. A dialog is displayed asking whether you want to configure Apache. Click Yes. 11. A confirmation message is displayed to confirm that the httpd.conf file has been updated. Click OK. 12. A confirmation message is displayed to confirm that the mime.types file has been updated. Click OK. 13. A final confirmation message is displayed to confirm that the PHP installation has completed. Click Finish. 14. Restart Apache with Start > Programs > Apache HTTP Server 2.0.59 > Control Apache Server > Restart. This opens a console window showing any error messages. Errors may also be recorded in C:\Program Files\Apache Group\Apache2\logs\error.log. If you have errors, double check your httpd.conf and php.ini files, and correct any problems.

Installing OCI8 with PHP 4
PHP 4 ships with the old OCI8 extension. If you use PHP 4, you should get the re-factored OCI8 from PECL. It works with PHP 4.3.10 onwards.

Installing PHP 4 on Linux
To install OCI8 on Oracle Enterprise Linux: 1. Download php-4.4.6.tar.bz2 from http://www.php.net/downloads.php. 2. Extract the files and delete the included oci8 extension
tar -jxf php-4.4.6.tar.bz2 rm -rf php-4.4.6/ext/oci8 81

Download the latest OCI8 extension from http://pecl. Download the PHP 4./buildconf --force 5.conf and add the following lines.1 Change extension_dir to C:\php-4.6-Win32\php4ts.dll for the 4. 4. Download php_oci8.dll. if you intend to use Oracle Instant Client.4.php.dll into the C:\php-4.cache autom4te. Installing PHP 4 on Windows To install OCI8 on Windows XP Professional Edition: 1.3. Uncompress php-4. 3.6 rm –rf config.6-Win32\extensions\php_oci8. 2.php. If you run the PHP command line interface copy it to the C:\php-4. 6.4.net/ext. 9.4.tgz mv oci8-1.6Win32\extensions\php_oci8.6-Win32\cli directory too. 3.4.4 branch from http://pecl4win.Installing PHP If you only rename the oci8 directory the configuration script will not be properly built. Delete the old OCI8 extension file C:\php-4.ini-recommended to C:\Program Files\Apache Group\Apache2\conf\php.3 php-4. Copy php.dll.4. which is the directory containing php_oci8.4.dll and the other PHP extensions. Rebuild the configuration script with the updated extension’s options: cd php-4. so you see any problems in your code. 7.6-Win32\sapi directory.2.6-Win32\extensions. Make sure to use forward slashes ‘/’ instead of back slashes ‘\’: 82 .ini.dll. Edit php.6 ZIP file from http://www.4.net/downloads. by following the steps in the section Installing OCI8 With Oracle Instant Client.6-Win32.4. Copy C:\php-4.4.php.2. Edit the file httpd.4.conf .zip to a directory called C:\php-4. 8. Note the OCI8 DLLs from PECL require Oracle 10g client libraries.php/php_oci8.php. 7.4.dll and move it to C:\php-4. Configure and build PHP following step 2 onward in the previous section Installing PHP on Linux or.net/package/oci8 Extract the files and move the directory to ext/oci8: tar -zxf oci8-1.ini and perform the following: 7.6-Win32. it is helpful to set display_errors to On. 5.2 Uncomment (remove the semicolon from the beginning of the line) the option extension=php_oci8. For testing.6/ext/oci8 4.

2.rpm rpm -Uvh oracle-instantclient-devel-10. you can install Oracle Instant Client and configure PHP to enable connections to Oracle databases.2.oracle. the two packages are about 32 MB in size. install the RPMs as the root user: rpm -Uvh oracle-instantclient-basic-10.0. To install: 1. unzip the Basic and the SDK packages to a directory of your choice. Collectively. Installing OCI8 with Instant Client on Linux After installing the Apache HTTP Server.Installing OCI8 With Oracle Instant Client # # This will load the PHP module into Apache # LoadModule php4_module C:/php-4.0. If you are using the RPMs.3/client. 3.3-1. 2.4.com/technology/tech/oci/instantclient/instantclient. then Oracle libraries will generally already be accessible and Instant Client is not required.phps # # This is the directory containing php.html. requiring installation of only a few libraries and header files. If the database is local.i386.3/client/lib and the second creates headers in /usr/include/oracle/10. The files should be unzipped together so the SDK is in $HOME/instantclient10_2/sdk. Typically the database is on another machine. and .6-Win32/sapi/php4apache2.php. Download the Basic and SDK Instant Client packages from the Instant Client page on the Oracle Technology Network. If you are using the Instant Client ZIP files.2.2.0. .php AddType application/x-httpd-php .0.phps files # AddType application/x-httpd-php . Set LD_LIBRARY_PATH to include the location of the Instant Client libraries: export LD_LIBRARY_PATH=\ $LD_LIBRARY_PATH:/usr/lib/oracle/10.0.3-1. for example $HOME/instantclient10_2. An existing Oracle database is needed in this installation scenario.dll # # This section will call PHP for .3/client/lib 83 . http://www.phtml AddType application/x-httpd-php-source . as Instant Client does not include one.2.i386.rpm The first RPM puts the Oracle libraries in /usr/lib/oracle/10. This section shows how to install the OCI8 extension with PHP using Oracle Instant Client.ini # PHPIniDir "C:/Program Files/Apache Group/Apache2/conf" Installing OCI8 With Oracle Instant Client The free Oracle 10g Instant Client is the easiest way for PHP to connect to a remote Oracle database.phtml.

tar.2. Configure PHP with: .ora file to define Oracle Net service names (database aliases). 11. use $HOME/instantclient10_2 instead.ini 9. you also need to apply a PHP patch given in PHP bug 31084 to build PHP with Oracle Instant Client.2. Log in as the root user and extract the PHP source code: tar -jxvf php-5.3.2.2 from http://www. Download PHP 5. See the configuration help using the . set the TNS_ADMIN environment variable to the directory containing the file. Restart the Apache HTTP Server.5. 10.2. Unset any Oracle environment variables that are not required by Instant Client. If you are using a tnsnames. 4. such as NLS_LANG.3/client/lib \ --enable-sigchild If you are using the ZIP files then change the --with-oci8 option to the unzipped directory: --with-oci8=instantclient./configure –-help command to check which syntax you should use. 5. such as ORACLE_HOME and ORACLE_SID.php.Installing PHP If you installed Instant Client from the ZIP files. 84 .11 and 5.2.2 6. If you are using a version of PHP that is earlier than releases 4. Rebuild PHP: make make install 8.php./usr/lib/oracle/10.0. Note: The configuration option in older versions of PHP is --with-oci8-instant-client.net/downloads.ini-recommended /usr/local/apache/conf/php./configure \ --with-apxs2=/usr/local/apache/bin/apxs \ --with-config-file-path=/usr/local/apache/conf \ --with-oci8=instantclient. Set any required Oracle environment variables. Copy PHP’s supplied initialization file to the location given by --with-configfile-path: cp php. See the Globalization chapter.$HOME/instantclient10_2 7.0. for more information on globalization with PHP and Oracle.bz2 cd php-5.

5. Unset any Oracle environment variables that are not required. Set any other required Oracle globalization language environment variables. Install PHP following the steps in the previous chapter.dll * oci.0.com/technology/tech/oci/instantclient/instantclient.0 does not support the Oracle PDO extension. before any other Oracle directories. Edit the environment and add the location of the Oracle Instant Client files.1. This procedure works for all versions of PHP after release 5. Download the Instant Client Basic package for Windows from the Instant Client page on the Oracle Technology Network. the default local environment is used. C:\instantclient10_2). Oracle Enterprise Linux.2. Installing PDO To use PDO with Oracle. http://www. 4. Installing PHP. such as NLS_LANG.dll 3.html. The installation uses PHP 5. Unzip the downloaded file into the new directory.2. See the Globalization chapter. C:\instantclient10_2. If you are using a tnsnames.zip and is around 32 MB in size. you can unzip just the following files to the new directory: * oraociei10. use Start > Settings > Control Panel > System > Advanced > Environment Variables.oracle. install the PDO extension and the native database extension for Oracle. for more information on globalization with PHP and Oracle.ora file to C:\instantclient10_2.Installing PDO Installing OCI8 with Instant Client on Windows After installing the Apache HTTP Server. If nothing is set. If you want to use the minimum files required. It will likely be supported in a future release.3-20061115. Zend Core for Oracle release 2. PDO_OCI. Apache 2. such as ORACLE_HOME and ORACLE_SID. To install: 1. A default service name can optionally be set in the user environment variable LOCAL.2.0. and edit PATH in the System Variables list. Create a new directory (for example. on Windows XP. to the PATH environment variable. Restart the Apache HTTP Server. The Windows 32 bit ZIP file is called instantclient-basic-win32-10. and Windows XP Professional Edition.dll * orannzsbb10.1. you can install Oracle Instant Client and configure PHP. copy the tnsnames. For example.59. 2. and set the user environment variable TNS_ADMIN to C:\instantclient10_2. when the extension is more stable and widely used.ora file to define Oracle Net service names (database aliases). The PDO extensions are included in PHP from release 5. You 85 .

/usr. If you want to build PDO_OCI with the Oracle Instant Client (See the chapter Installing PHP With Oracle Instant Client). you should see PDO and PDO_OCI.10.2.2.10.php.2. PDO_OCI and Oracle: export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/ 10.3 or --with-pdo-oci=instantclient.0/server . Installing PDO on Linux To install PDO on Oracle Enterprise Linux: 1. Configure PHP with PDO.2. 86 . Continue from step 5 of the previous section Installing OCI8 on Linux to create the php./configure \ --with-apxs2=/usr/local/apache/bin/apxs \ --with-config-file-path=/usr/local/apache/conf \ --enable-pdo \ --with-pdo-oci=$ORACLE_HOME \ --enable-sigchild Note there is no “8” in the –-with-pdo-oci option name. 2.bz2 cd php-5.Installing PHP can install PDO_OCI and OCI8 at the same time by combining the appropriate options to configure.2 from http://www.2.php. Check the extension has been installed correctly: php -m In the list of modules.$HOME/instantclient_10_2.tar.ini script and configure Apache.2.2 3. Review the output of configure and check that the extension was enabled successfully before continuing. Download PHP 5. PHP’s configure script ignores options it does not recognize and will not warn if you make a mistake with the name.3 4. Log in as the root user and extract the PHP source code using the following commands: tar -jxvf php-5.net/downloads. change the –-with-pdo-oci option to: --with-pdo-oci=instantclient. 6. make make install 5. Make and install PHP.2.0.0.

Figure 6-1 PDO Installation on Windows 4. 87 . 2. The Oracle PDO_OCI extension is now installed and configured with PHP. 3. Follow the steps in Installing OCI8 on Windows. Install an Oracle Client or Oracle Database.Installing PDO Installing PDO on Windows To install PDO on Windows XP Professional Edition: 1. Continue with the rest of the PHP installation. Restart Apache. 5. add the PDO extension by also selecting to install PHP > Extensions > PDO > Oracle 8i +. At step 8. This procedure uses Oracle Instant Client 10g. See the section Installing OCI8 With Oracle Instant Client for steps on installing Oracle Instant Client 10g.

.

So you can use this procedure on all supported operating systems. 6. web server and PHP.2.0 is a fully tested and supported PHP distribution that includes integration with Oracle Database 10g client libraries. Zend Core for Oracle release 2.CHAPTER 7 Installing Zend Core for Oracle Zend Core for Oracle 2. It is a pre-built stack that makes it easier to get started with PHP and Oracle.x (except on Windows Vista). but the installation is similar on all platforms. 9 10 The web servers that are supported are: * * * Apache 1.3 Sun Solaris Sparc 8.1. and an optional Apache HTTP Server 2. That means that you can have a fully supported stack of database. 7 Zend Core for Oracle is supported against Oracle Database 10g and 9i. The collaboration between Oracle and Zend reinforces Oracle’s commitment to the open source PHP community. 89 . Installing Zend Core for Oracle This procedure installs Zend Core for Oracle on Linux and Windows platforms.2. The procedure to install on other operating systems is similar as the installer is the same on all operating systems.2.0 includes PHP 5. the refactored OCI8 driver.0 (on Linux and Windows x86) Microsoft IIS 5.1.3.0 Zend Core for Oracle 2. Apache 2.2 or 5. Zend Core for Oracle is supported by Zend on the following operating systems: * * * * * * * Oracle Enterprise Linux X86 running SLES9 or RHEL3 or RHEL4 X86 running Windows XP/2003/Vista X86-64 running Windows Vista in 32bit mode X86-64 running SLES9 or RHEL3 or RHEL4 pSeries running AIX 5.x Oracle HTTP Server 10. Oracle Instant Client. There are some slight differences.0. like the names and locations of the web server.2. as all the hard work of installation and configuration has been done for you.

The next page prompts you to select the web server to use for the Zend Core for Oracle installation. 4.0. 90 . click Yes. click Yes. The installer begins extracting the files required for the installation.gz Files are extracted to a subdirectory called ZendCoreForOracle-v2. In the page confirming your web server selection./install 5.gz: tar -zxf ZendCoreForOracle-v2. su Password: 3.0. In the initial Zend Core for Oracle Installation page. Select the your web server from the list. select Yes. Download the Zend Core for Oracle file from the Oracle Technology Network (http://otn. When prompted to accept the terms of the license.1-Linux-x86. Zend Core for Oracle can install Apache if you don’t have it on your system. If you want to install and configure Apache. or if you want to use an existing web server. If you have not registered.1-Linux-x86. 13.1-Linux-x86 and start the Zend Core for Oracle installation: cd ZendCoreForOracle-v2. select No. 6. 10. accept the default (or enter your preferred location). 11.0. 7.0.1-Linux-x86. 8.tar. Log in or su as root if you are not already. When prompted to specify the location for installing Zend Core for Oracle.tar. Click OK. and click OK. You may optionally enter your Zend network user ID and password to be able to use the Zend Core Console to track when updates to Zend Core and PHP components are available. 2.1-Linux-x86 . 9. and click OK. click OK. 12.Installing Zend Core for Oracle Installing Zend Core for Oracle on Linux To install Zend Core for Oracle on Linux: 1. Change directory to ZendCoreForOracle-v2.com/php). at the "Do you wish to proceed?" prompt. Confirm the password and click OK. This rest of this installation assumes that you have selected No and have in instance of Apache already installed on your machine. named ZendCoreForOracle-v2. This is the password for the webbased interface to Zend Core for Oracle.0. or do not want to track updates. Extract the contents of the downloaded Zend Core for Oracle software file. select No.oracle. Enter a password for the Administration Console.

Configure Apache to use a public virtual directory. You can also use the FastCGI or CGI options if you prefer. create a directory called public_html in your home directory. ?> 4. edit APACHE_HOME/conf/httpd. click Yes. Testing the Zend Core for Oracle Installation on Linux To test the Zend Core for Oracle installation on Linux platforms: 1. In the next installation page. 16. A page containing “Thank you for installing Zend Core for Oracle” lists useful configuration commands and the URL for the Zend Core for Oracle Administration Console. In the next installation page. 19. 18.0. Create a file called hello. Click OK. As your normal user (not root).” select Main Server. enter the following commands in a command window: cd $HOME mkdir public_html cd public_html 3. and click OK. Make sure Oracle OCI DB Drivers is selected.59. 20.conf and add a comment to the following line: #UserDir “disable” Then remove the "#" from the following line: UserDir public_html 2. and click OK. The Zend Core for Oracle installation is now complete. In the next installation page. 17. 15. a notice is displayed stating that the apachectl script has been updated. As root.php that contains the following PHP code: <?php echo "Hello world!". and click OK. 91 .Installing Zend Core for Oracle 14. In the next installation page. when you are prompted to ”Please select a virtual server for the Zend Core GUI. you are prompted to “Please select an installation method for Apache 2. Click OK to finish the installation. and change directory to the newly created directory. Make sure the permissions on any files in the public_html directory. at the “Would you like to restart the Web Server” prompt. The next installation page contains a list of extra components to install. Take note of the information and click Next. A final confirmation page is displayed. and the directories above it are set to 755 so the web server can read and execute them.” Select Apache module as the method.

In the initial Zend Core for Oracle installation page. 7. click Next. When prompted to accept the terms of the license. accept the default (or enter your preferred location).zip file extracts a file named ZendCoreforOracle-v. Log in as a system administrator. 8. select the Apache root folder.0. Double click on the file named ZendCoreforOracle-v. There is a link to the Zend site available on the Oracle Technology Network at http://otn.oracle. Select the extensions you want to associate with PHP from the check boxes and click Next. Installing Zend Core for Oracle on Windows To install Zend Core for Oracle on Windows platforms: 1.2. select the Complete installation for the default install options.com/php. select Install bundled Apache 2. you can install it now by selecting Apache 2. 4. If you have an Apache install already. click Next. When prompted to specify the location for installing Zend Core for Oracle. 92 . select Specify Apache’s location. 9. 2. 11. If you prefer. Click Next.0. Click Next.0.2. and if you do not have Apache installed yet. If you have chosen to install a new Apache server. select the port number you want Apache to listen on.2.2. 5. and click Next. 3. Click Next. On Windows platforms.php The line “Hello world!” appears in the browser.1-Windows-x86. 12. or a Custom installation.2.1/~<username>/hello.exe into the location of your choice. The installer begins extracting the files required for the installation. Any errors in your PHP code are displayed as you have configured PHP to display errors.0.1-Windows-x86. Zend Core Administration. Select Zend Core PHP and Extensions.exe to start the Zend Core for Oracle installation. The ZendCoreforOracle-v.Installing Zend Core for Oracle 5. This installation procedure assumes you select the Custom installation. Download the Zend Core for Oracle. or if you do not have Apache installed.1-Windows-x86. you can choose to perform a Complete installation. 6.0. Open a web browser and enter the following URL in your browser: http://127. If you have chosen to use an existing Apache install. 10. Extract the contents of the downloaded Zend Core for Oracle software using WinZip or similar software. or a user with system administrator privileges.

In the Zend Network Registration page. Open a web browser and enter the following URL in your browser: http://127. The final installation page is displayed confirming the installation is complete.Configuring Zend Core for Oracle 13. Any errors in your PHP code are displayed if you have configured PHP to display errors. 15. 17. Click Finish. and the release notes. you may optionally enter your Zend network user ID and password to be able to use the Zend Core Console to track when updates to Zend Core and PHP components are available. 16. Create a file called hello. Configuring Zend Core for Oracle In this section. The Zend Core for Oracle installation is now complete.php in the Apache C:\Program Files\Apache Group\Apache2\htdocs directory that contains the following PHP code: <?php echo "Hello world!".php The line “Hello world!” appears in the browser.0. 14. Click the Install button to begin the installation. A dialog is displayed giving the URL of the Zend Core Administration console.0. 1. select No. Click Next. Enter the following URL in a web browser to access the Zend Core for Oracle Administration console: http://127. ?> 2. Testing the Zend Core for Oracle Installation on Windows To test the Zend Core for Oracle installation on Windows platforms: 1. The installer runs through the installation. Enter a password for the Administration Console.0.0. If you have not registered. or do not want to track updates. you configure environment variables and Zend Core directives that control default error reporting in web pages. Click OK.1/hello. Confirm the password and click Next.1/ZendCore 93 .

94 . Click the login >>> icon. Click the Configuration tab to display the configuration options. 5. Make sure you set this back to Off before you release any applications you build as users will see the errors and gain information about your system that you otherwise don’t want them to see or know. Set the display_errors directive to On to enable the display of errors in the HTML script output during development. Click the + icon to expand the Error Handling and Logging configuration entry. 3.Installing Zend Core for Oracle Figure 7-1 Zend Core for Oracle login screen. 4. 2. Enter the GUI password that you provided during Zend Core for Oracle installation.

95 . Click Logout to exit the Zend Core for Oracle Administration page. Click Restart Server to restart the Apache server. Under the page header notice the "Please Restart Apache" message reminding you to do so. you should restart the Apache server using the Services dialog in Control Panel. Click Save Settings to save the configuration change. 6. 8. the "Unsaved configuration" message appears under the page header. 7. Because there are unsaved changes. If you are using a Windows operating system.Configuring Zend Core for Oracle Figure 7-2 Zend Core for Oracle configuration screen. you must restart the Apache web server. or the Apache Monitor in the system tray. Because you have made configuration changes.

.

$dbname). Persistent connections are not automatically closed at the end of a PHP script and remain open in PHP’s persistent connection cache for reuse in other scripts. Standard Connections For basic connection to Oracle use PHP’s oci_connect() call: $c = oci_connect($username. This can be useful when you want to do database operations independently from each other. If you do this and use the same username and database name. 97 . and tuning your connections. $password.CHAPTER 8 Connecting to Oracle Using OCI8 This section covers the ways in which you can connect to an Oracle database from your PHP application. Oracle Connection Types There are three ways to connect to an Oracle database in a PHP application. Persistent Connections Persistent connections can be made with oci_pconnect(): $c = oci_pconnect($username. $dbname). $dbname). unique connections. or persistent connections. $password. $password. including the types of Oracle connections. environment variables that may effect connections. then you get a pointer to the original connection. This makes oci_pconnect() fast for frequently used applications. Each method returns a connection “resource” that is used in subsequent OCI8 calls. using standard connections. Each connection is separate from any other. Multiple Unique Connections To get a totally independent connection use oci_new_connect(): $c = oci_new_connect($username. You can call oci_connect() more than once in a script. This lets you have more than one database session open at the same time.

This uses the Easy Connect string. 98 . Limits on the number of persistent connections in the cache can be set. The service name defaults to same name as the host computer. the character set and the connection privilege to ensure reconnections are the same as the original. and connections can be automatically expired to free up resources.Connecting to Oracle Using OCI8 Figure 8-1 Persistent connection are cached in PHP Each cache entry uses the username. which is JDBC-like. the database name.2). The syntax is: [//]hostname[:port][/service_name] The port defaults to Oracle’s standard port. and the PHP-enabled web server is on the same machine. Oracle9i and Oracle10g databases as long as PHP is linked with Oracle 10g libraries. Oracle Database Name Connection Strings The $dbname connection string is the name of the local or remote database that you want to attach to. More information on the syntax can be found in the Oracle® Database Net Services Administrator's Guide 10g Release 2 (10. 1521. The database name can be one of: * * * An Easy Connect string A full connection string A database alias Having an invalid connection string can lead to the Oracle error: ORA-12514 TNS:listener does not currently know of service requested in connect descriptor Easy Connect String If you are running Oracle XE on a machine called mymachine. The parameters for tuning persistent connections are discussed later in this chapter. This syntax is usable in Zend Core for Oracle. 'hrpwd'. you could connect to the HR schema with: $c = oci_connect('hr'. '//mymachine/XE'). The // prefix is part of the syntax and is not a PHP line comment. You can use this syntax to connect to Oracle8i.

0/server If you have compiled PHP yourself and are running it with the Oracle libraries in an ORACLE_HOME-style install. by using the full syntax. For example.mydomain)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = MYDB. you can enable Oracle Net features like load balancing and tweak packet sizes. copy the connection string used by other Oracle tools and users. $c = oci_connect($username. Instead.MYDOMAIN)))'. 99 . and there is no default file. 'MYA').MYDOMAIN))) In PHP you would use the alias MYA to connect to the database: $c = oci_connect($username. In Zend Core for Oracle. The Easy Connect syntax does not allow this flexibility. the ORACLE_HOME variable is generally not set. set the TNS_ADMIN variable in the Apache startup script to the location of your tnsnames.ora file to resolve the MYA alias.ora file will automatically be found without needing to set TNS_ADMIN.ora In Oracle XE. The directory paths that Oracle searches for tnsnames.ora and refer to it in PHP using an alias: # tnsnames. PHP needs to be able to find the tnsnames.mydomain)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = MYDB.ora is in: $ORACLE_HOME/network/admin/tnsnames.2.ora MYA = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP) (HOST = mymachine. $db). $password. When in doubt.ora. $ORACLE_HOME is: /usr/lib/oracle/xe/app/oracle/product/10. Database Alias You can store the full connection string in a file called tnsnames.ora depend on your operating system. The syntax can be more complex than the example. $password. The search path always includes the directory specified by the TNS_ADMIN environment variable and a default location.Oracle Database Name Connection Strings Full Database Connection String The full Oracle Net connection string gives total flexibility over the connection. then you would typically have ORACLE_HOME set and the default tnsnames. depending on the database and Oracle Net features used. $db = '(DESCRIPTION = (ADDRESS = (PROTOCOL = TCP) (HOST = mymachine. In an “ORACLE_HOME” style install the default tnsnames.

Not used for Oracle Instant Client.sh script: export OH=/usr/lib/oracle/xe/app/oracle/product/10. Do not set Oracle environment variables in PHP scripts with putenv(). Not used for Oracle Instant Client. The location of the tnsnames. Finding mismatched versions of Oracle libraries and files can lead to PHP returning errors such as ORA-12705: Cannot access NLS data files or invalid environment specified. $OH/bin/oracle_env. Not finding the files can lead to errors like Error while trying to retrieve text for error ORA-12154. Only needed if a database alias is used in the PHP connect function and the tnsnames.0/server . The solution for both problems is often the same: to set the environment correctly. The OCI8 extension always needs to find Oracle libraries and message files.sh 100 . or are building PHP yourself. The Oracle Net alias of the database. or OCI8 functions.2. Using putenv() causes hard to track errors as the behavior is not consistent for all web servers. you will need to set some environment variables in the shell that starts the web server. Table 8-1 Oracle Environment Variables Oracle Environment Variable ORACLE_HOME ORACLE_SID Purpose The directory containing the Oracle software. Only used when PHP is on same machine as the database and the connection string is not specified in the PHP connect function. In Oracle XE.Connecting to Oracle Using OCI8 Oracle Environment Variables for Connections If you need to change Oracle environment settings like the language and territory conventions.ora and other Oracle Net configuration files. for example $ORACLE_HOME/lib or $HOME/instantclient_10_2 Sets the globalization options for Oracle. The bottom line is that your environment should be set correctly and consistently. The common Oracle environment variables are listed in table 8-1.ora file is not in $ORACLE_HOME/network/admin. you can set the environment by using the oracle_env. Another potential source of problems is having multiple installations of Oracle. Environment variables must be set in the shell that starts Apache. platforms. LD_LIBRARY_PATH NLS_LANG TNS_ADMIN Should include the Oracle libraries. It also means that OCI8 could not find Oracle’s message files to get the text describing the error (a second problem). in this case a connection problem). This message means that an error ORA-12154 occurred (which is one problem. The web server may load Oracle libraries before running your script.

and never actually closed a connection. Any uncommitted data is rolled back. Closing Oracle Connections At the end of each script.0/server LD_LIBRARY_PATH=$LD_LIBRARY_PATH/$ORACLE_HOME/lib NLS_LANG=American_America. it modifies /usr/local/Zend/apache2/bin/envvars to add LD_LIBRARY_PATH. but you can revert to the old behavior if necessary with this php. The common Oracle environment variables you may want to set explicitly for Zend Core for Oracle are NLS_LANG and TNS_ADMIN. 101 . Make sure you preserve this file inclusion if you later modify the apachectl script. it had no functional code. check the output from the phpinfo() function. This is similar to the way persistent resources work in other PHP extensions. This command allows the script to set the environment of the shell itself. As part of the install.old_oci_close_semantics = 1 oci_close() works by reference counting. In this example $c1 and $c2 are the one database connection (because oci_connect() returns the same connection resource when called more than once in a script). Only when all references to the PHP connection are finished will the database connection actually be closed. That is. If a long running script only spends a small amount of time interacting with the database. Idle persistent connections can be set to expire. The envvars file is called by apachectl.ini setting: oci8. but only at the end of script when $c2 is closed is the database connection really released. For example: start_apache. If you have environment related problems. connections opened with oci_connect() or oci_new_connect() are automatically closed. If you start Apache manually. You could not explicitly close connections even if you wanted to! This has now changed. you may want to close connections to free resources for other users.sh #!/bin/sh ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10. The oci_close() function was a “no-op” prior to the re-factoring of OCI8.WE8ISO8859P1 export ORACLE_HOME LD_LIBRARY_PATH NLS_LANG echo Starting Apache #export > /tmp/envvars # uncomment to debug /usr/local/apache/bin/apachectl start Zend Core for Oracle is automatically configured to use Oracle Instant Client.Closing Oracle Connections Note the space after the period. Look at the Environment section and make sure the Oracle variables are set to the values you expect. Connections opened with oci_pconnect() will not be closed by oci_close(). You can also explicitly close them at any time by calling: oci_close($c). set the environment in a calling script.2.

'hrpwd'. $s = oci_parse($c. do_query($c2. 'hrpwd'. One example is the globalization setting for the date format: $c = oci_pconnect("hr". oci_execute($s). var_dump($res). The first time this is called. } $c1 = oci_connect('hr'. do_query($c. echo "<pre>". oci_fetch_all($s. $query). Connection Cleanliness with Persistent Connections Uncommitted data is rolled back at the end of a PHP script. $query) { $s = oci_parse($c. do_query($c. (The Oracle term “session” is effectively the same as the PHP term “connection”). Although the reference counting algorithm keeps the database connection physically open. oci_close($c1). "select sysdate from dual"). the second query fails. oci_close($c2). but the third succeeds. $r = oci_execute($s).Connecting to Oracle Using OCI8 close. "//localhost/XE"). do_query($c1. 'select user from dual'). "select sysdate from dual").php <?php function do_query($c. echo "</pre>". the connection resource in $c1 is not usable after oci_close($c1) is executed. However. 'select user from dual'). $c2 = oci_connect('hr'. Calling the script a second time gives: 2007-04-18 14:21:10 2007-04-18 14:21:10 102 . the two dates returned by the queries are: 18/APR/07 2007-04-18 14:21:09 The first date has the system default format. For oci_pconnect() this means subsequent scripts reusing the cached database connection will not see any data they should not. ?>7 // fails // succeeds In the example. "alter session set nls_date_format=’YYYY-MM-DD HH24:MI:SS’"). $res). do_query($c1. 'select user from dual'). The second is different because the ALTER SESSION command changed the date format. '//localhost/XE'). it is possible for a script to change session attributes for oci_pconnect() that are not reset at the end of the script. '//localhost/XE'). "hrpwd".

They can be enabled in php. to run queries and make updates. If the characters sets are not equivalent some data may get converted abnormally. "hrpwd". perform data recovery. Privileged connections are disabled by default. $c = oci_connect("hr". Your applications may never need to do anything like it. They are both created with the password that you supplied upon configuration.ini using: oci8. which will have the original default date format. When creating a database user. Optional Connection Parameters The oci_connect(). If a new Apache process serves the second request then it will open a new connection to the database. perhaps by using PHP’s mb_string or iconv functionality. and to create schema objects. ja16euc. 'ja16euc'). and even access the database when it has not fully started. The following administrative user accounts are automatically created when you install Oracle. oci_new_connect() and oci_pconnect() functions take an optional extra two parameters: * * Connection character set Connection privilege level Connection Character Set The character set is a string containing an Oracle character set name. make sure your application resets necessary values after connecting. "//localhost/XE". that is. Connection Privilege Level One of the new features of the re-factored OCI8 extension is the ability to allow privileged SYSDBA and SYSOPER connections. Be very careful about exposing this on customer facing web sites. system — This is the user account that you log in with to perform all administrative functions.) Session changes like this may not be a concern. This only happens if the same Apache process serves both HTTP requests. This setting determines how Oracle translates data when it is transferred from the database to PHP. do not do it! It might be more useful for command line PHP scripts. the NLS_LANG environment variable setting is used. other than starting up and shutting down the database. or all connections may need the same values anyway. for example.Optional Connection Parameters The persistent connection has retained the session setting and the first query no longer uses the system default format. (Also the system will have two persistent connections left open instead of one. Globalization is discussed in more detail in the Globalization chapter. It is up to your application to handle returned data correctly. When not specified or NULL.privileged_connect = 1 The SYSDBA and SYSOPER privileges give you the ability to change the state of the database. you grant privileges to enable the user to connect to the database. If there is a possibility incorrect settings will be inherited. 103 .

This is not recommended. for example. theoretically. In PHP use OCI_SYSOPER in oci_connect(). all these must be true: * * * The operating system process user is run as a member of the dba group PHP is linked with the ORACLE_HOME software (that is. null. null. Scripts that contain operating system authenticated privileged connection calls will connect successfully: $c = oci_connect("/". OCI_SYSDBA). the nobody user must be in the privileged Oracle group. not Oracle Instant Client. specified by the ORACLE_SID environment variable This would be typically be done by compiling and running PHP with the Oracle libraries used by the database. AS SYSOPER access is available for members of the oper group. Also. in the operating system dba group. the operating system groups are called ORA_DBA and ORA_OPER. Operating System Authenticated Privileged Connections You can have the operating system perform the authentication for privileged connections based around the user that is running the web server system process. By default. for example. or Zend Core for Oracle) that the database is running as The database is your default local database. a username and password must be given when connecting. On Windows. 104 . Remote Privileged Access With Zend Core for Oracle and any other PHP based on Oracle Instant Client. the library path needs to contain the same Oracle libraries. If PHP is invoked by Apache. the SYSDBA privilege is assigned only to user sys. An operating system authenticated privileged connection is equivalent to the SQL*Plus connection: $ sqlplus / as sydba In PHP for / as sysdba access (where no username and password is used). These connections are considered “remote” from the database because the libraries used by PHP are not those used by the running database. Remote users can make privileged connections only when they have been given the appropriate Oracle access. A database administrator can grant SYSDBA or SYSOPER to any user. Similarly. In SQL*Plus a privileged session would be started like: $ sqlplus username/password@sid as sysdba The database will not permit the (possibly physically) “remote” operating system to authorize access. An extra Oracle password file needs to be created and a password needs to be used in the database connection.Connecting to Oracle Using OCI8 sys — All base tables and views for the database data dictionary are stored in the sys schema and are critical for the operation of Oracle. "".

pwd \ password=secret entries=10 This creates a password file named acct. you can change the value with the SQL*Plus and enter a command similar to the following command: SQL> alter system set remote_login_passwordfile='exclusive' 2 scope=spfile sid='*'.Tuning Oracle Connections in PHP To set up a password file. This is the default value. and by tuning the database. log in to the operating system shell as the Oracle database software owner. null. To do this.-----. USERNAME SYSDBA SYSOPER -----------------------------.----------. and start SQL*Plus: $ sqlplus / as sysdba SQL> show parameter remote_login_passwordfile NAME TYPE VALUE ----------------------------. Tuning Oracle Connections in PHP Connections to Oracle can be tuned by changing the OCI8 calls made. "c1pw". create an Oracle password file: $ $ORACLE_HOME/bin/orapwd file=$ORACLE_HOME/dbs/acct. '//localhost/XE'. and not just as sys. any OCI_SYSDBA connection will show the user as sys not c1. A connection made with OCI_SYSOPER will show a user of public. From the operating system shell. 105 . SQL> grant sysdba to c1. check the database initialization parameter remote_login_passwordfile is EXCLUSIVE.pwd that allows up to 10 privileged users with different passwords (this number can be changed later).------SYS TRUE TRUE C1 TRUE FALSE Now in PHP you can use the following connection string: $c = oci_connect("c1". The file is initially created with the password secret for users connecting with the username sys. One feature of a privileged connection is that if you issue a SELECT USER FROM DUAL statement. If this parameter is not set to EXCLUSIVE. SQL> grant connect to c1. by changing the network configuration.-----------remote_login_passwordfile string EXCLUSIVE EXCLUSIVE means the password file is only used with one database and not shared among several databases on the host. OCI_SYSDBA). To add a new user to the password file use SQL*Plus: SQL> create user c1 identified by c1pw. SQL> select * from v$pwfile_users. and enables you to have multiple users connect to the database as themselves.

$db) { $c = oci_pconnect($un. "hrpwd". When oci_connect() is called multiple times in the one script or when persistent connections are used. This may involve a potentially expensive environment lookup. Pass the Character Set Explicitly passing the client character set name as the fourth parameter to the connection functions improves performance: $c = oci_connect("hr". Using a trigger means the date format is only set when the physical database connection is created the first time. Do Not Set the Date Format Unnecessarily You can often remove ALTER SESSION statements used after connecting. "//localhost/XE". For example. consider tuning the timeout parameters or using oci_connect(). Sometimes different database users should have different session values so setting NLS_DATE_FORMAT globally is not possible. A new. $db). The trigger does not fire when subsequent connect calls return a cached connection. A logon trigger can be created using SQL*Plus by connecting as a privileged database user: $ sqlplus system/systempwd@//localhost/XE 106 . open persistent connections consume too much memory on the database server. the ALTER SESSION can be moved to a logon trigger. return $c. by choosing the best connection function. passing the character set on connection. if your connection routine always sets the date format: function my_connect($un. physical connection to the database does not have to be created if one already exists in PHP’s cache. } One way to optimize this is to simply set the environment variable NLS_DATE_FORMAT in the shell that starts the web server. $pw. PHP has to determine which client character set to use. However if currently unused. oci_execute($s). Use the Best Connection Function Using oci_pconnect() makes a big improvement in overall connection speed of frequently used applications because it uses the connection cache in PHP. $pw. 'ja16euc'). If you do not enter a character set and use the default. and optimizing common connection steps.Connecting to Oracle Using OCI8 Connection Decisions There are a number of ways you can improve the performance of the PHP to Oracle connections. Each PHP connection will have the required date format automatically. This is because session settings are retained in cached connections. "alter session set nls_date_format='YYYY-MM-DD HH24:MI:SS'"). $s = oci_parse($c.

each of them may have its own set of 107 . '//localhost/XE'). instead of multiple calls to execute ALTER SESSION statements. If you cannot use a trigger because each PHP invocation needs different settings. return $c. 'hrpwd'.Tuning Oracle Connections in PHP SQL> 2 3 4 5 6 7 8 create or replace trigger my_set_date after logon on database begin if (user = 'HR') then execute immediate 'alter session set nls_date_format = ''YYYY-MM-DD HH24:MI:SS'' '. And if Apache spawns a number of server processes. end my_set_date. the connection function can simply become: function my_connect($un. / Trigger created. What you consider high depends on your application requirements and on implementation issues such as whether the web server and database are on the same host. $pw. Tuning Persistent Connections Persistent connections are great if the cost of opening a connection is high. The date format string is enclosed in a pair of two quotes. echo $row['SYSDATE'] . Note the use of single quotes. The drawback is the connection uses Oracle resources even when no one is accessing the application or database. $s = oci_parse($c. and you need more than one session value changed. $row = oci_fetch_array($s). After connecting you can call the PL/SQL procedure. $c = my_connect('hr'. end if. This trigger sets the session’s date format every time hr connects to the database from any client tool. oci_execute($s). } Oracle does all the work setting the date format when the physical database connection is originally established and first used. This connects as hr and queries the current date. which is one oci_execute() call to the database. "\n". It shows the new format set by the trigger: 2007-05-04 13:50:35 If the connection is any user other than hr the standard default date format will be displayed: 04-MAY-07 Using a trigger like this only works when the required session setting is the same for all PHP application users that share the same database user name. In PHP. you can put the statements inside a PL/SQL procedure. $db). When PHP later uses a cached connection it will already have the desired date format. which is the Oracle method of nesting single quotes inside a quoted string. $pw. $db) { $c = oci_pconnect($un. 'select sysdate from dual').

all oci_pconnect() calls are treated like oci_connect() calls and are closed at the end of the script. The database administrator may have installed user profiles with CREATE PROFILE IDLE_TIMEOUT. or being timed out. oci_pconnect() will always check an Oracle client-side setting to see if the server was known to be available the last time anything was received from the server. The default value is 60 seconds. for example in oci_execute(). When the limit is reached. Good application design gracefully recovers from failures.ping_interval = 60 This parameter is the number of seconds that pass before OCI8 does a ping during oci_pconnect(). The ping interval is an easy way to improve connection reliability for persistent connections.ping_interval.ini directives. a new connection is transparently created and returned by oci_pconnect().max_persistent = -1 This parameter limits the number of persistent connections cached by each Apache process. Timeout for Unused Persistent Connections oci8. oci8.Connecting to Oracle Using OCI8 connections to the database. causing a “round-trip” over the network. or the Oracle network layer may time out the network.persistent_timeout = -1 This parameter is the length in seconds that an Apache process maintains an idle persistent connection. If the ping determines the connection is no longer usable. To disable pinging. the next time oci_pconnect() is called a new connection is created. If a connection has been expired. You need to balance performance (no pings) with having to handle disconnected Oracle sessions (or other changes in the Oracle environment) in your PHP code. Setting oci8. When set to 0. During the time PHP stored an unaccessed connection resource in its cache. In any application there are a number of potential points of failure including the network. This is a quick operation. a database error. Oracle itself may be configured to close idle connections and release their database resources. The proliferation of connections can be controlled with php. PHP checks the database each time oci_pconnect() is called. Setting this parameter to -1 (the default) means there is no timeout. For highest 108 .ping_interval additionally physically sends a message to the server. Pinging for Closed Persistent Connections There is no guarantee that the connection descriptor returned by oci_pconnect() represents a usable connection to the database. This is a bad thing for scalability. the hardware and user actions such as shutting down the database. The expiry check happens whenever a PHP script finishes regardless of whether the script calls OCI8 functions. oci_pconnect() appears to be successful but an error is thrown when the connection is later used. the connection to the database may have become unusable due to a network error. set the value to -1. If this happens. Setting it to -1 (the default) means there is no limit. Regardless of the value of oci8. Maximum Number of Persistent Connections Allowed oci8.

In SQL*Plus the connection: $ sqlplus hr/hr@abc Would be the same. The issue is not specific to PHP. This depends on your Oracle Net and DNS settings. How Oracle is configured to authenticate the user’s credentials (here a username and password) can also have an effect. Both internal connection methods may be tried in sequence adding to the time delay before a PHP script gets the error. which will also free up Oracle resources used by persistent connections.ini directives work in harmony with your Apache settings and your timeouts happen predictably. For example a connection: $c = oci_connect("hr". Apache Configuration Parameters You can also tune Apache to kill idle processes.ora file.DIRECTORY_PATH = (TNSNAMES) SQLNET. "abc"). Defines whether Apache can serve a number of documents to the one user over the same HTTP connection. Sets how many servers to keep in memory that are not handling requests. John Coggeshall’s article Improving Performance Through Persistent Connections discusses Apache configuration in more depth. Ideally your php. "hrpwd". but do error recovery in your application code. Tuning Oracle Net There are many ways to configure connection and authentication. one way to return an error as soon as possible is to set this in your client sqlnet.AUTHENTICATION_SERVICES = (NONE) 109 .Tuning Oracle Connections in PHP reliability and scalability it is generally recommended that you do not use oci8. Could be evaluated by Oracle10g as using the Easy Connect syntax to host machine abc (using the default port and database service) or using a net alias abc configured in a tnsnames.ping_interval. In a basic Oracle10g installation. The flexibility can cause a delay in getting an error back if the connection details are invalid or a database is not operational.ora file: NAMES. Table 8-2 Apache configuration parameters Parameter MaxRequestsPerChild MaxSpareServers KeepAlive Purpose Sets how many requests Apache will serve before restarting. Table 8-2 lists the Apache configuration parameters that can be used to tune PHP.

The sample sqlnet. might be beneficial. but one to be used with caution. The sqlnet.Connecting to Oracle Using OCI8 The DIRECTORY_PATH value disables Easy Connect’s //hostname:port/service syntax. [10-MAY-2006 09:55:00:854] snlinGetAddrInfo: Name resolution failed for #c .ora: trace_level_client = USER trace_directory_client = /tmp And the PHP code: $c = oci_connect("hr". The drawback is greatly reduced reliability. Database resource usage of a large number of connections is potentially more likely to be significant than network consumption. If you are not using a tnsnames. You may also be able to tune your TCP/IP stack. Check the Oracle Net documentation for details and for other authentication methods and authentication-type specific timeout parameters. [10-MAY-2006 09:54:58:100] nnftmlf_make_system_addrfile: system names file is .trc..ora and use a network alias.) Setting AUTHENTICATION_SERVICES to NONE stops different authentication methods being tried.ora file.. If network consumption is an issue.ora file and see where time is being spent. set the environment variable TNS_ADMIN to the directory that contains the sqlnet. again. including the session data unit size.. For example. Other Oracle Net Optimizations Oracle Net lets you tune a lot of other options too. Check the Oracle Net Services Administrator’s Guide and the Oracle Net Services Reference for details of all the wonderful variety of Oracle Net options available.. Oracle Net’s Connection Pooling and Session Multiplexing features should be evaluated. for example /tmp/cli_3232. you can tune the QUEUESIZE option in the listener. 110 . For sites that have a large number of connections being made. // invalid db name The trace file. create a tnsnames. This removes the need to do a hostname lookup. It stops users guessing database server hostnames they should not know about. "hrpwd". shows: . turn on Oracle Net tracing in your client sqlnet. Tracing Oracle Net Sometimes your network is the bottleneck. with a USER level trace in sqlnet. "#c"). Although this may prevent privileged database connections.ora file..ora file.ora file. If you suspect this is the case.ora file. this. The benefit may be small on platforms that cache the IP address well.ora in $ORACLE_HOME/network/admin/sample has some notes on the parameters that help. which require operating system authorization.ora file should be on the machine running Apache and in the same directory as your tnsnames. (This may also add a small measure of security if your scripts accidentally allow arbitrary connection strings. is to hardcode the database host IP address in the tnsnames. Another potential Oracle Net optimization. Instead of using Easy Connect syntax..

ora parameter PREFER_LEAST_LOADED_NODE_<listener_name> to OFF to use session based load balancing. the DBMS_SERVICE package lets you specify workload management goals. sys. A starting point is to change it to perhaps 10000: SQL> alter sequence sys. This difference means care is required when designing scalable applications. For both RAC and non-RAC database. make sure that your applications are as efficient as possible. Set the listener.ini parameters to expire persistent connections. This is also recommended if you are using Oracle RAC (“Real Application Clusters”). Each connection will take some Oracle memory. Large sites should benchmark persistent PHP connections and Oracle Shared Servers also known as “Multi Threaded Servers” (MTS). it shows a relatively big time delay doing name resolution for the non-existent host #c. The cause is the configuration of the machine network name resolution. For sites with hundreds of connections a second.audses$. Using persistent connections is common for web sites that have high numbers of connections being established.Tuning Oracle Connections in PHP The left hand column is the timestamp of each low level call. 111 .audses$ cache 10000.1 on Oracle’s Metalink support site: Session based load balancing takes into account the number of sessions connected to each node and then distributes new connections to balance the number of sessions across the different nodes This can help when there is a connection “storm” and the normal allocation metrics do not get a chance to get updated fast enough. This is documented in Note 220970. Connection Management in Scalable Systems Oracle achieves its well-known scalability in part through a multi-threaded architecture. Finally. Make sure that you understand the lifetime of your applications connections. so overall load can be reduced if idle connections are closed with Apache process timeouts or with the php. Shared Servers reduce the numbers of processes needed to handle database requests. This is a detailed topic. With Oracle RAC you can adjust the algorithm that decides which Oracle node handles each new connection. PHP instead has a multi-process architecture. refer to Oracle’s manuals for more information. This minimizes the length of time connections are held. tune the cache size of an internal sequence generator. Here. but don’t be afraid to create new connections and close them as needed. Reuse connections where possible. Reusing a previously opened connection is significantly faster than opening a fresh one.

.

php <?php $c = oci_connect("hr". oci_execute($s). for better performance and security. The possible steps are: 1.CHAPTER 9 Executing SQL Statements With OCI8 This chapter discusses executing SQL statements using the Oracle OCI8 extension. the functions available. This improves performance and security. postal_code from locations'). execute and fetch. 'select city. in the WHERE clause. You can also “define” where you want the results to be stored. since Oracle’s actual text parse can occur at the execution stage. Statements like CREATE and INSERT require only parsing and executing. Fetch ― Gets any query results back from the database. Execute ― The database processes the statement and buffers any results. 3. Query Example A basic query in OCI8 is: query. 113 . "//localhost/XE"). but almost all scripts let the OCI8 fetch functions take care of this. for example. Parse ― Prepares a statement for execution. "hrpwd". Parsing is really just a preparatory step. 4. 5. Define ― Optional step allowing you to specify which PHP variables will hold the results. including how statements are executed. $s = oci_parse($c. and some tips and tricks that you might find useful in your applications. You can optionally “bind” local values into a statement similar to the way you use %s print format specifications in strings. SQL Statement Execution Steps Queries using the OCI8 extension follow a model familiar in the Oracle world: parse. 2. transactions. There is no one-stop function to do all these steps in a single PHP call. This is not commonly used. Bind ― Optionally lets you bind data values. but it is trivial to create one in your application and you can then add custom error handling requirements. tuning your queries.

oci_close($c).php In PHP.$item. "select * from locations where city = 'Sydney'").Executing SQL Statements With OCI8 print '<table border="1">'. it is fully enclosed in double quotes: $s = oci_parse($c. OCI_RETURN_NULLS)) { print '<tr>'.'</td>'. To make the query a PHP string. foreach ($row as $item) print '<td>'. The common built-in Oracle datatypes are: * * CHAR VARCHAR2 114 . print '</tr>'. } print '</table>'.php is: Figure 9-1 Output from query. Strings with embedded quotes can be made by escaping the nested quotes with a backslash. or by using both quoting styles. while ($row = oci_fetch_array($s. Oracle Datatypes Each column has a datatype. single and double quotes are used for strings. ?> The output from the script query. The next example shows single quotes around the city name. which is associated with a specific storage format.

Some of the functions have optional parameters that alter their behavior. Gets a new row as an object. Table 9-2 fetch_array() options. Used with oci_result(). Table 9-1 OCI8 fetch functions OCI8 Function oci_fetch_all() oci_fetch_array() oci_fetch_assoc() oci_fetch_object() oci_fetch_row() oci_fetch() Purpose Gets all the results at once. for table 9-2 lists the oci_fetch_array() options. VARCHAR2. NUMBER.Fetch Functions * * * * * * * NCHAR and NVARCHAR2 NUMBER DATE BLOB CLOB and NCLOB BFILE XMLType The CHAR. CLOB. BLOB. Gets the next row as an associative array. which returns the result of a given field. all carefully documented in the PHP OCI8 Reference Manual. Gets the next row as an array of your choice. Fetch Functions There are a number of fetch functions. and BFILE datatypes use PHP descriptors and are shown in the Using Large Objects in OCI8 chapter. and DATE datatypes are stored directly in PHP variables. and NCLOB are not supported in the OCI8 extension. 115 . NVARCHAR2. Parameter OCI_ASSOC OCI_NUM OCI_BOTH Purpose Return results as an associative array. NCHAR. Return results as both associative and numeric arrays. Gets the next row as an integer indexed array. Return results as a numerically indexed array. XMLTypes are returned as strings. Table 9-1 lists the OCI8 fetch functions.

$s = oci_parse($c. regions. . postal_code from locations")."<br>\n". country_name.. oci_execute($s). . "<br>\n".00989 Venice .". In an associative array there is no table prefix for the column name. "select region_name.region_id as myreg. " .Executing SQL Statements With OCI8 Parameter OCI_RETURN_NULLS OCI_RETURN_LOBS Purpose Return PHP NULL value for NULL data. while ($res = oci_fetch_array($s. Associative arrays are keyed by the uppercase column name. } This displays: 00989 10934 1689 6823 26192 . OCI_NUM)) { echo $res[0] . Return the actual LOB data instead of an OCI. If you join tables where the same column name occurs with different meanings in both tables.region_id 116 . countries. Refer to the chapter Globalization for more information.LOB resource. "select postal_code from locations"). "select city.$res[1].6823 Southlake – 26192 .1689 Hiroshima .. use a column alias in the query. Note: Numbers and dates are fetched as strings and the Oracle globalization settings may affect their formatting. oci_execute($s).10934 Tokyo . while ($res = oci_fetch_array($s)) { echo $res["POSTAL_CODE"] . Otherwise only one of the similarly named columns will be returned by PHP: $s = oci_parse($c. } This displays: Roma . A basic example to fetch results in a numerically indexed PHP array is: $s = oci_parse($c.

simply requires a parse and execute: $s = oci_parse($c1. "create table i1test (col1 number)"). " " . Except in special cases.Argentina 2 Australia 3 . OCI_NUM+OCI_RETURN_NULLS). or specify the OCI_RETURN_NULLS flag: $res = oci_fetch_array($s. OCI8’s default commit behavior is like other PHP extensions and different from Oracle’s standard. Use inline views. oci_execute($s). Create and Drop Executing Data Definition Language (DDL) and Data Manipulation Language (DML) statements. Insert. Create and Drop from countries inner join regions on countries.Insert.Brazil 2 2 .region_id = regions. " " . . The result array can appear to have fewer columns than selected. . Tom Kyte talks about global temporary tables on http://asktom. while ($res = oci_fetch_array($s)) { echo $res["REGION_NAME"] . oci_execute($s). like CREATE and INSERT. " " . Update." . Update.Belgium 1 2 . Applications in Oracle do not commonly need to create temporary tables at run time. or join tables when required. Transactions Using transactions to protect the integrity of data is as important in PHP as any other relational database application. 117 .com/.Canada 2 Some of the fetch functions do not return NULL data by default.oracle. or none of them. $res["COUNTRY_NAME"] . 2 . } The query column alias MYREG is used as the index to the result array. Delete. At the end of a script any uncommitted changes are automatically rolled back. Temporary tables are expensive to create and have no statistics for the Oracle optimizer to evaluate. $res["REGION_ID"] . "<br>\n". and you can’t always tell which column was NULL. The script output is: Americas Asia 3 Europe 1 Americas Americas . The default mode of oci_execute() is OCI_COMMIT_ON_SUCCESS to commit changes. $res["MYREG"] . This can be tricky when using numerically indexed arrays. The only-run-once installation sections of applications should contain almost all the CREATE TABLE statements used. Either use associative arrays so the column names are directly associated with their values. Delete. you want either all your changes to be committed. " .region_id").

but transactional and performance requirements should be thought about before using the default mode everywhere. You specify not to auto-commit and begin a transaction with: $s = oci_parse($c. OCI_DEFAULT). Be careful mixing and matching oci_execute() calls with both commit modes in one script. To rollback. but we are stuck with the awkward usage. 118 . do: oci_commit($c). "insert into testtable values ('my data')"). where the value of the C macro with the same name is actually the default value when nothing else is specified. oci_execute($s). // automatically committed This can be handy for single INSERTs and UPDATEs.Executing SQL Statements With OCI8 In the following example the changes are committed immediately when the oci_execute() call is called: $s = oci_parse($c. To maximize efficiency. since you may end up auto-committing and later also unnecessarily explicitly committing. or you may simply commit at incorrect times. // not committed The PHP parameter name OCI_DEFAULT is borrowed from Oracle’s Call Interface. Transactions are automatically rolled back when you close the connection or at the end of the script. oci_execute($s. Figure 9-2 Each round trip between PHP and the Database reduces scalability It is also causes extra processing and more IO to the database files. "insert into testtest values ('my data 2')"). do: oci_rollback($c). Unnecessarily committing or rolling back impacts database performance as it causes unnecessary network traffic (“round trips”) between PHP and the database. use transactions where appropriate. Benchmarking and testing your applications in your environment is wise. In PHP a better name would have been NO_AUTO_COMMIT. To commit any un-committed transactions for your connection.

"//localhost/XE"). allows you to do autonomous transactions. An autonomous transaction can be committed or rolled back without affecting the main transaction. use SQL*Plus to create a table with a single date column: SQL> create table mytable (col1 date). This might be useful for logging data access. $res). oci_execute($s. changing oci_connect() to oci_new_connect() and oci_pconnect(): transactions. NAME -----------------------------Fred You could call the PL/SQL function from PHP to log access. PL/SQL.php <?php function do_query($c. var_dump($res).Transactions Autonomous Transactions Oracle’s procedural language for SQL. Rerun this script a few times. OCI_DEFAULT). } $c1 = oci_connect("hr". echo "</pre>". execute updatelog('Fred’). / SQL> SQL> SQL> SQL> insert into logtable values ('Sally'). SQL> create or replace procedure updatelog(name_p in varchar2) as pragma autonomous_transaction. $query) { $s = oci_parse($c. An example is: SQL> create table logtable (name varchar2(30)). select name from logtable. begin insert into logtable (name) values(name_p). echo "<pre>". which are effectively sub-transactions. "hrpwd". commit. rollback. end. An audit record can be inserted even if the user decides to rollback their main change. The Transactional Behavior of Connections To see the transactional behavior of the three connection functions. oci_fetch_all($s. 119 . $query).

"hrpwd". Expect the unexpected. Using oci_pconnect() is the same as oci_connect(). To handle errors in OCI8. "select * from mytable"). For connection errors. no argument is needed: $c = oci_connect("hr". do_query($c2.Executing SQL Statements With OCI8 $s = oci_parse($c1. "')"). in a production system you would turn off display_errors in php.ini so you can catch any problems that will cause upgrade issues. Check all return codes.php Handling OCI8 Errors The error handing of any solid application adds complexity and requires careful design. For development. "//localhost/XE"). // No COMMIT occurs do_query($c1. "select * from mytable"). "insert into mytable values ('" . and you do not want your application pages to contain ugly error messages. // No parameter passed 120 . OCI_DEFAULT). Figure 9-3 Output from transactions.ini. date('j:M:y') . Using oci_new_connect() for $c2 gives a new connection which cannot see the uncommitted data. enable the E_STRICT level for error_reporting in php. ?> Using oci_connect() connection lets you query the newly inserted (but uncommitted) data because $c1 and $c2 refer to the same Oracle connection. using the oci_error() function. For a start. $c2 = oci_connect("hr". "hrpwd". if (!$c) { $e = oci_error(). $r = oci_execute($s. You do not want to leak internal information to web users. "//localhost/XE").

pass the connection resource: $s = oci_parse($c. // Statement handle passed var_dump($e). if (!$rc) { $e = oci_error($s). using PHP’s output buffering functions may be a way to help hide errors from users. if (isset($err['message'])) { echo htmlspecialchars($err['message']). } For execution and fetching errors."\n". // Connection handle passed var_dump($e). $pw. if (!$con) { DisplayOCIError(). "select city from locations"). For pretty output. } $rc = oci_fetch_all($s. $con = @oci_connect($un. if (!$rc) { $e = oci_error($s). $un. $db). $db) { ob_start(). pass the statement resource: $rc = oci_execute($s). // Statement handle passed var_dump($e). } ob_end_clean(). if (!$s) { $e = oci_error($c). } echo '</pre>'. return($con). } For parse errors. else $err = @oci_error(). function Connect(&$e. echo "<pre>\n". echo "<p><b>Error</b>:</p>\n". $e = ob_get_contents(). } else { echo 'Unknown DB error'. $pw. $results). } You might consider using PHP’s @ to suppress function errors.Handling OCI8 Errors var_dump($e). 121 . } function DisplayOCIError($r = false) { if ($r) $err = @oci_error($r).

On the OCI8 side. Efficient caching of statements by having reusable code and using bind variables are fundamental in improving database performance. It can improve overall database throughput. SQL tuning will help make efficient use of table design. They let you re-execute a statement with different values for the variables and get different results. If you do not bind. Using Bind Variables Bind variables are just like %s print format specifiers. Oracle is more likely to find the matching statement in its cache and be able to reuse the execution plan and context for that statement. Consider using PL/SQL packages for complex data operations to minimize data transfers. next tune the SQL. Oracle must reparse and cache multiple statements. Database tuning maximizes throughput and allows efficient use of buffering and I/O strategies. 122 .Executing SQL Statements With OCI8 } Tuning SQL Statements in PHP Applications Tuning is an art and a science. Figure 9-4 Not binding wastes database resources Binding is highly recommended. It is almost always more efficient to select the minimum amount of data necessary and only return rows and columns that will be used by PHP. and finally tune the database. transaction management can help reduce round trips from PHP to the database. The database-centric approach to tuning is to first tune the application. even if someone else originally executed it. SQL tuning and Database tuning are covered in the Oracle documentation. indexes and the Oracle optimizer.

SQL injection may occur when SQL statements are hard coded text concatenated with user input: $s = oci_parse($c. // No need to re-parse $myeid = 102. User data is always treated as data and never as part of the SQL statement. Bind variables give a high level of automatic protection against SQL injection attacks and you do not need to resort to workarounds. Do not do this. It may even cause you problems. A lot of the older documentation uses & in calls to oci_bind_by_name()."<br>\n". "select ". $res). echo "Last name is: ". this syntax has been deprecated. then it may be possible for a malicious user to execute a SQL statement of their choice instead of the one you intended. "select last_name from employees where employee_id = :eidbv"). there are also OUT binds that return values. $myeid = 101. extra functionality was added to PHP in an attempt to work around this kind of problem. $myeid). One of the notorious features is “magic quotes”. which pass data into Oracle. These are mostly used to return values from PL/SQL procedures and functions. $res['LAST_NAME'][0] . As well as IN binds. $s = oci_parse($c. oci_execute($s)."<br>\n". ":EIDBV". If the user input is not carefully checked. The bind data needs to be accessible when oci_execute() is called. Using a local variable in a sub function may cause a scope problem. $res['LAST_NAME'][0] . oci_fetch_all($s. If the 123 . which will go away in PHP 6 because of the confusion caused. Over the years.$col. echo "Last name is: "." from mytable").Tuning SQL Statements in PHP Applications Figure 9-5 Binding improves performance and security Bind variables are also an important way to prevent SQL injection security attacks. oci_execute($s). $res). oci_bind_by_name($s. Since the recent PHP call-by-reference clean up. oci_fetch_all($s.

When pre-fetching is enabled. you need to specify the otherwise optional length parameter. the optimizer does not have any information about the value you may eventually use when the statement is executed. Testing will show the optimal size. numbers are converted to and from strings when they are bound. The default value is 10.default_prefetch bytes. It minimizes database server “round-trips” by returning as much data as possible each time. Subsequent OCI8 fetches will consume the data in the cache until eventually another batch of records is fetched from the database. the database will return the specified number of rows to a cache in its client buffers and give PHP only the row (or rows) the OCI8 function call requested. When queries contain bind variables. Prefetching is similar to an “array fetch”. Another case when the length should be specified is when returning numbers. Figure 9-6 Each individual request to the database returns a number of rows to a cache You can also change the value at runtime with the oci_set_prefetch() function: 124 . There is one case where you might decide not to use bind variables. This mostly used for binding LOBS and result sets as shown in a later chapter. 10). which is the datatype. But if the data is derived from user input be sure to sanitize it. This means the length parameter should also be passed to OCIBindByName() when returning a number: oci_bind_by_name($s. you might want to hard code values. There is no benefit using too large a prefetch value. “:MB”.default_prefetch = 10 This parameter sets the number of records to be returned by the database when each fetch occurs. $mb. but Oracle handles the caching. The OCI8 extension also caps the memory used by the prefetch buffer at 1024 * oci8. Increasing the prefetch value can significantly improve performance of queries that return a large number of rows. There is also an optional fifth parameter. Default Prefetch Size You can tune PHP’s overall query performance with two configuration parameters: oci8.Executing SQL Statements With OCI8 PHP variable associated with an OUT bind does not exist. If your data is highly skewed. By default in OCI8.

there is a time/memory trade-off when tweaking this parameter. 125 .ini directive: oci8. The statement cache also means slightly more load is put on the PHP host. Caching can be disabled by setting the value to 0.default_prefetch $res = oci_fetch_array($s). oci_execute($s).Limiting Rows and Creating Paged Datasets $s = oci_parse($c. oci_set_prefetch($s. Limiting Rows and Creating Paged Datasets Oracle’s SQL does not have a LIMIT keyword. Like many tuning options. not by Oracle’s native functionality. This is implemented by the extension. "select city from locations"). There are several ways to limit the rows returned in OCI8. Figure 9-7 The second time a statement is issued the statement text does not need to be sent to the server The cache is per-Oracle session so this feature is most likely to be useful when persistent connections are used. further reducing network traffic and database server load. The client-side statement cache is in addition to the standard database statement cache. // 10 is default oci8. The oci_fetch_all() function has optional arguments to specify a range of results to fetch. 100). The client cache means even the text of the statement does not need to be transmitted to the database more than once. Default Statement Cache Size You can set a client cache for SQL statement text with the php. All rows preceding those you want still have to be fetched from the database. The database can directly look up the statement in its cache without having to parse the statement. It is not in the SQL standard and the vendors that use it have different implementations.statement_cache_size = 20 The default is 20 statements. offsetting the reduced load on the database host.

oci_fetch_all($s. oci_execute($s). Bind data is not treated as code. oci_fetch_all($s. oci_bind_by_name($s. $res).com: select * from ( select a. $s = oci_parse($c. $firstrow. $res. rownum as rnum from (YOUR_QUERY_GOES_HERE -. ?> Note that $mystmt is not bound. so you cannot bind the text of the statement and expect it to be executed. $pagesql). $minrow = 4. The canonical paging query for Oracle8i onwards is given on http://asktom. var_dump($res). ":maxrow".*. oci_bind_by_name($s. $minrow). $maxrow). rownum as rnum from ( $mystmt ) a where rownum <= :maxrow) where rnum >= :minrow".Executing SQL Statements With OCI8 $firstrow = 3. $numrows).oracle. In PHP you might do this: <?php $mystmt = "select city from locations order by city".including the order by) a where rownum <= MAX_ROWS ) where rnum >= MIN_ROWS MIN_ROWS is the row number of first row and MAX_ROWS is the row number of the last row to return. The output of the script is: array(2) { ["CITY"]=> array(5) { [0]=> string(6) "Geneva" [1]=> string(9) "Hiroshima" [2]=> string(6) "London" [3]=> string(11) "Mexico City" 126 . oci_execute($s). var_dump($res). // row number of first row to return $maxrow = 8. $numrows = 5. It is more efficient to let Oracle do the row selection. // row number of last row to return $pagesql = "select * from ( select a. ":minrow".*.

ROW_NUMBER() OVER (ORDER BY last_name) AS MYR FROM employees) WHERE MYR BETWEEN 11 and 20 In SQL*Plus the output is: LAST_NAME ------------------------Bissot Bloom Bull Cabrio Cambrault Cambrault Chen Chung Colmenares Davies 127 . . By turning this into a subquery and using a WHERE condition any range of names can be queried. For example to get the 11th to 20th names the query is: SELECT last_name FROM (SELECT last_name. .---------Abel 1 Ande 2 Atkinson 3 . The query: SELECT last_name.Limiting Rows and Creating Paged Datasets [4]=> string(6) "Munich" } ["RNUM"]=> array(5) { [0]=> string(1) [1]=> string(1) [2]=> string(1) [3]=> string(1) [4]=> string(1) } } "4" "5" "6" "7" "8" An alternative query syntax uses Oracle’s analytic ROW_NUMBER() function. ROW_NUMBER() OVER (ORDER BY last_name) AS myr FROM employees Returns two columns identifying the last name with its row number: LAST_NAME MYR ------------------------.

Executing SQL Statements With OCI8 Auto-Increment Columns Auto increment columns in Oracle can be created using a sequence generator and a trigger. This gives the next available number and increments the generator. SQL> SELECT myseq. mydata VARCHAR2(20)).myid FROM DUAL. Sequence generation is useful to generate unique primary keys for your data and to coordinate keys across multiple tables. Sequence numbers are generated independently of tables. the same sequence generator can be used for more than one table or anywhere that you want to use a unique number. A sequence generator returns unique values when it is called. In SQL*Plus a sequence can be created and called like: SQL> CREATE SEQUENCE myseq. / In PHP insert two rows: $s = oci_parse($c. MYID ---------2 3 MYDATA -------------------Hello Bye The identifier numbers start at 2 because the example query shown above when the sequence was created returned 1 and incremented the generator. Therefore. The similar CURRVAL operator returns the current value of a sequence without incrementing the generator. NEXTVAL ---------1 To create an auto-increment column on a table SQL> CREATE TABLE mytable (myid number. Sequence generators are defined in the database and return Oracle numbers. END. SQL> CREATE TRIGGER mytrigger BEFORE INSERT ON mytable FOR EACH ROW BEGIN SELECT myseq. You can get a new value from a sequence generator using the NEXTVAL operator in a SQL statement. oci_execute($s). A trigger is a PL/SQL procedure that is automatically invoked at a pre-determined point. "insert into mytable (mydata) values ('Bye')”).nextval INTO :new.nextval FROM dual. Querying the table in SQL*Plus shows the MYID values were automatically inserted: SQL> select * from mytable. Together they can automatically insert incrementing identifiers when table rows are created. "insert into mytable (mydata) values ('Hello')”). 128 . oci_execute($s). $s = oci_parse($c.

'^Ste(v|ph)en$'). Analytic Functions in SQL Oracle’s Analytic functions are a useful tool to compute aggregate values based on a group of rows. since it depends on table data not available to hr: select max_extents. You must be connected as the system user in this particular example. The following query gets both spellings of Stephen: select first_name. Here is an example of a correlation. corr(max_trans.Exploring SQL Exploring SQL Explore the SQL and PL/SQL languages.oracle. Some examples of useful database features are regular expressions and analytic functions. Regular Expressions in SQL Regular expressions were first introduced in Oracle 10g Release 10. Make maximum reuse of functionality that already exists. Keeping a thin interface between your application layer and the database is also good programming practice. autonomous transactions and spatial functionality are left for you to investigate further. Many more features including. CORR() returns the coefficient of correlation of a set of number pairs. last_name from employees where regexp_like(first_name. 129 . has a lot of very useful information. and extended in Release 10. Data is a core asset of your business. http://asktom. Avoid shipping data from the database to PHP for unnecessary post processing.2. Other analytic functions allow you to get basic information like standard deviations or do tasks such as ranking (for Top-N or Bottom-N queries) or do linear regressions. initial_extent) from all_tables group by max_extents. Oracle’s regular expressions conform to POSIX regular expression standard and the Unicode Regular Expression Guidelines. Tom Kyte’s popular site.1. Oracle’s general guideline is to let the database manage data and to transfer the minimum amount across the network. It should be treated consistently across your applications.com.

.

put_line('Salary is ' || sal_l). You can create stored procedures.. END) An exception-handling (EXCEPTION) part that handles error conditions For example: declare sal_l pls_integer. all your Oracle applications in any tool or client language can reuse the functionality. end. job scheduling and TCP access. stored procedural language that is easy-to-use. You can run this in many tools. Packages exist for full text indexing. for example to make sure your financial data is not affected by PHP’s floating point semantics. the cost of data transfer across the network and the re-usability of the code. including PHP. just to name a few. such as data change triggers.. and can use it to efficiently insert and fetch data. A PL/SQL block has three basic parts: * * * A declarative part (DECLARE) An executable part (BEGIN . consider your skill levels in the languages. PL/SQL enables you to mix SQL statements with procedural constructs. It is a server-side. PHP can call PL/SQL blocks to make use of advanced database functionality. Some functionality should only ever be in the database. begin select salary into sal_l from employees where employee_id = 191. When deciding whether to write PHP on the client or PL/SQL in the server. queuing.CHAPTER 10 Using PL/SQL with OCI8 PL/SQL is Oracle’s procedural language extension to SQL. PL/SQL Overview There are a number of pre-supplied PL/SQL packages to make application development easier. functions and packages so your business logic is reusable in all your applications. then SQL*Plus will display the output messages after execution: 131 . sending emails. In Oracle. If you turn on SET SERVEROUTPUT beforehand. exception when no_data_found then dbms_output. dbms_output. PL/SQL has a ‘wrap’ code obfuscation facility to protect the intellectual property of your applications. Using PL/SQL gives your application access to Oracle’s better date and number handling. In Oracle’s SQL*Plus it is run by entering the text at the prompt and finishing with a single / to tell SQL*Plus to run the code.put_line('No results returned'). you can create these to be fired when an event such as a data insert or a user logon occurs. If you write in PL/SQL. change notification.

7 dbms_output. and variables in packages can be used from other packages.Using PL/SQL with OCI8 SQL> set serveroutput on SQL> declare 2 sal_l pls_integer. 11 end. functions. The optional declarative part is written first. Packages and Triggers PL/SQL code is generally categorized as one of the following: * * * * Anonymous block Stored procedure or function Package Trigger Procedures. they are generally for one-time use either in a script or as SQL text dynamically submitted to the Oracle server. if anything they reference is not available. Functions return a value when executed.put_line('No results returned'). 3 begin 4 select salary into sal_l 5 from employees 6 where employee_id = 191. In many applications. PL/SQL blocks can appear wherever SQL statements can appear. where you define types. Oracle stores its parsed representation in the database for efficient reuse. Only the executable part of a PL/SQL block is required. When you create a stored procedure or function. procedures. A PL/SQL block groups related declarations and statements. variables. 8 exception 9 when no_data_found then 10 dbms_output. They may also have an invalid state. Procedures can be created in SQL*Plus like: 132 . Because these blocks are not stored in the database. Blocks. Errors that occur during execution can be dealt with in the exception-handling part. Procedures. and similar items. The previous example is an anonymous block.put_line('Salary is ' || sal_l). or functions. Stored or Standalone Procedures and Functions A stored procedure or function is a PL/SQL block that Oracle stores in the database and can be called by name from an application. They can be enabled and disabled to prevent them being used. 12 / Salary is 2500 Other tools have different ways of indicating the end of the statements and how to switch server output on. Anonymous Blocks An anonymous block is a PL/SQL block that appears in your application and is not named or stored in the database.

to record it.Creating PL/SQL Procedures in PHP SQL> create table mytab (mydata varchar2(40). The trigger can be called before the event. 8 end mypack. 4 / SQL> create or replace package body mypack as 2 function myfunc(i_p in number) return varchar2 as 3 d_l varchar2(20). For example. or event. end. under the heading Auto-Increment Columns. functions and triggers can be created using PHP. to prevent erroneous operations or fix new data so that it conforms to business rules. stored procedures and functions are encapsulated into packages. SQL> 2 3 4 5 6 create or replace procedure myproc(d_p in varchar2. The package specification defines the signatures of the functions and procedures. 6 return d_l. use the SQL*Plus SHOW ERRORS command to display any error messages Packages Typically. i_p). If you have errors creating a PL/SQL block.php <?php 133 . code that invokes it will not need to be recompiled even if the implementation in the package body changes. Creating PL/SQL Procedures in PHP Procedures. SQL> create or replace package mypack as 2 function myfunc(i_p in number) return varchar2. 3 end mypack. or take some follow-up action. Programs like PHP can run the procedure later. i_p in number) as begin insert into mytab (mydata. view. 4 begin 5 select mydata into d_l from mytab where myid = i_p. Executing SQL Statements with OCI8. myid) values (d_p. This helps minimizes recompilation of dependent objects. An example of a trigger was shown in the previous chapter. The trigger can be called after the event. 7 end. / The procedure is just created. not run. If that definition is unchanged. 9 / Triggers A database trigger is a stored procedure associated with a database table. to create the procedure myproc the code is: createmyproc. myid number).

i_p). ?> 134 . 'hrpwd'. $plsql)." . Calling PL/SQL Procedures and Functions To invoke the previously created PL/SQL procedure. ':ret'. oci_bind_by_name($s. } ?> Note that there is a semi-colon after the PL/SQL keyword end. In the next example. which is different to the way SQL statements are written.php <?php $c = oci_connect('hr'."). 123)"). "begin :ret := mypack. "insert into mytab (mydata. but you could include any number of other PL/SQL statements: anonplsql. '//localhost/XE'). You can also use an anonymous block. $s = oci_parse($c. $plsql = "create or replace procedure " .". 456).$r. end. ?> The call command is actually a SQL command and does not have a trailing semi-colon. 'hrpwd'. "end.php <?php $c = oci_connect('hr'.myfunc(123). "call myproc('Chris'. '//localhost/XE'). "begin " .php <?php $c = oci_connect('hr'. use the SQL CALL statement like: callplsql. '//localhost/XE'). "myproc(d_p in varchar2. oci_execute($s)."). i_p in number) as " . oci_execute($s). 'hrpwd'. if ($r) { echo 'Procedure created'. myid) values (d_p. the block contains a single procedure call. $s = oci_parse($c. Using the function myfunc() created above: plsqlfunc. 'hrpwd'. end. $r = oci_execute($s). $s = oci_parse($c. ?> Calling a PL/SQL function needs a bind variable to hold the return value. '//localhost/XE').Using PL/SQL with OCI8 $c = oci_connect('hr'. "begin myproc('Alison'. $s = oci_parse($c. echo "Name is: ". 20). oci_execute($s). $r.

$s = oci_parse($c. '//localhost/XE'). end. } else { // A normal SQL-style error 135 . PL/SQL Errors in PHP Some common PL/SQL errors you might encounter are: * * Success with information warnings Incorrect end of line terminators on Windows platforms This section gives a description of what may cause these errors. // A PL/SQL statement with deliberate error: not_mytab doesn’t exist $plsql = "create or replace procedure myproc(d_p in varchar2. PL/SQL Success With Information Warnings A common PL/SQL error when creating packages. and ways to resolve them. if (!$r) { $m = oci_error($s). i_p in number) as begin insert into not_mytab (mydata. i_p). The PHP code to check for informational errors and warnings is shown by this example that creates a procedure referencing a non-existent table and then queries the user_errors table when an ORA-24344 error occurs: plsqlerr.php <?php $c = oci_connect('hr'. 'hrpwd'. $plsql). $r = oci_execute($s).PL/SQL Errors in PHP The output is: Name is: Chris This example also shows how to call a function inside a package using the syntax packagename. if ($m['code'] == 24344) { // A PL/SQL "success with compilation error" show_compilation_errors($c). procedures or triggers is: Warning: oci_execute(): OCI_SUCCESS_WITH_INFO: ORA-24344: success with compilation error You can get more information about the problem cause by querying Oracle’s user_errors table.".procedurename(). myid) values (d_p.

Alternatively to show the PL/SQL errors. SQL> show errors procedure myproc Errors for PROCEDURE MYPROC: LINE/COL -------4/7 4/19 ERROR --------------------------------------------------------PL/SQL: SQL Statement ignored PL/SQL: ORA-00942: table or view does not End of Line Terminators in PL/SQL with Windows PHP On Windows platforms the additional messages from show_compilatation_errors() sometimes include: 136 . } } // Display PL/SQL errors function show_compilation_errors($c) { $s = oci_parse($c. connect to SQL*Plus and use SHOW ERRORS: SQL> connect hr/hrpwd@//localhost/XE Connected. MESSAGE_NUMBER"). $m['message'].' || TEXT FROM USER_ERRORS ORDER BY NAME. } ?> This displays: Warning: oci_execute(): OCI_SUCCESS_WITH_INFO: ORA-24344: success with compilation error in plsqlerr. print "<table border='1'>\n". Character 19 is the not_mytab table name. ATTRIBUTE.PL/SQL: SQL Statement ignored MYPROC: ERROR at character 19 of line 4 . "SELECT NAME || ': ' || ATTRIBUTE || ' at character ' || POSITION || ' of line ' || LINE || ' . while ($row = oci_fetch_array($s. } print "</tr>\n".Using PL/SQL with OCI8 echo "Error is ". } print "</table>".($item?htmlentities($item):" "). LINE.php on line 11 MYPROC: ERROR at character 7 of line 4 . character 7 on line 4 of the PL/SQL code is the INSERT statement. "\n"."</td>". OCI_ASSOC+OCI_RETURN_NULLS)) { print "<tr>". oci_execute($s). foreach ($row as $item) { print "<td>". POSITION.PL/SQL: ORA-00942: table or view does not exist Looking at the PL/SQL code creating the procedure.

". Also. . sets. collections can be passed as parameters. which allow you to declare index-by tables. myid) values (d_p. bags. SQL> create table emails ( 2 user_id varchar2(10). end. nested tables. . . A collection is an ordered group of elements. 4 email_address varchar2(20)). all of the same type. This can happen when the end of line characters in a multi-line PL/SQL string are Windows carriage-return line-feeds: $plsql = "create or replace procedure myproc(d_p in varchar2.Oracle Collections in PHP PLS-00103: Encountered the symbol "" when expecting one of the following: Followed by a list of keywords or tokens the PL/SQL parser was expecting. nested tables. Use one of these solutions to fix the problem: * * Write the PL/SQL code on a single line: $plsql = "create or replace procedure myproc . and variable-size arrays. SQL> drop table emails. i_p in number) as " "begin " "insert into mytab (mydata. 3 friend_name varchar2(20). i_p). . So. Use PHP string concatenation with appropriate white space padding: $plsql = . 137 . PL/SQL provides the datatypes TABLE and VARRAY. i_p). Collections work like the arrays found in most third-generation programming languages. In a simple email address book demonstration (created by Charles Poulsen from Oracle). "create or replace procedure " "myproc(d_p in varchar2. and trees. lists. * Convert the file to UNIX-style line-feeds using a conversion utility or editor. and one for an array of email addresses. Each element has a unique subscript that determines its position in the collection. you can use them to move columns of data into and out of database tables or between client-side applications and stored subprograms. myid) values (d_p. one for an array of people’s names. Similar to LOBs.".". two VARRAYs are created. " "end. To support these techniques in database applications. VARRAYs (short for variable-size arrays) use sequential numbers as subscripts to access a fixed number of elements. Collections are effectively arrays. Oracle Collections in PHP Many programming techniques use collection types such as arrays. i_p in number) as begin insert into mytab (mydata. which is allocated with oci_new_collection(). . collections are manipulated by methods on a collection resource.

for ($i=0. 3 / SQL> 2 3 4 5 6 7 8 9 10 11 12 13 14 15 create or replace procedure update_address_book( p_user_id in varchar2. end. In PHP we create collection variables and use the append() method to add elements to each array. for i in 1 . These collections are bound to the arguments of the PL/SQL address_book() call.php <?php $c = oci_connect('hr'. $user_name = 'cjones'. "begin update_address_book(:name. 'EMAIL_ARRAY'). p_email_addresses(i)). the names and email addresses are inserted into the database. friend_name.com'). $i++) { $friend_coll->append($friends_names[$i]). p_friend_name friend_array.count loop insert into emails (user_id.com'. 'hrpwd'. By binding as OCI_B_NTY (“Named Type”) we can pass collections to the PL/SQL procedure arguments. p_email_addresses. $friend_coll = oci_new_collection($c. p_friend_name(i). When this executes."). $i < count($friends_names). :friends.. email_address) values (p_user_id. p_email_addresses email_array) is begin delete from emails where user_id = p_user_id. 'aslam'). 'FRIEND_ARRAY'). $friends_emails = array('alison@example. updateaddresses. $email_coll = oci_new_collection($c. 'aslam@example. end loop. } $s = oci_parse($c. :emails).Using PL/SQL with OCI8 SQL> create or replace type email_array as 2 varray(100) of varchar2(20). $friends_names = array('alison'. 138 . The following PHP code creates a collection of names and a collection of email addresses. '//localhost/XE'). $email_coll->append($friends_emails[$i]). / The update_address_book() procedure loops over all elements of the address collection and inserts each one. 3 / SQL> create or replace type friend_array as 2 varray(100) of varchar2(20). end update_address_book.

myselproc(). ':friends'. 4 procedure myselproc(p_arr out arrtype. 6 end myinsproc. 3 procedure myinsproc(p_arr in arrtype). p_count in number) is 8 begin 9 select name bulk collect 10 into p_arr 11 from mytab 12 where rownum <= p_count.com aslam@example. selects from the table using the BULK COLLECT clause and returns the array as the OUT parameter p_arr. The second procedure. $email_coll. SQL> drop table mytab. this can be very efficient for insertion. Coupled with a helper PL/SQL function. $user_name). 6 / SQL> create or replace package body mypkg as 2 procedure myinsproc(p_arr in arrtype) is 3 begin 4 forall i in indices of p_arr 5 insert into mytab values (p_arr(i)). The p_count parameter is used to make sure PL/SQL does not try to return more values than the PHP array can handle. myinsproc(). -1. It uses Oracle’s “bulk” FORALL statement for fast insertion. USER_ID ---------cjones cjones FRIEND_NAME -------------------alison aslam EMAIL_ADDRESS -------------------alison@example. oci_bind_by_name($s. SQL> create table mytab(name varchar2(20)). will be passed a PHP array to insert. -1.2 improved collection support with a new function oci_bind_array_by_name(). ':emails'.com Other OCI8 collection methods allow accessing or copying data in a collection. 139 . oci_execute($s).Oracle Collections in PHP oci_bind_by_name($s. Array Binding and PL/SQL Bulk Processing PHP 5. OCI_B_NTY). 5 end mypkg. The first. 7 procedure myselproc(p_arr out arrtype.1. SQL> create or replace package mypkg as 2 type arrtype is table of varchar2(20) index by pls_integer. ':name'. $friend_coll. This example creates a PL/SQL package with two procedures. ?> The emails table now has the inserted data: SQL> select * from emails. p_count in number). OCI_B_NTY). oci_bind_by_name($s. We can bind a PHP array containing all data and send it to the database with a single oci_execute().

but also the number of elements in the array. "//localhost/XE"). and the data length is given as –1. SQLT_CHR). var_dump($r). oci_bind_array_by_name($s.Using PL/SQL with OCI8 13 14 15 end myselproc. 'hrpwd'. end mypkg. $s = oci_parse($c. end. SQLT_CHR). :n). end. // print the array A number of other Oracle types can be bound with oci_array_bind_by_name(). oci_bind_array_by_name($s. The number of elements $numelems to be fetched is passed into myselproc() by being bound to :n. ":p1". "begin mypkg.php <?php $c = oci_connect('hr'. the myselproc() function can be called. 140 . "begin mypkg. ":p1". oci_bind_by_name($s. $numelems = 4. -1. $r. $numelems. $a = array('abc'. This limits the query to return $numelems rows. It takes not just the upper data length. The value is also used in the oci_bind_array_by_name() call so the output array $r is correctly sized to accept that number of rows back. 'def'."). count($a). 'ghi'. NAME -------------------abc def ghi jkl To query the table in PHP. 'jkl'). use: arrayinsert. In this example. $a. These are also bundled with the PHP source code. ":n"."). '//localhost/XE'). The value 20 is the width of the database column. meaning use the actual length of the character data. 20. oci_execute($s). for example SQLT_FLT for floating point numbers. / To insert a PHP array into mytab. The inserted data shown in SQL*Plus is: SQL> select * from mytab.myinsproc(:p1). $c = oci_connect("hr".myselproc(:p1. $s = oci_parse($c. $numelems). "hrpwd". oci_execute($s). There are more examples of oci_bind_array_by_name() in the automated tests under the OCI8 CVS tree. the number of elements is count($a). Any lower value could result in shorter strings being returned to PHP. ?> The oci_bind_array_by_name() function is similar to oci_bind_by_name().

data varchar2(100) ). Oracle Text can perform linguistic analysis on documents.delete. in files. ctx. For example.sql. type SuppliedTabType is table of SuppliedRec index by binary_integer. procedure SuppliedProc(p_p in out nocopy SuppliedTabType).It has a procedure that returns a PL/SQL type.Create some random results p_p. Oracle Text supports multiple languages and uses advanced relevance-ranking technology to improve search quality. for i in 1. and support for information visualization metaphors. and so on. HTML with term highlighting.Package "SuppliedPkg" simulates Oracle Text's CTX_THES. create or replace package SuppliedPkg as type SuppliedRec is record ( id number.data := 'Random: ' || i || (1+ABS(MOD(dbms_random. end SuppliedPkg. PL/SQL types differ from SQL types that are created with the CREATE TYPE command. -. and original document format.. the Oracle Text CTX_THES package procedures return Oracle PL/SQL types that are not easily accessible in OCI8. Oracle Text is described in the Oracle marketing datasheets like this: “Oracle Text uses standard SQL to index. Oracle Text also offers advanced features like classification. / create or replace package body SuppliedPkg as procedure SuppliedProc(p_p in out nocopy SuppliedTabType) is begin -. end SuppliedProc. p_p(i).random. context queries. This example. just returns random data in the parameter: ctx. end SuppliedPkg.id := i. HTML/XML section searching. Boolean operations. search. and analyze text and documents stored in the Oracle database. end loop. It can render search results in various formats including unformatted text.sql -. pattern matching.” Let’s set up an example package with a similar interface to CTX_THES.5 loop p_p(i).100000))). mixed thematic queries. and on the web. as well as search text using a variety of strategies including keyword searching. / 141 . clustering.Oracle Collections in PHP Using PL/SQL Types in PHP Sometime you have to call PL/SQL procedures that are designed for interacting with other PL/SQL code.

p_data(i) := l_results(i).sql and use SQL*Plus to run it like the previous script: myproc. -. / Now you can call MyProc(): ctx.sql in SQL*Plus: $ sqlplus hr/hrpwd@//localhost/XE @ctx.sql This is the “fixed” part of the problem. 'begin MyProc(:res_id. :res_data). $res_data = oci_new_collection($c.get results from existing procedure SuppliedPkg. 'MYDATAREC').l_results. $s = oci_parse($c.extend.php <?php $c = oci_connect("hr". 142 . p_data. ':res_data'. Create myproc. oci_execute($s).Using PL/SQL with OCI8 Run the file ctx. 'MYIDREC'). / create or replace procedure MyProc (p_id IN OUT MyIdRec. To call SuppliedProc().id.. end MyProc. p_data.SuppliedProc() and converts its output to SQL types. create a wrapper function in PL/SQL to convert the PL/SQL type SuppliedTabType to a pair of SQL types. representing the pre-supplied functionality. / create or replace type MyDataRec as table of varchar2(100). $res_data. $res_id. OCI_B_NTY). for i in 1.SuppliedTabType.'). p_data IN OUT MyDataRec) as l_results SuppliedPkg.Create a wrapper procedure that calls the pre-supplied -.SuppliedProc(l_results). -1.copy to a type we can pass back to PHP p_id.sql -.delete. OCI_B_NTY). end loop. end. begin -.delete. "hr". "//localhost/XE"). $res_id = oci_new_collection($c. p_id(i) := l_results(i).extend. ':res_id'. -1. oci_bind_by_name($s. oci_bind_by_name($s.data. create or replace type MyIdRec as table of number.count loop p_id.

the collection method getElem() is used to access each value returned. 4. The output is similar to: Id: Id: Id: Id: Id: 1. SQL> 2 3 4 5 6 7 create or replace procedure myproc(p1 out sys_refcursor) as begin open p1 for select last_name from employees where rownum <= 5. '//localhost/XE'). As an example. It is simply executed like a normal query and used in a fetch loop. Data: Data: Data: Data: Data: Random: Random: Random: Random: Random: 155942 247783 365553 487553 589879 An alternative implementation could be to create MyProc() to return arrays and use oci_bind_array_by_name(). $i++) { $id = $res_id->getElem($i). / In PHP the oci_new_cursor() function returns a REF CURSOR. The procedure returns a REF CURSOR containing the employees’ last names. Data: $data<br>". we create a PL/SQL package with a procedure that queries the employees table. 3.php <?php $c = oci_connect('hr'. 2. 5. refcur. // Excute the call to the PL/SQL stored procedure $stid = oci_parse($c. This is bound to :rc in the call to myproc(). 143 . } ?> This allocates two collections and binds them as the parameters to MyProc(). $refcur = oci_new_cursor($c). The PL/SQL procedure contains the code. $data = $res_data->getElem($i).Using REF CURSORS for Result Sets for ($i = 0. echo "Id: $id. 'hrpwd'. end. In PHP you bind an OCI_B_CURSOR variable to a PL/SQL REFCURSOR procedure parameter and retrieve the rows of the result set in a normal fetch loop. After MyProc() has been called. Once the PL/SQL procedure has completed the value in $refcur is treated like a prepared statement identifier. $i < $res_id->size(). "call myproc(:rc)"). Using REF CURSORS for Result Sets REF CURSORS let you return a set of query results to PHP.

". echo '<table border="1">'. OCI_B_CURSOR). else $s = "BEGIN DBMS_OUTPUT. } 144 . } echo '</table>'.Using PL/SQL with OCI8 oci_bind_by_name($stid. $r = oci_execute($s). $p) { if ($p) $s = "BEGIN DBMS_OUTPUT. DBMS_OUTPUT is like a buffer.". $s = oci_parse($c.ENABLE(NULL). $s). END. dbmsoutput. Here are sample functions to enable and fetch DBMS_OUTPUT. $refcur. The PL/SQL procedure or block runs to completion before any output is returned.inc <?php // Turn dbms_output ON or OFF function SetServerOutput($c. -1.DISABLE(). puts some output in the buffer. oci_free_statement($s). return $r. ?> The output is: Abel Ande Atkinson Austin Baer Records returned by REF CURSORS cannot currently take advantage of row pre-fetching. Getting Output with DBMS_OUTPUT The DBMS_OUTPUT package is the standard way to “print” output in PL/SQL. foreach ($row as $c) { echo "<td>$c</td>\n". } echo '</tr>'. // Execute and fetch from the cursor oci_execute($refcur). oci_execute($stid). and then fetches from the buffer. The drawback is that it is not asynchronous. while($row = oci_fetch_assoc($refcur)) { echo '<tr>'. END. Other database connections cannot access your buffer. Your code turns on buffering. ':rc'.

enable buffering before executing the PL/SQL code that creates output. // Display the output $output = GetDbmsOutput($c). function GetDbmsOutput($c) { $res = false. END.inc"). dbmsoutput. // Turn on buffering of output SetServerOutput($c. ":ST". "hrpwd". if (!$succ) $res = false. world! If you expect large amounts of output. // Create some output $s = oci_parse($c.GET_LINE(:LN. $c = oci_connect("hr". :ST).php <?php include("dbmsoutput. or false. $s = oci_parse($c. ?> The output is the put_line() text: Hello. you may want to write your own code to stream results as they are fetched from the database instead of returning them in one array from DbmsOutputFetch(). "BEGIN DBMS_OUTPUT.2."). true). while (($succ = oci_execute($s)) && !$st) $res[] = $ln. 255) && oci_bind_by_name($s. 145 . oci_execute($s). ":LN". $ln. if (oci_bind_by_name($s. return $res. $st)) { $res = array(). "call dbms_output. To use GetDbmsOutput(). This was the DBMS_OUTPUT line size limit prior to Oracle 10g Release 10.Getting Output with DBMS_OUTPUT // Returns an array of dbms_output lines. } oci_free_statement($s). foreach ($output as $line) echo "$line<br>". "//localhost/XE"). } ?> In GetDbmsOutput() the :LN line variable is arbitrarily bound as length 255.put_line('Hello. world!')").

146 .Using PL/SQL with OCI8 In Oracle 10g Release 10. the maximum line length was changed from 255 bytes to 32Kb and a theoretically infinite number of lines can now be returned. you can also get output by logging to database tables or using packages like UTL_FILE and DBMS_PIPE to asynchronously display output to a separate terminal window. Avoid binding 32Kb. If you bind this size. then it is easy to slow performance or get memory errors. If DBMS_OUTPUT does not suit your application.2. especially if the database is running in Oracle’s shared server mode.

They can be used for table columns and PL/SQL variables. The $lob->save() method then stores the data in $myv into the BLOB column. oci_bind_by_name($s. blobdata) ' . the PHP descriptor in $lob references this locator. blobdata blob). oci_bind_by_name($s. EMPTY_BLOB()) ' . The OCI_DEFAULT flag is used for oci_execute() so the descriptor remains valid for the save method. OCI_B_BLOB). $lob.CHAPTER 11 Using Large Objects in OCI8 Oracle Character Large Object (CLOB) and Binary Large Object (BLOB) types can contain very large amounts of data. 'RETURNING blobdata INTO :blobdata'). ':BLOBDATA'. $s = oci_parse($c. $myv = 'a very large amount of binary data'.php <?php $c = oci_connect('hr'. 'VALUES(:myblobid. ':MYBLOBID'. OCI_DEFAULT). '//localhost/XE'). PHP code to insert data into this table is: blobinsert. LOBs are manipulated using a descriptor. There are various ways to specify them for optimal Oracle storage. oci_execute($s. The commit concludes the insert and makes the data visible to other database users. 'hrpwd'. Oracle also has a BFILE type for large objects stored outside the database. -1. OCI_B_LOB). A pre-supplied DBMS_LOB package makes manipulation in PL/SQL easy. By binding as OCI_B_BLOB. $myblobid). $lob = oci_new_descriptor($c. 'INSERT INTO mybtab (blobid. $lob->save($myv). 147 . $myblobid = 123. To show this. ?> The RETURNING clause returns the Oracle LOB locator of the new row. in SQL*Plus create a table that has a BLOB column: SQL> create table mybtab (blobid number. oci_commit($c). Working with LOBs In PHP.

$stmt = oci_parse ($c. Table 11-1 LOB methods and functions PHP Function or Method OCI-Lob->close OCI-Lob->eof OCI-Lob->erase OCI-Lob->export OCI-Lob->writeToFile OCI-Lob->flush OCI-Lob->free OCI-Lob->getBuffering Action Close a LOB descriptor Test for LOB end-of-file Erases a specified part of the LOB Write a LOB to a file Flushes buffer of the LOB to the server Frees resources associated with the LOB Returns current state of buffering for the LOB 148 . it can be inserted directly from the upload directory with $lob->import($filename). When fetching a LOB. $result = $arr['BLOBDATA']->read(50). $arr = oci_fetch_assoc($stmt). PHP’s maximum allowed size for uploaded files is set in php. The full list of LOB methods and functions is shown in table 11-1. The PHP manual recommends using read() instead of load() because it allows the data size of data to be limited. and the table must obviously contain a CLOB column. Using CLOBs is almost identical to using BLOBs. OCI_SEEK_SET). The bind type becomes OCI_B_CLOB. exporting data directly to file. and copying or comparing a LOB. This code snippet shows seeking to the 10th position in the result descriptor. Other LOB Methods A number of other methods on the LOB descriptor allow seeking to a specified offset. set with memory_limit in php.ini using the upload_max_filesize parameter.ini. erasing data. OCI8 returns the LOB descriptor. oci_execute($stmt).Using Large Objects in OCI8 If the application uploads LOB data using a web form. $data = $arr['BLOBDATA']->load(). and then storing the next 50 bytes in $result: $arr['BLOBDATA']->seek(10. $query). This can help avoid the PHP process abruptly terminating when it reaches its allocated maximum memory size. Check the PHP manual for usage. and the data is retrieved by using a load() or read() method: $query = 'SELECT blobdata FROM mybtab WHERE blobid = 123'.

BFILEs are a handy way for using relatively static. In SQL and PL/SQL. the browser is redirected to the image URL of the external file. For example if the file is /tmp/cj. a BFILE is accessed via a locator. They are also useful for loading text or binary data into Oracle tables. the image data is not loaded and printed in PHP. To allow Apache to serve the image. In this example. externally created content. Instead. which is simply a pointer to the external file.jpg add: 149 .Working with BFILEs PHP Function or Method OCI-Lob->import OCI-Lob->saveFile OCI-Lob->load OCI-Lob->read OCI-Lob->rewind OCI-Lob->save OCI-Lob->seek OCI-Lob->setBuffering OCI-Lob->size OCI-Lob->tell OCI-Lob->truncate OCI-Lob->write OCI-Lob->writeTemporary oci_lob_copy oci_lob_is_equal Action Loads data from a file to a LOB Returns LOB contents Returns part of the LOB Moves the LOB’s internal pointer back to the beginning Saves data to the LOB Sets the LOB's internal position pointer Changes LOB's current state of buffering Returns size of LOB Returns current pointer position Truncates a LOB Writes data to the LOB Writes a temporary LOB Copies a LOB Compare two LOB locators for equality Working with BFILEs A BFILE is an Oracle large object (LOB) datatype for files stored outside the database. The image will not be loaded into the database but the picture description is loaded so it can be queried. edit httpd. To show how BFILEs work in PHP this section creates a sample application that accesses and displays a single image. There are numerous pre-supplied functions that operate on BFILE locators. Also the application could be extended in future to use PL/SQL packages to read and manipulate the image. The BFILE allows the image to be related to the description.conf and map a URL to the directory containing the file. This significantly reduces the amount of data that needs to be handled by the application.

"hrpwd". bfilename('TESTDIR'. :name))"). oci_bind_by_name($s.jpg". a text description of the file. :fdsc. ":name". The image data is not loaded into this table. This new BFILE can be queried back in PHP: bfilequery1. oci_bind_by_name($s. ":fdsc". ?> The bfilename() constructor inserts into the BFILE-type column using the TESTDIR directory alias created earlier. oci_execute($s. Image) values (:fnum.jpg. $name. the BFILE in the table is a pointer to the file on your filesystem. In SQL*Plus run: SQL> SQL> SQL> SQL> SQL> connect system/systempwd@//localhost/XE create directory TestDir AS '/tmp'.Using Large Objects in OCI8 Alias /tmp/ "/tmp/" <Directory "/tmp/"> Options None AllowOverride None Order allow. OCI_DEFAULT). This gives the hr user access to the /tmp directory and creates a table FileTest containing a file number identifier.jpg loads the picture in /tmp/cj. $fdsc. $name = "cj. create a DIRECTORY alias for /tmp. In Oracle. $c = oci_connect("hr". FileDesc varchar2(30). $fdsc = "Some description to search". FileDesc. -1. oci_commit($c). $s = oci_parse($c.deny Allow from all </Directory> Using /tmp like this is not recommended for anything except testing! Restart Apache and use a browser to check that http://localhost/tmp/cj. $fnum. "//localhost/XE"). oci_bind_by_name($s. "insert into FileTest (FileNum. SQLT_CHR).php <?php $fnum = 1. SQLT_INT). Bind variables are used for efficiency and security. This is Oracle’s pointer to the operating system and forms part of each BFILE. ":fnum". Image bfile). -1. -1. SQLT_CHR).php <?php 150 . PHP code to insert the image name into the FileTest table looks like: bfileinsert. connect hr/hrpwd@//localhost/XE create table FileTest ( FileNum number primary key. grant read on directory TestDir to hr. and the BFILE itself. The directory must be on the same machine that the database server runs on.

filegetname(b_l.php <?php $c = oci_connect("hr". 'b_l bfile.jpg is returned in $name courtesy of the :name bind variable argument to the DBMS_LOB. var_dump($bf). $s = oci_parse($c. ":name". ?> For simplicity. oci_bind_by_name($s.' . SQLT_CHR).FILEGETNAME() function. :name). $fnum = 1. $fnum = 1. 'end. echo "</pre>".Working with BFILEs $c = oci_connect("hr". ?> The filename cj. 255. $name. 'somepattern') The PHP script returns a BFILE descriptor. But if you have (or create) an Oracle procedure you could pass it the BFILE descriptor and get the name. 'da_l varchar2(255). da_l. Now what? In this example the file name is needed so the browser can redirect to a page showing the image. In real life it might use a regular expression on the FileDesc field like: select Image from FileTest where regexp_like(FileDesc.' . "select Image from FileTest where FileNum = :fnum"). a more efficient method is to create a PL/SQL anonymous block that does both the query and extracts the filename from its returned BFILE.' . "//localhost/XE").' . the query condition is the file number of the new record. 'dbms_lob. $row = oci_fetch_assoc($s). oci_execute($s).'). Instead of executing the query in PHP and using PL/SQL to find the filename. 'begin ' . $fnum). $fnum). $bf = $row['IMAGE']. ":fnum". 'declare ' . // This is a BFILE descriptor echo "<pre>". The previous query code in bfilequery1. The header() function redirects the user to the 151 . ":fnum". Unfortunately there is no direct method in PHP to get the filename from the descriptor. $s = oci_parse($c. 'select image into b_l from filetest where filenum = :fnum. oci_execute($s). oci_bind_by_name($s.php can be replaced with: bfilequery2. "hrpwd". "//localhost/XE"). "hrpwd". header("Location: http://localhost/tmp/$name"). oci_bind_by_name($s.

LOADFROMFILE() reads BFILE data from the file system into a PL/SQL BLOB or CLOB. end. Another example is DBMS_LOB. 255."). begin select image into bf_l from FileTest where FileNum = fnum_p. ?> BFILEs are easy to work with in PL/SQL because the presupplied DBMS_LOB package has a number of useful functions. SQLT_CHR). BFILEs are very useful for many purposes including loading images into the database.php <?php $c = oci_connect("hr". oci_bind_by_name($s. This lets Oracle parse and optimize the code at creation time. comment out the header() call and check that $name is valid. Changes to BFILE locators can be rolled back or committed but since the files themselves are outside the database.Using Large Objects in OCI8 image. ":name". da_l. The browser is redirected to the image similar to the previous example: getpic. "begin MyGetFileName(:fnum. You can have dangling references to BFILEs because Oracle does not check the validity of BFILEs until the data is explicitly read (this allows you to precreate BFILEs or to change the physical data on disk). For example DBMS_LOB. BFILEs need to be backed up manually. $fnum). $fnum = 1. The application can be improved by putting the PL/SQL into a stored procedure. name_p out varchar2) as bf_l bfile. This could be loaded into a BLOB table column. name_p). there might be times you should use BLOBs to store images inside the database to ensure data and application consistency but BFILEs are there if you want them. "//localhost/XE"). which can be used to check whether the FileTest table contains references to images that do not exist. BFILE data does not participate in transactions. $name. the HTTP headers will not be correct and the image will not display. oci_execute($s). or even returned to PHP using OCI8’s LOB features. da_l varchar2(255). ":fnum". If you have problems. :name). header("Location: http://localhost/tmp/$name"). "hrpwd". Because of these points. $s = oci_parse($c. manipulated in PL/SQL. dbms_lob. end.filegetname(bf_l.FILEEXISTS(). If any text is printed before the header() is output. BFILE data files are read-only and cannot be changed within Oracle. To create a PL/SQL procedure MyGetFileName() in SQL*Plus: SQL> connect hr/hrpwd@//localhost/XE SQL> create or replace procedure MyGetFileName (fnum_p in number. but BLOBs may be better in some circumstances. oci_bind_by_name($s. 152 . Finally. / Back in PHP the filename is easily fetched from the database with an anonymous block.

CHAPTER 12

Using XML with Oracle and PHP
Both Oracle and PHP 5 have excellent XML capabilities, allowing lots of choice for processing information. All editions of Oracle contain what is known as “XML DB”, the XML capabilities of the database. When tables are created, XML can be stored in linear LOB format, or according to the structure of your XML schema. This chapter covers the basics of returning XML data from Oracle to PHP.

Fetching Relational Rows as XML
One useful feature of XML DB is that relational SQL tables can automatically be retrieved as XML. The queried XML is in XML fragments, and not fully formed XML documents.
xmlfrag.php
<?php $c = oci_connect('hr', 'hrpwd', '//localhost/XE'); $query = 'SELECT XMLELEMENT("Employees", XMLELEMENT("Name", employees.last_name), XMLELEMENT("Id", employees.employee_id)) as result FROM employees WHERE employee_id > 200'; $s = oci_parse($c, $query); oci_execute($s); while ($row = oci_fetch_row($s)) foreach ($row as $item) echo htmlentities($item)." "; ?>

The output is:
<Employees><Name>Hartstein</Name><Id>201</Id></Employees> <Employees><Name>Fay</Name><Id>202</Id></Employees> <Employees><Name>Mavris</Name><Id>203</Id></Employees> <Employees><Name>Baer</Name><Id>204</Id></Employees> <Employees><Name>Higgins</Name><Id>205</Id></Employees> <Employees><Name>Gietz</Name><Id>206</Id></Employees>

153

Fetching Rows as Fully Formed XML

Tip: Watch out for the quoting of XML queries. The XML functions can have embedded double-quotes. This is the exact opposite of standard SQL queries, which can have embedded single quotes.

There are a number of other XML functions that can be similarly used. See the Oracle Database SQL Reference.

Fetching Rows as Fully Formed XML
Another way to create XML from relational data is to use the PL/SQL package DBMS_XMLGEN(). This package returns a fully formed XML document, with the XML header. Queries that use DBMS_XMLGEN() return a CLOB column, so the initial result needs to be treated in PHP as a LOB descriptor. There is effectively no length limit for CLOBs. The following example queries the first name of employees in department 30 and stores the XML marked-up output in $mylob:
getxml.php
<?php $c = oci_connect('hr', 'hrpwd', '//localhost/XE'); $query = "select dbms_xmlgen.getxml(' select first_name from employees where department_id = 30') xml from dual"; $s = oci_parse($c, $query); oci_execute($s); $res = oci_fetch_row($s); $mylob = $res[0]->load(); // treat result as a LOB descriptor echo "<pre>\n"; echo htmlentities($mylob); echo "</pre>\n"; ?>

The value of $mylob is:
<?xml version="1.0"?> <ROWSET> <ROW> <FIRST_NAME>Den</FIRST_NAME> </ROW> <ROW> <FIRST_NAME>Alexander</FIRST_NAME> </ROW> <ROW>

154

Fetching Rows as Fully Formed XML

<FIRST_NAME>Shelli</FIRST_NAME> </ROW> <ROW> <FIRST_NAME>Sigal</FIRST_NAME> </ROW> <ROW> <FIRST_NAME>Guy</FIRST_NAME> </ROW> <ROW> <FIRST_NAME>Karen</FIRST_NAME> </ROW> </ROWSET>

Using the SimpleXML Extension in PHP
You can use PHP 5’s SimpleXML extension to convert XML to a PHP object. Following on from the previous example the query results can be converted with:
$xo = simplexml_load_string((binary)$mylob); var_dump($xo);

Note the cast to binary which ensures consistent encoding. The output is:
object(SimpleXMLElement)#2 (1) ["ROW"]=> array(6) { [0]=> object(SimpleXMLElement)#3 ["FIRST_NAME"]=> string(3) "Den" } [1]=> object(SimpleXMLElement)#4 ["FIRST_NAME"]=> string(9) "Alexander" } [2]=> object(SimpleXMLElement)#5 ["FIRST_NAME"]=> string(6) "Shelli" } [3]=> object(SimpleXMLElement)#6 ["FIRST_NAME"]=> string(5) "Sigal" } [4]=> object(SimpleXMLElement)#7 ["FIRST_NAME"]=> string(3) "Guy" } [5]=> object(SimpleXMLElement)#8 ["FIRST_NAME"]=> {

(1) {

(1) {

(1) {

(1) {

(1) {

(1) {

155

$r->FIRST_NAME . $query). A basic XQuery to return the records in the employees table is: for $i in ora:view("employees") return $i This XQuery syntax is in a special SELECT: SELECT COLUMN_VALUE FROM XMLTABLE('for $i in ora:view("employees") return $i') The different quoting styles used by SQL and XQuery need careful attention in PHP. $query = 'SELECT COLUMN_VALUE FROM XMLTABLE(\''. There is an article Using PHP5 with Oracle XML DB by Yuli Vasiliev in the July/August 2005 Oracle Magazine that discusses this.php <?php $c = oci_connect("hr". "<br>\n".$xq." ". $s = oci_parse($c. oci_execute($s).'\')'. "//localhost/XE"). but it is in the other editions of Oracle. to keep the footprint of Oracle XE small. XQuery is not available in the Oracle XE release. Unfortunately.XQuery XML Query Language string(5) "Karen" } } } This object can be accessed with array iterators or properties: foreach ($xo->ROW as $r) { echo "Name: " . $xq = 'for $i in ora:view("employees") return $i'. ?> 156 . while ($row = oci_fetch_row($s)) foreach ($row as $item) echo htmlentities($item). } This output from the loop is: Name: Name: Name: Name: Name: Name: Den Alexander Shelli Sigal Guy Karen As an alternative to SimpleXML you could use PHP’s older DOM extension. It can be coded: xquery. XQuery XML Query Language Oracle’s support for XQuery was introduced in Oracle Database 10g Release 2. "hrpwd".

XQuery XML Query Language

Table rows are automatically wrapped in tags and returned:
<ROW> <EMPLOYEE_ID>100</EMPLOYEE_ID> <FIRST_NAME>Steven</FIRST_NAME> <LAST_NAME>King</LAST_NAME> <EMAIL>SKING</EMAIL> <PHONE_NUMBER>515.123.4567</PHONE_NUMBER> <HIRE_DATE>1987-06-17</HIRE_DATE> <JOB_ID>AD_PRES</JOB_ID> <SALARY>24000</SALARY> <DEPARTMENT_ID>90</DEPARTMENT_ID> </ROW> … <ROW> <EMPLOYEE_ID>206</EMPLOYEE_ID> <FIRST_NAME>William</FIRST_NAME> <LAST_NAME>Gietz</LAST_NAME> <EMAIL>WGIETZ</EMAIL> <PHONE_NUMBER>515.123.8181</PHONE_NUMBER> <HIRE_DATE>1994-06-07</HIRE_DATE> <JOB_ID>AC_ACCOUNT</JOB_ID> <SALARY>8300</SALARY> <MANAGER_ID>205</MANAGER_ID> <DEPARTMENT_ID>110</DEPARTMENT_ID> </ROW>

You can also use RETURNING CONTENT to return a single document node:
$xq = 'for $i in ora:view("hr","locations")/ROW return $i/CITY'; $query = 'SELECT XMLQUERY(\''.$xq.'\' RETURNING CONTENT) FROM DUAL';

Since this result is treated as a single SQL query row, there are restrictions on its length.

Accessing Data from Oracle over HTTP
XML DB allows you to access data directly via HTTP, FTP or WebDAV. The Oracle Network listener will handle all these requests. As an example of HTTP, use the PL/SQL DBMS_XDB package to create a resource, which here is some simple text:
SQL> declare 2 res boolean; 3 begin 4 begin 5 -- delete if it already exists 6 dbms_xdb.deleteResource('/public/test1.txt'); 7 exception 8 when others then 9 null; 10 end; 11 -- create the file 12 res := dbms_xdb.createResource('/public/test1.txt', 13 'the text to store'); 14 commit; -- don’t forget to commit 15 end; 157

XQuery XML Query Language

16

/

For testing, remove access control on the public resource:
SQL> connect system/systempwd SQL> alter user anonymous identified by anonymous account unlock;

Sometimes it takes a few minutes for this all to take effect, but the file can now be accessed from a browser (or PHP application) using:

http://localhost:8080/public/test1.txt
If you are accessing Oracle XE from a remote browser, you may need to enable remote client connection as described in the chapter Installing Oracle Database 10g Express Edition. There is extensive Oracle documentation on XML DB on the Oracle Technology network at http://otn.oracle.com/tech/xml/xmldb.

158

CHAPTER 13

Globalization
This chapter discusses global application development in a PHP and Oracle Database XE environment. It addresses the basic tasks associated with developing and deploying global Internet applications, including developing locale awareness, constructing HTML content in the user-preferred language, and presenting data following the cultural conventions of the locale of the user. Building a global Internet application that supports different locales requires good development practices. A locale refers to a national language and the region in which the language is spoken. The application itself must be aware of the locale preference of the user and be able to present content following the cultural conventions expected by the user. It is important to present data with appropriate locale characteristics, such as the correct date and number formats. Oracle Database XE is fully internationalized to provide a global platform for developing and deploying global applications.

Establishing the Environment Between Oracle and PHP
Correctly setting up the connectivity between the PHP engine and the Oracle database is the first step in building a global application. It guarantees data integrity across all tiers. Most Internet based standards support Unicode as a character encoding. This chapter focuses on using Unicode as the character set for data exchange. OCI8 is an Oracle OCI application, and rules that apply to OCI also apply to PHP. Oracle locale behavior (including the client character set used in OCI applications) is defined by Oracle’s “national language support” NLS_LANG environment variable. This environment variable has the form:
<language>_<territory>.<character set>

For example, for a German user in Germany running an application in Unicode, NLS_LANG should be set to
GERMAN_GERMANY.AL32UTF8

The language and territory settings control Oracle behaviors such as the Oracle date format, error message language, and the rules used for sort order. The character set AL32UTF8 is the Oracle name for UTF-8. For information on the NLS_LANG and other Oracle language environment variables, see the Oracle documentation. When Zend Core for Oracle is installed on Apache, you can set NLS_LANG in /etc/profile:
export NLS_LANG GERMAN_GERMANY.AL32UTF8

If the globalization settings are invalid, PHP may fail to connect to Oracle and give an error like
159

$s = oci_parse($c. 1. Open the Zend Core for Oracle Administration Console by entering the URL in a web browser: http://<machine_name>/ZendCore 2.6. After executing this. To handle other character sets. the altered values will still be in effect. Caution: Be careful changing the globalization settings when using a persistent connection. To enable multibyte strings in PHP using the Zend Core for Oracle Administration Console.1\lib"/> <variable id="PHPRC" value="D:\oracle\1012J2EE\Apache\Apache\conf"/> <variable id="NLS_LANG" value="german_germany. a set of “MultiByte String Functions” is available. "alter session set nls_territory=germany nls_language=german"). you must set NLS_LANG as an environment variable in $ORACLE_HOME/opmn/conf/opmn.xml: <ias-component id="HTTP_Server"> <process-type id="HTTP_Server" module-id="OHS"> <environment> <variable id="PERL5LIB" value="D:\oracle\1012J2EE\Apache\Apache\mod_perl\site\5.al32utf8"/> </environment> <module-data> <category id="start-parameters"> <data id="start-mode" value="ssl-disabled"/> </category> </module-data> <process-set id="HTTP_Server" numprocs="1"/> </process-type> </ias-component> You must restart the Web listener to implement the change. Login in and navigate to Configuration > Extensions > Zend Core Extensions. 160 . Manipulating Strings PHP was designed to work with the ISO-8859-1 character set. The next time the connection is used. oci_execute($s). specifically multibyte character sets.Globalization ORA-12705: Cannot access NLS data files or invalid environment specified Some globalization values can be changed per connection. Oracle error messages will be in German and the default date format will have changed. If PHP is installed on Oracle HTTP Server.

When you have enabled the mbstring extension and restarted the web server. 161 . Refresh the browser on the Extension Configuration page to see these mbstring configuration options. and the application should fall back to a predefined default locale. Enable the mbstring extension. which returns the number of bytes in a string.net/mbstring. then there is no locale preference information available. 5. Determining the Locale of the User In a global environment. The PL/SQL UTL_I18N package contains mapping functions that can map between ISO and Oracle locales. When you write global applications implemented in different programming environments. time. For example. Save the configuration. This may return different values than strlen(). 4. such as date. For more information. and monetary formatting to format the HTML pages according to the cultural conventions of the locale. The following PHP code retrieves the ISO locale from the Accept-Language HTTP header through the $_SERVER Server variable. you should enable the synchronization of user locale settings between the different environments. several configuration options become available in the Zend Core for Oracle Administration Console. Restart Apache. the application can call localesensitive functions. PHP applications that call PL/SQL procedures should map the ISO locales to the corresponding NLS_LANGUAGE and NLS_TERRITORY values and change the parameter values to match the locale of the user before calling the PL/SQL procedures. Table 13-1 shows how some commonly used locales are defined in ISO and Oracle environments. Usually a browser sends its locale preference setting to the HTTP server with the Accept Language HTTP header. If the Accept Language header is NULL.php.Determining the Locale of the User 3. You can change the behavior of the standard PHP string functions by setting mbstring. A common method to determine the locale of a user is from the default ISO locale setting of the browser. the application should construct HTML content in the language of the locale and follow the cultural conventions implied by the locale. your application should accommodate users with different locale preferences. Once it has determined the preferred locale of the user. $s = $_SERVER["HTTP_ACCEPT_LANGUAGE"] Developing Locale Awareness Once the locale preference of the user has been determined. see the PHP mbstring reference manual at http://www. Your application code should use functions such as mb_strlen() to calculate the number of characters in strings.func_overload to one of the “Overload” settings.

C. Internet applications must know about the HTML page encoding so they can process input data from an HTML form.R. SQL. The browser must know about the page encoding so that it can use the correct fonts and character set mapping tables to display the HTML pages.) Chinese (Taiwan) English (U. You can think of the page encoding as the character set used for the locale that an Internet application is serving. and PL/SQL Programming Environments Locale Chinese (P.Globalization Table 13-1 Locale Representations in ISO. This encoding not only simplifies the coding for global applications. but it also enables multilingual content on a single page.A) English (United Kingdom) French (Canada) French (France) German Italian Japanese Korean Portuguese (Brazil) Portuguese Spanish Locale ID zh-CN zh-TW en-US en-GB fr-CA fr-FR de it ja ko pt-BR pt es NLS_LANGUAGE SIMPLIFIED CHINESE TRADITIONAL CHINESE AMERICAN ENGLISH CANADIAN FRENCH FRENCH GERMAN ITALIAN JAPANESE KOREAN BRAZILIAN PORTUGUESE PORTUGUESE SPANISH NLS_TERRITORY CHINA TAIWAN AMERICA UNITED KINGDOM CANADA FRANCE GERMANY ITALY JAPAN KOREA BRAZIL PORTUGAL SPAIN Encoding HTML Pages The encoding of an HTML page is important information for a browser and an Internet application.S. Instead of using different native encodings for the different locales. or in HTML page header. Specifying the Page Encoding for HTML Pages You can specify the encoding of an HTML page either in the HTTP header. 162 . Oracle recommends that you use UTF-8 (Unicode encoding) for all page encodings.

Your application must ensure that the server-generated pages are encoded in UTF-8. Specifying the Page Encoding in PHP You can specify the encoding of an HTML page in the Content-Type HTTP header in PHP by setting the default_charset configuration variable as follows: default_charset = UTF-8 To enable character set encoding of HTML pages using the Zend Core for Oracle Administration Console. include the Content-Type HTTP header in the HTTP specification. the possible values for the charset parameter are the IANA (Internet Assigned Numbers Authority) names for the character encodings that the browser supports.charset=utf-8"> The charset parameter specifies the encoding for the HTML page. The Content-Type HTTP header has the following form: Content-Type: text/html. Login in and navigate to Configuration > PHP > Data Handling. charset=utf-8 The charset parameter specifies the encoding for the HTML page. Save the configuration. To specify HTML page encoding in the HTML page header. 163 .Encoding HTML Pages Specifying the Encoding in the HTTP Header To specify HTML page encoding in the HTTP header. 4. 1. Restart Apache. 3. The possible values for the charset parameter are the IANA names for the character encodings that the browser supports. specify the character encoding in the HTML header as follows: <meta http-equiv="Content-Type" content="text/html. It specifies the content type and character set. Specifying the Encoding in the HTML Page Header Use this method primarily for static HTML pages. This setting does not imply any conversion of outgoing pages. As with the ContentType HTTP Header. Open the Zend Core for Oracle Administration Console by entering the URL in a web browser: http://<machine_name>/ZendCore 2. Enter UTF-8 for the default_charset parameter. 5.

in Germany this symbol is a thousand separator. you must include a WHERE clause in your query. Translatable sources for the content of an HTML page belong to the following categories: * * * Text strings included in the application code Static HTML files. whereas in the United Kingdom it means ‘12th November 2005’. the date ‘12/11/05’ implies ‘11th December 2005’ in the United States. images files. Presenting data not sorted in the linguistic sequence that your users are accustomed to can make searching for information difficult and time consuming. stage the static files of different languages in different directories or with different file names. Static Files Static files such as HTML and text stored as images are readily translatable. These text messages can be stored in flat files or database tables depending on the type and the volume of the data being translated. Presenting Data Using Conventions Expected by the User Data in the application must be presented in a way that conforms to the expectation of the user.Globalization Organizing the Content of HTML Pages for Translation Making the user interface available in the local language of the user is a fundamental task in globalizing an application. Some languages are collated according to the letter sequence in the alphabet. Otherwise. To differentiate various translations. This can be a particular problem in PHP when database numbers are fetched as PHP strings. Data from the Database Dynamic information such as product names and product descriptions is typically stored in the database. and template files such as CSS Dynamic data stored in the database Strings in PHP You should externalize translatable strings within your PHP application logic. For example. For example. the database schema holding this information should include a column to indicate the language.’ is a decimal separator in the United States. To differentiate the languages of the translated files. Different languages have their own sorting rules. When these files are translated. 164 . To select the desired language. the meaning of the data can be misinterpreted. they should be translated into the corresponding language with UTF-8 as the file encoding. so that the text is readily available for translation. and some languages are ordered by the pronunciation of the words. Similar confusion exists for number and monetary formats of the users. some according to the number of stroke counts in the letter. the symbol ‘.

1987 Thursday.User Presenting Data Using Conventions Expected by the Depending on the application logic and the volume of data retrieved from the database.Kochhar L. Januar 1993 Mittwoch. and long dates.1.1)||'.'DS') "Hiredate". Oracle Date Formats The three different date presentation formats in Oracle are standard.90 21. 1989 Wednesday. 1993 Wednesday. The following sections provide examples of locale-sensitive operations in SQL. 13. 21.91 Long HireDate -----------------------------Mittwoch. short. September 21. September 1989 Mittwoch. to set the format to ’YYYYMM-DD HH24:MI:SS’ use: 165 . 1991 EMPID ---------100 101 102 103 104 SQL> alter session set nls_territory=germany nls_language=german.De Haan A.Hunold B.09. SQL> alter session set nls_territory=america nls_language=american.01. Session altered.05. 1990 Tuesday.King N.06. Juni 1987 Donnerstag.1)||'. Januar 1990 Dienstag. to_char(hire_date.Ernst Hiredate ---------06/17/1987 09/21/1989 01/13/1993 01/03/1990 05/21/1991 Long HireDate ----------------------------Wednesday.89 13.Ernst Hiredate -------17.King N. 21.01. it may be more appropriate to format the data at the database level rather than at the application level. SQL> 2 3 4 5 6* select employee_id EmpID.1.'||last_name "EmpName".'DL') "Long HireDate" from employees where employee_id <105. May 21.Kochhar L. substr(first_name. substr(first_name. EmpName ----------------S. to_char(hire_date. SQL> 2 3 4 5 6* select employee_id EmpID.87 21. EmpName ---------------S. The following examples illustrate the differences between the short date and long date formats for both the United States and Germany.'DS') "Hiredate". January 13. For example. to_char(hire_date.Hunold B.De Haan A. to_char(hire_date. Oracle offers many features that help to refine the presentation of data when the locale preference of the user is known.93 03.'||last_name "EmpName". June 17. Mai 1991 EMPID ---------100 101 102 103 104 In PHP you can override any default date format.'DL') "Long HireDate" from employees where employee_id <105. January 3. 3. 17. Session altered.

See the tip “Do Not Set the Date Format Unnecessarily” in the chapter Connecting to Oracle Using OCI8 for how to set the format in a database logon trigger. '99G999D99') "Salary" from employees where employee_id <105 EmpName Salary --------------------------.Ernst 6.000.De Haan 17.De Haan 17.Globalization $c = oci_pconnect("hr". $s = oci_parse($c. substr(first_name.1)||'. "hrpwd".'||last_name "EmpName".00 A. SQL> alter session set nls_territory=america.000.Hunold 9.00 B.1.000.00 N.1. 166 .Hunold 9.000.1)||'. "//localhost/XE").000. SQL> 2 3 4 5* select employee_id EmpID. Oracle Number Formats The following examples illustrate the differences in the decimal character and group separator between the United States and Germany.'||last_name "EmpName".00 A.00 B.---------S.Kochhar 17.Ernst 6.000.Kochhar 17.00 EMPID ---------100 101 102 103 104 Because OCI8 fetches numbers as PHP strings it possible to lose decimal places or have other errors when PHP converts a string with an incorrect decimal separator. Session altered.000. substr(first_name. do_query($c. '99G999D99') "Salary" from employees where employee_id <105 EmpName Salary --------------------------. to_char(salary.00 L.00 N. $r = oci_execute($s).00 L.000. SQL> 2 3 4 5* select employee_id EmpID. to_char(salary.000. "select sysdate from dual").000.King 24.00 EMPID ---------100 101 102 103 104 SQL> alter session set nls_territory=germany. Session altered.---------S.King 24. "alter session set nls_date_format=’YYYY-MM-DD HH24:MI:SS’").

'//localhost/XE'). Session altered.User Presenting Data Using Conventions Expected by the numformat. oci_execute($s). $s = oci_parse($c.567" float(123.567" float(123) If NLS_TERRITORY had instead been set to america the output would have been correct: string(7) "123. 'hrpwd'. $n1 = $r['NUM']. var_dump($n1). ?> // value as fetched // now cast it to a number The output is: string(7) "123. oci_execute($s). "alter session set nls_territory=germany"). $s = oci_parse($c. or the value of NLS_NUMERIC_CHARACTERS. SQL> alter session set nls_sort=binary. $r = oci_fetch_assoc($s). l and n. ordered after c. var_dump($n2).567) The problem can also occur depending on the territory component of NLS_LANG. The following examples illustrate the effect of using a Spanish sort against the employee names Chen and Chung. last_name "Last Name" from employees where last_name like 'C%' order by last_name Last Name ------------------------Cabrio Cambrault 167 EMPID ---------187 148 . respectively. $n2 = (float)$n1. "select 123. SQL> 2 3 4 5* select employee_id EmpID. ll as well as ñ as unique letters. The latter variable can be used to override the number format while other territory settings remain in effect.php <?php $c = oci_connect('hr'.567 as num from dual"). Oracle Linguistic Sorts Spain traditionally treats ch.

the server message appears as follows: ORA-00942: table ou vue inexistante For more discussion of globalization support features in Oracle Database XE. Session altered. 168 . SQL> 2 3 4 5* select employee_id EmpID. Consider the following server message: ORA-00942: table or view does not exist When the NLS_LANGUAGE parameter is set to French. SQL> alter session set nls_sort=spanish_m.Globalization 154 110 188 119 Cambrault Chen Chung Colmenares 6 rows selected. Setting this parameter prior to submitting your SQL statement ensures that the language-specific database error messages will be returned to the application. last_name "Last Name" from employees where last_name like 'C%' order by last_name Last Name ------------------------Cabrio Cambrault Cambrault Colmenares Chen Chung EMPID ---------187 148 154 119 110 188 6 rows selected. Oracle Error Messages The NLS_LANGUAGE parameter also controls the language of the database error messages being returned from the database. see Working in a Global Environment in the Oracle Database Express Edition 2 Day Developer Guide.

c:128) OCI8 DEBUG: OCIAttrGet at (/tmp/php5.1/ext/oci8/oci8_statement.2.c:1253) OCI8 DEBUG: OCISessionBegin at (/tmp/php-5.1/ext/oci8/oci8.CHAPTER 14 Tracing OCI8 Internals To see exactly what calls to the Oracle database the OCI8 extension makes.c:119) OCI8 DEBUG: OCIAttrSet at (/tmp/php5. "//localhost/XE"). This is mostly useful for the maintainers of the OCI8 extension.1/ext/oci8/oci8.c:1151) OCI8 DEBUG: OCIHandleAlloc at (/tmp/php-5.c:1213) OCI8 DEBUG: OCIAttrSet at (/tmp/php-5.1/ext/oci8/oci8_statement.1/ext/oci8/oci8.1/ext/oci8/oci8. "hrpwd". $s = oci_parse($conn. // turn on tracing $conn = oci_connect("hr".c:321) OCI8 DEBUG: OCIStmtRelease at (/tmp/php5.2.c:1244) OCI8 DEBUG: OCIAttrSet at (/tmp/php-5.2. OCI_DEFAULT).1/ext/oci8/oci8.1/ext/oci8/oci8_statement. Enabling OCI8 Debugging output Tracing can be turned on in your script with oci_internal_debug().c:1223) OCI8 DEBUG: OCIAttrSet at (/tmp/php-5.2.1/ext/oci8/oci8.2.2.1/ext/oci8/oci8.2. For a script that connects and does an insert: <?php oci_internal_debug(1).c:995) OCI8 DEBUG: OCIEnvNlsCreate at (/tmp/php-5.2.c:1176) OCI8 DEBUG: OCIServerAttach at (/tmp/php-5.c:589) 169 .2.1/ext/oci8/oci8_statement.c:1185) OCI8 DEBUG: OCIHandleAlloc at (/tmp/php-5.2.1/ext/oci8/oci8_statement. oci_execute($s.1/ext/oci8/oci8_statement. "insert into testtable values ('my data')").1/ext/oci8/oci8.1/ext/oci8/oci8.2.2.2.1/ext/oci8/oci8.2.c:65) OCI8 DEBUG: OCIAttrSet at (/tmp/php5.c:61) OCI8 DEBUG: OCIStmtPrepare2 at (/tmp/php5.2.1/ext/oci8/oci8.c:297) OCI8 DEBUG: OCIStmtExecute at (/tmp/php5.2.1/ext/oci8/oci8.c:1204) OCI8 DEBUG: OCIHandleAlloc at (/tmp/php-5.c:1234) OCI8 DEBUG: OCIAttrSet at (/tmp/php-5.2.1/ext/oci8/oci8_statement.c:1284) OCI8 DEBUG: OCIHandleAlloc at (/tmp/php5.2. you can turn on debugging output.2.c:1195) OCI8 DEBUG: OCIHandleAlloc at (/tmp/php-5. // do not auto-commit ?> You get output like: OCI8 DEBUG: OCINlsEnvironmentVariableGet at (/tmp/php5.

2.2.c:1468) OCI8 DEBUG: OCIHandleFree at (/tmp/php-5.2. thus saving a roundtrip.1/ext/oci8/oci8.Tracing OCI8 Internals OCI8 DEBUG: OCIHandleFree at (/tmp/php5.1/ext/oci8/oci8. 170 .1/ext/oci8/oci8_statement.c:1456) OCI8 DEBUG: OCIHandleFree at (/tmp/php-5.1/ext/oci8/oci8.2. but some require a “round trip” to the database.c:1460) OCI8 DEBUG: OCIHandleFree at (/tmp/php-5.1/ext/oci8/oci8. If you change to auto-commit mode you will not see a call to OCITransCommit() because the commit message is piggy-backed with the execution call.c:1400) OCI8 DEBUG: OCISessionEnd at (/tmp/php-5. As part of PHP’s end of HTTP request shutdown at the conclusion of the script.c:1448) OCI8 DEBUG: OCIHandleFree at (/tmp/php-5.2.1/ext/oci8/oci8.1/ext/oci8/oci8.2.2. The OCI_DEFAULT flag said not to auto-commit and there was no explicit oci_commit() call.2.2. If a script only inserts one row it is fine to auto-commit. Otherwise. the rollback was issued.c:1452) OCI8 DEBUG: OCIServerDetach at (/tmp/php-5. do the transaction management yourself.c:1472) Many of these calls just allocate local resources (“handles”) and set local state (“attributes”).1/ext/oci8/oci8. One of these is the OCITransRollback() call near the end of the script.1/ext/oci8/oci8.c:1464) OCI8 DEBUG: OCIHandleFree at (/tmp/php-5.c:601) OCI8 DEBUG: OCITransRollback at (/tmp/php-5.

It is also a good idea to proactively test your applications with PHP “release candidates” and report problems so they can be fixed before each final PHP release.CHAPTER 15 Testing PHP and the OCI8 Extension This section discusses installing and running the PHP source code tests for OCI8 on Linux. types. This gives load and real-life testing not possible with PHP’s command-line test suite. then also set: $oracle_on_localhost = TRUE. You should run the tests after building PHP on Linux. For the tests to run successfully.2/ext/oci8/tests verify the behavior of the OCI8 extension. stored procedures.inc and set the Oracle system user password for your database: $user = "system". If the database and PHP are not using the same file system. This specifies whether to test functionality that has the Oracle database reading files created directly by PHP. If PHP is running on the same machine as the database.inc file. The PHP source code includes tests for all the core functionality and extensions. In older versions of PHP these variables are located in connect. you may have to grant that database user extra privileges.inc. To run the OCI8 tests: 1. this is not possible and the variable should be left FALSE. This ensures PHP continues doing what you need.2/ext/oci8/tests/details. Edit php-5. 2. 4. You should also verify your applications work correctly with your new PHP binary before putting it into production. and so on. $password = "systempwd". Consider contributing new tests to the PHP community. Adding tests that are relevant to your application reduces the risks of PHP developers breaking PHP features important to you. 3. The tests rely on being able to create tables.ini configuration may also be needed. 171 . password and connect string for your database need to be configured.2. At the end of the of the details. Some php. the username. Running OCI8 Tests The tests in php-5. If you change the $user variable.2. set the connection string for the database: $dbase = "//localhost/XE".

EL INI actual : /usr/local/apache/conf/php. for example: variables_order = "EGPCS" Without this flag. Failing tests are marked FAIL.2. The output of failing tests is kept for your 172 . Successful tests begin with PASS. Tests that are to be skipped in the current configuration are marked SKIP.9-42.INIs : Extra dirs : ============================================================== Running selected tests.2/sapi/cli/php PHP_SAPI : cli PHP_VERSION : 5.phpt] PASS oci_bind_array_by_name() and invalid values 2 [ext/oci8/tests/array_bind_002.Testing PHP and the OCI8 Extension 5.2.10.0. For example.2 make test If you want to run just the OCI8 tests use: make test TESTS=ext/oci8 Each test script is executed and its status reported.0/server . 7.2.2.2.ini.Linux localhost 2. $OH/bin/oracle_env.0 PHP_OS : Linux .phpt] .2 PHP : /home/myhome/php-5.sh Note the space after the full stop.. ============================================================== CWD : /home/myhome/php-5. These might be for unfixed bugs. A summary of the failing tests is given at the completion of the tests.0.2. the Oracle environment variables are not propagated through the test system and tests fail to connect..1. PASS oci_bind_array_by_name() and invalid values 1 [ext/oci8/tests/array_bind_001.ini More . Run PHP’s test suite with: cd php-5.6. Set any necessary Oracle environment variables in your shell.phpt] PASS oci_bind_array_by_name() and invalid values 3 [ext/oci8/tests/array_bind_003. Tests that Fail Occasionally a few tests are known to fail. 6.2 ZEND_VERSION : 2. or where portability of the test cannot be guaranteed. for PHP linked with Oracle Database XE enter: export OH=/usr/lib/oracle/xe/app/oracle/product/10. Check that variables_order has E in your php.

2/ext/oci8/tests using the test file format. echo "Done\n".exp demotest. For example.phpt file in php-5. The FILE section is the PHP code to be executed. create a .phpt: demotest.phpt --TEST— Demo to test the Test system --SKIPIF— <?php if (!extension_loaded('oci8')) die("skip no oci8 extension"). 173 .2/ext/oci8/tests: Table 15-1 Test files and their contents File name demotest.phpt file Difference between actual and expected output Actual and expected output in a single file Creating a Test To add a new OCI8 test. oci_fetch_all($s.2.phpt fails.inc'. ?> --EXPECTF-array(1) { ["USER"]=> array(1) { [0]=> string(6) "SYSTEM" } } Done The test begins with a comment that is displayed when the test is run.out demotest. ?> --FILE-<?php require dirname(__FILE__).Creating a Test analysis. For example. $s = oci_parse($c. the following files will be in php5. oci_execute($s).'/connect.2. $res). if ext/oci8/tests/demotest. "select user from dual").diff demotest.php demotest.phpt demotest. var_dump($res). The SKIPIF section causes the test to be skipped when the OCI8 extension is not enabled in PHP.log File Contents Test framework script PHP file executed Test output Expected output as coded in the . create demotest. The EXPECTF section has the expected output.

Making a test portable.net/write-test.2 ZEND_VERSION : 2.phpt] =================================================================== Number of tests :1 1 174 . Writing good units tests is an art. Application level testing brings even more challenges.2.Linux localhost 2. They include PHPUnit and SimpleTest.2.2/ext/oci8/tests/connect.2.php.ini More .2.EL INI actual : /usr/local/apache/conf/php.inc will connect to Oracle as $user and return the connection resource in $c.INIs : Extra dirs : =================================================================== Running selected tests. the same PHP binary is used to run the controlling runtests.10.phpt The TEST_PHP_EXECUTABLE variable contains the PHP binary with which to test demotest.phpt.0 PHP_OS : Linux . do the following: export TEST_PHP_EXECUTABLE=/home/myhome/php-5.inc drop_type. There are several other scripts for creating and dropping basic tables and types: * * * * create_table. The test output is similar to the previous output: =================================================================== CWD : /home/myhome/php-5. including arguments and php.9-42.2 PHP : /home/myhome/php-5. There are several PHP test frameworks with sophisticated features that might be more suited to your application test suites.phpt script. to run the demotest.php. call the run-tests.ini settings. PASS Demo to test the Test system [ext/oci8/tests/demotest.inc create_type.inc Running a Single Test To run only one or two tests.2/sapi/cli/php run-tests. When you run make test the new file is automatically run.2/sapi/cli/php /home/myhome/php-5.inc drop_table. This page also has generic examples and helpful information on writing tests.6.2.php script. Please send new tests or issues with PHP’s test suite to php-qa@lists.2/sapi/cli/php PHP_SAPI : cli PHP_VERSION : 5. In example 1-1.php for the other sections the test file can have. simple and selfdiagnosing requires fine judgment and tidy programming.1. For example. OCI8 Test Helper Scripts The file php-5.Testing PHP and the OCI8 Extension See Writing Tests at http://qa.php script directly and pass the test names as parameters.net.0.2.0. accurate.2.php \ ext/oci8/tests/demotest. but they could be different executables.

For the errors above. 100: SQL> alter system set processes=100 scope=spfile.----------.0%) -------Tests warned :0 ( 0. 175 . Increase the value to. This may be noticeable with Oracle Database XE.0%) ------------------------------------------------------------------Time taken :0 seconds =================================================================== Configuring the Database For Testing Sometimes it is possible for rapidly executing OCI8 test scripts to flood the database with connections. Random tests fail with errors like the following: ORA-12516 TNS:listener could not find available handler with matching protocol stack ORA-12520: TNS:listener could not find available handler for requested type of server A quick solution is to add sleep(1). Use SQL*Plus to connect as a privileged database user: sqlplus / as sysdba 4. for example: export OH=/usr/lib/oracle/xe/app/oracle/product/10.0%) ( 0. to details. To increase the number of processes in Oracle: 1.0/server . System altered.2.0%) (100. Set the Oracle environment variables needed by SQL*Plus.0%) Tests passed :1 (100.. $OH/bin/oracle_env.0%) ( 0. the number of “processes” that Oracle can handle needs to be increased. You may need to su as the oracle user so you have operating system privileges to start SQL*Plus: su –oracle Password: ****** 2. Check the current value of processes using the SHOW PARAMETER PROCESSES command: SQL> show parameter processes NAME TYPE VALUE ------------------------. say.0%) Tests failed :0 ( 0..----------. The preferred solution is to configure the database to suit the load.Configuring the Database For Testing Tests skipped :0 ( 0.sh 3. which has smaller defaults. processes integer 40 5.inc so scripts take an extra second and the database has time to clean up closed connections.

. Restart the database using the SHUTDOWN IMMEDIATE. Exit SQL*Plus using the EXIT command: SQL> exit 9. 7. Database dismounted. Now the tests can be run again: make test TESTS=ext/oci8 176 .----------. processes integer 100 8.---------. SQL> startup ORACLE instance started. Database opened. Total System Global Area 289406976 bytes Fixed Size 1258488 bytes Variable Size 96472072 bytes Database Buffers 188743680 bytes Redo Buffers2932736 bytes Database mounted. followed by the STARTUP command: SQL> shutdown immediate Database closed.. ORACLE instance shut down.Testing PHP and the OCI8 Extension 6. Use the SHOW PARAMETER PROCESSES command to confirm the new value is in effect: SQL> show parameter processes NAME TYPE VALUE ------------------------.

so PHP 4 scripts do not necessarily need to be changed. you should replace the OCI8 code with the new version to get improved stability and performance optimizations.2 onwards builds and runs with PHP 4 too. Operation Connection Action PHP 4 Name PHP 5 Name oci_connect() oci_new_connect() oci_pconnect() Open connection ocilogon() Open new connection ocinlogon() Persistent connection ociplogon() Close connection ocilogoff() (and new php. Steps to do this are given in this book. The refactored OCI8 extension in PHP 5. and so on. check both manual pages for user tips. One side effect of renaming the function names is that user contributed comments in the PHP manual (http://www. OCIParse() became oci_parse(). The old OCI8 names still exist as aliases. Function names in PHP are case insensitive and it is common to see the PHP 4 names written with a capitalized prefix.CHAPTER 16 OCI8 Function Names in PHP 4 and PHP 5 In PHP 5 several extensions including OCI8 underwent name standardization.net/oci8) are found in two different places. PHP 4 functions like OCILogin() became oci_connect().php. or on the page for the new syntax. Where a function has an alias.1. If you are using PHP 4 and cannot upgrade to PHP 5.ini parameters) oci_close() oci_new_cursor() oci_free_statement() Cursor Open cursor ocinewcursor() Close cursor ocifreecursor() 177 . Table 16-1 Relationship between OCI8’s PHP 4 and PHP 5 function names. The comments are either on the page for the old syntax. Table 16-1 shows the OCI8 function names in PHP 4 and PHP 5 where names or functionality differ.

OCI8 Function Names in PHP 4 and PHP 5 Operation Action PHP 4 Name ocifreestatement() PHP 5 Name Parsing Binding Parse statement Bind variable ociparse() ocibindbyname() oci_parse() oci_bind_by_name() oci_bind_array_by_name() Bind array Not applicable Defining Define output variables Execute statement Fetch row ocidefinebyname() oci_define_by_name() Execution Fetching ociexecute() ocifetch() oci_execute() oci_fetch() oci_fetch_array() oci_fetch_row() oci_fetch_assoc() oci_fetch_object() oci_fetch_all() oci_result() Fetch row ocifetchinto() Fetch all rows Fetch column Is the column NULL? Cancel Fetch Transaction Management Commit Rollback Descriptors ocifetchstatement() ociresult() ocicolumnisnull() oci_field_is_null() ocicancel() ocicommit() ocirollback() ocinewdescriptor() ocifreedesc() oci_cancel() oci_commit() oci_rollback() oci_new_descriptor() oci_free_descriptor() oci_error() Error Handling Long Objects (LOBs) Note: Methods on a collection object ocierror() ocisavelob() oci_lob_save() 178 .

ocinewcollection() oci_new_collection() ocifreecollection() ocicollappend() ocicollgetelem() ocicollassign() oci_free_collection() oci_collection_append() oci_collection_element_get() OCI-Collection->assign() method oci_collection_element_assig n() oci_collection_size() oci_collection_max() oci_collection_trim() oci_statement_type() ocicollassignelem() ocicollsize() ocicollmax() ocicolltrim() Metadata Statement type Name of result column Size of result ocistatementtype() ocicolumnname() oci_field_name() ocicolumnsize() oci_field_size() 179 .Configuring the Database For Testing Operation can be used in addition to these functions. Action PHP 4 Name PHP 5 Name ocisavelobfile() ociwritelobtofile() ociwritetemporarylob() ociloadlob() ocicloselob() oci_lob_import() oci_lob_export() OCI-Lob->writeTemporary() method oci_lob_load() OCI-Lob->close() method Collections Note: Methods on a collection object can be used in addition to these functions.

ini parameter) 180 .OCI8 Function Names in PHP 4 and PHP 5 Operation Action column PHP 4 Name PHP 5 Name Datatype of result ocicolumntype() column Datatype of result ocicolumntyperaw() column Precision of result ocicolumnprecision() column Scale of result column oci_field_type() oci_field_type_raw() oci_field_precision() ocicolumnscale() oci_field_scale() Number of rows ocirowcount() effected Number of columns ocinumcols() returned Changing Password Tracing Server Version Tuning ocipasswordchange() ociinternaldebug() ociserverversion() oci_num_rows() oci_num_fields() oci_password_change() oci_internal_debug() oci_server_version() oci_set_prefetch() ocisetprefetch() (and new php.

Paying some attention to transaction management and connection handling is wise to make sure all your data is committed when you expect it to be. The functionality it offered was limited.ini parameters) oci_close() oci_new_cursor() oci_free_statement() oci_parse() oci_bind_by_name() oci_bind_array_by_name() ora_logoff() ora_open() ora_close() Parse statement ora_parse() Bind variable Bind array ora_bind() Not applicable 181 . Oracle and OCI8 Comparison Table 17-1 shows the general relationship between the obsolete and current extensions. Table 17-1 Relationship between current and obsolete Oracle extensions Operation Connection Action Open connection Open new connection Persistent connection Close connection Cursor Open cursor Close cursor Parsing Binding ORA function (obsolete) ora_logon() OCI8 function oci_connect() oci_new_connect() oci_pconnect() Not available ora_plogon() (and new php. and changing the ora_ function calls in your scripts.CHAPTER 17 The Obsolete Oracle Extension Very rarely you might come across PHP scripts that use the early Oracle extension. This chapter gives a comparison of the obsoleted Oracle PHP extension and the current OCI8 extension. and upgrading to the new OCI8 extension might be as simple as enabling the newer OCI8 extension in the PHP binary. This extension is obsolete and is no longer included with PHP.

The Obsolete Oracle Extension Operation Execution Action Execute statement ORA function (obsolete) ora_exec() OCI8 function oci_execute() oci_parse() oci_execute() Followed by one of: Prepare. execute ora_do() and fetch oci_fetch_all() oci_fetch_array() oci_fetch_assoc() oci_fetch_object() oci_fetch_row() oci_fetch() oci_fetch() oci_fetch_array() oci_fetch_row() oci_fetch_assoc() oci_fetch_object() oci_fetch_all() oci_result() oci_field_is_null() oci_cancel() oci_commit() Fetching Fetch row ora_fetch() Fetch row ora_fetch_into Fetch all rows Fetch column Is the column NULL? Cancel Fetch Transaction Commit Management Commit mode Rollback Error Handling Not applicable ora_getcolumn() Not applicable Not applicable ora_commit() ora_commiton() ora_commitoff() ora_rollback() ora_error() ora_errorcode() Pass OCI_DEFAULT flag to oci_execute() oci_rollback() oci_error() OCI-Lob->append OCI-Lob->close OCI-Lob->eof OCI-Lob->erase OCI-Lob->export OCI-Lob->flush OCI-Lob->free OCI-Lob->getBuffering Long Objects (LOBS) Not applicable 182 .

Oracle and OCI8 Comparison Operation Action ORA function (obsolete) OCI8 function OCI-Lob->import OCI-Lob->load OCI-Lob->read OCI-Lob->rewind OCI-Lob->save OCI-Lob->saveFile OCI-Lob->seek OCI-Lob->setBuffering OCI-Lob->size OCI-Lob->tell OCI-Lob->truncate OCI-Lob->write OCI-Lob->writeTemporary OCI-Lob->writeToFile OCI-Collection->append OCI-Collection->assign OCI-Collection->assignElem OCI-Collection->free OCI-Collection->getElem OCI-Collection->max OCI-Collection->size OCI-Collection->trim oci_statement_type() oci_field_name() oci_field_size() oci_field_type() oci_field_type_raw() oci_field_precision() oci_field_scale() oci_num_rows() Collections Not applicable Metadata Statement type Not applicable Name of result ora_columnname() column Size of result column Datatype of result column Precision of result column Scale of result column ora_columnsize() ora_columntype() Not applicable Not applicable Number of rows ora_numrows() effected Number of columns returned Changing Password ora_numcols() oci_num_fields() Not applicable oci_password_change() 183 .

ini parameters) 184 .The Obsolete Oracle Extension Operation Tracing Server Version Tuning Action ORA function (obsolete) Not applicable Not applicable OCI8 function oci_internal_debug() oci_server_version() oci_set_prefetch() Not applicable (and new php.

CLOBs store database character set data. they are generally for one-time use. Binding A method of including data in SQL statements that allows SQL statements to be efficiently reused with different data. Collection Type A collection is an ordered group of elements. Connection String The string used to identify which database to connect to. Data Dictionary A set of tables and views that are used as a read-only reference about the database. all of the same type. Although you may have more than one database per machine. A BFILE column or attribute stores a file locator that points to an external file containing the data. Each element has a unique subscript that determines its position in the collection. lists. PL/SQL datatypes TABLE and VARRAY enable collection types such as arrays. Because these blocks are not stored in the database. PL/SQL blocks can appear wherever SQL statements can appear. and NCLOBs store Unicode national character set data. BFILE The BFILE datatype stores unstructured binary data in operating-system files outside the database. BLOB The BLOB datatype stores unstructured binary data in the database. sets and trees. CHAR The CHAR datatype stores fixed-length character strings. nested tables. Database A database stores and retrieves data. Each database consists of one or more data files. bags.Glossary Anonymous Block A PL/SQL block that appears in your application and is not named or stored in the database. CLOB and NCLOB The CLOB and NCLOB datatypes store up to 8 terabytes of character data in the database. typically a single Oracle 185 . A PL/SQL block groups related declarations and statements. In many applications.

SQL statements that define or manage the data in the database. INSERT. Easy Connect A simple hostname or database name string that is used to identify which database to connect to. In the PHP world. Database Link A pointer that defines a one-way communication path from an Oracle Database server to another database server. DDL SQL’s Data Definition Language. you must specify a datatype for each of its columns. or DATE DATE The DATE datatype stores point-in-time values (dates and times) in a table. and a valid range of values. Database Name The name of the database. a system global area (SGA) is allocated and Oracle 186 . This person is a specialist in Oracle databases. Instance The Oracle Instance is the running component of an Oracle database server. like CREATE. Multiple applications can use the same database without any conflict by using different schemas. Indexes can be created to increase the performance of data retrieval. A person who administers the Oracle database. UPDATE and DELETE. this is the text used in oci_connect() calls. HR The Human Resources user created by default with an Oracle seed database installation. DML SQL’s Data Manipulation Language. SQL statements that define the database structure or schema. When you create a table. Datatype Each column value and constant in a SQL statement has a datatype. DBA Database Administrator.Glossary database contains multiple schemas. When an Oracle database is started. which is associated with a specific storage format. and would usually have SYSDBA access to the database. For example. constraints. ALTER. Also see Easy Connect. like SELECT. Index Indexes are optional structures associated with tables. NUMBER. A database link connection allows local users to access data on a remote database. and DROP. A schema is often equated with a user. The hr user has access to the Human Resources demonstration tables in the HR schema.

stored together in the database for continued use as a unit. which does not take up any storage space or contain any data. LOBS may be persistent (stored in the database) or temporary. Instant Client The Oracle Instant Client is a small set of libraries. An Oracle Instant Client install is not required to be in an Oracle Home. A subset of the full Oracle Client. Packages A package is a group of related procedures and functions. Instant Client is downloadable from OTN and is usable and distributable for free. NUMBER The NUMBER datatype stores fixed and floating-point numbers. which allow you to connect to an Oracle Database. The privilege to delete rows from the departments table is an example of an object privilege. demonstration scripts and error message files for each component of Oracle. NCHAR and NVARCHAR2 NCHAR and NVARCHAR2 are Unicode datatypes that store Unicode character data. The combination of the background processes and memory buffers is called an Oracle instance. See CLOB. LOB A large object. Different object privileges are available for different types of schema objects. it requires minimal installation but has full functionality. stored in the database. Object Privilege A right to perform a particular action on a specific schema object. a materialized view contains the rows resulting from a query against one or more base tables or views. Materialized View A materialized view provides access to table data by storing the results of a query in a separate schema object. These installs contain all required software in a directory hierarchy. This set of directories includes binaries.background processes are started. grouped together. and run as a unit to solve a specific problem or perform a set of related tasks. utilities. BLOB and BFILE. Procedures and Functions A PL/SQL procedure or function is a schema object that consists of a set of SQL statements and other PL/SQL constructs. ORACLE_HOME install An Oracle Client or Oracle Database install. Any 187 . along with the cursors and variables they use. configuration scripts. LOB Locator A “pointer” to LOB data. Unlike an ordinary view.

interpreted scripting language commonly used for web applications. stored procedural language that enables you to mix SQL statements with procedural constructs. Prepared Statement A pre-parsing step for SQL statements.ini The configuration file used by PHP. functions. Php. stored functions. PHP A popular. and variable definitions stored in the Oracle database.ini can also be set at runtime using ini_set(). This term is often used with non-Oracle databases. procedures. 188 . PEAR The PHP Extension and Application Repository (PEAR) is a repository for reusable packages written in PHP. and packages.Glossary program using Oracle typically requires the ORACLE_HOME environment variable to be set to the top level installation directory. Package A group of PL/SQL procedures. PECL The PHP Extension Community Library (PECL) is a repository of PHP extensions that can be linked into the PHP binary. functions. OTN The Oracle Technology Network is Oracle’s free repository of articles on Oracle technologies. With PL/SQL. Regular Expression A pattern used to match data. stored procedures. and variables in packages can be called from other packages. or functions. Many (but not all) options that are set in php. and packages. PHP is a recursive acronym for “PHP: Hypertext Preprocessor”. It is a server-side. functions. Oracle Net The networking component of Oracle that connects client tools such as PHP to local or remote databases. It also hosts many discussion forums. PL/SQL program units generally are categorized as anonymous blocks. Procedures. Oracle has several functions that accept regular expressions. The Oracle Net listener is a process that handles connection requests from clients and passes them to the target database. In Oracle it is called parsing. including one on PHP. you can create and run PL/SQL program units such as procedures. PL/SQL Oracle’s procedural language extension to SQL.

Functions are different than procedures in that functions return a value when executed. Schema objects include structures like tables. Oracle parses the procedure or function. Synonym A synonym is an alias for any table. type. SID The system identifier is commonly used to mean the database name alias in the connection string. 189 . Schema objects are the logical structures that directly refer to the database's data. sequence. SYSOPER Similar to sysdba. SID also stands for session identifier. and indexes. function.Schema A schema is a collection of database objects. is assigned only to the sys user. SYS An administrative user account name. but with a limited set of privileges that allows basic administrative tasks without having access to user data. or another synonym. user-defined object type. It enables sys to perform high-level administrative tasks such as starting up and shutting down the database. and stores its parsed representation in the database. SQL*Plus The traditional command line tool for executing SQL statements available with all Oracle databases. the unique number assigned to each database user session when they connect to the database. Although recently superceded by GUI tools like Oracle’s free SQL Developer. When you create a stored procedure or function. sys has access to all base tables and views for the database data dictionary. SYSTEM An administrative user account name that is used to perform all administrative functions other than starting up and shutting down the database. by default. A schema is owned by a database user and has the same name as that user. package. view. It is also convenient to show examples using SQL*Plus. materialized view. procedure. SQL*Plus remains hugely popular. SYSDBA A system privilege that. views. Java class schema object. Sequence A sequence (a sequential series of numbers) of Oracle integers of up to 38 digits defined in the database. Stored Procedures and Functions A PL/SQL block that Oracle stores in the database and can be called by name from an application.

view. Views do not actually contain data. Users are assigned a default tablespace that holds all the data the users creates. The trigger can be called before the event. the privileges to create tables and to delete the rows of any table in a database. Tnsnames. in the database. TNS stands for Transparent Network Substrate.Glossary System privilege The right to perform a particular action. 190 . to prevent erroneous operations or fix new data so that it conforms to business User A database user is often equated to a schema. VARCHAR and VARCHAR2 These datatypes store variable-length character strings. Database tables hold all user-accessible data. and so on. Temporary LOB See LOB. Tablespace Tablespaces are the logical units of data storage made up of one or more datafiles. A view can also be considered a stored query. Trigger A stored procedure associated with a database table.ora The Oracle Net configuration file used for connecting to a database. referred to as the base tables of the views. The alias is used in the PHP connection string. For example. to record it. The trigger can be called after the event. Transaction A sequence of SQL statements whose changes are either all committed. The file maps an alias to a local or remote database and allows various configuration options for connections. A database is made up of default and DBA-created tablespaces. Rather. View Views are customized presentations of data in one or more tables or other views. or take some follow-up action. or event. they derive their data from the tables on which they are based. Tablespaces are often created for individual applications because tablespaces can be conveniently managed. Table Tables are the basic unit of data storage. The names are currently synonyms but VARCHAR2 is recommended to ensure maximum compatibility of applications in future. or all rolled back. Each table has columns and rows. or to perform an action on any schema objects of a particular type. and has access to tables. Each user connects to the database with a username and secret password.

XMLType XMLType is a datatype that can be used to store XML data in table columns. 191 .

.

oracle.oracle.com/pls/xe102/homepage Oracle Documentation Portal http://tahiti.php.html Blog: Christopher Jones on OPAL http://blogs.oracle.oracle.com/opal/ Blog: Alison Holloway on PHP http://blogs.com/database/product_editions.com/ Oracle Database Editions http://www.oracle. General Information and Forums * * * * * * * PHP Developer Center on Oracle Technology Network (OTN) http://www.oracle.com/ Oracle Net Services Administrator's Guide http://download.html OTN PHP Discussion Forum http://www.2) Documentation (Oracle Database XE) http://www.102/b14212/toc.com/technology/forums/php.102/b25317/toc.oracle.oracle.php Oracle Database Express Edition 2 Day Plus PHP Developer Guide http://download.htm 193 * * * .com/alison/ AskTom – General Oracle language and application design help http://asktom.oracle.Resources This chapter gives links to documentation.net/docs.oracle.oracle.htm Oracle Database Express Edition 10g Release 2 (10. resources and articles discussed in this book.com/ Oracle Metalink – Oracle Support web site http://metalink.com/technology/tech/php/index.net/oci8 PHP documentation http://www. and to other web sites of interest.com/docs/cd/B19306_01/network.com/docs/cd/B19306_01/network.102/b14213/toc.php.html Documentation * * * * PHP OCI8 documentation http://www.htm Oracle Net Services Reference http://download.oracle.com/docs/cd/B25329_01/doc/appdev.

Resources * Oracle Database Net Services Administrator’s Guide 10g Release 2 (10.htm * PHP and Oracle Books * * Oracle Database 10g Express Edition PHP Web Programming. Osbourne Oracle Press. by Wez Furlong http://www. Currently in its 4th edition.102/b14212/naming.oracle.oracle. 2006 Easy Oracle PHP: Create Dynamic Web Pages with Oracle Data. * * * * * Source and Binaries * * Zend Core for Oracle http://www.net/downloads.com/technology/tech/php/htdocs/php_troubleshooting_faq.com/technology/pub/articles/php_experts/otn_pdo_oracle5.com/technology/pub/articles/oracle_php_cookbook/coggeshall_p ersist. Articles and Other References * * * Oracle PHP Troubleshooting FAQ http://www.oracle. Mladen Gogala.php 194 .oracle.html Using PHP 5 with Oracle XML DB by Yuli Vasiliev http://www. O’Reilly Press.htm# i498306 Oracle Database SQL Reference http://download.com/tkyte/autonomous/index.pdf Using PHP5 with Oracle XML DB http://www.oracle.com/technology/tech/php/pdf/globalizing_oracle_php_applicatio ns.com/technology/oramag/oracle/05-jul/o45php. Improving Performance Through Persistent Connections by John Coggeshall http://www. Rampant TechPress.html Autonomous transactions in Oracle http://asktom.oracle.com/technology/oramag/oracle/05-jul/o45php. Michael McLaughlin.html An Overview on Globalizing Oracle PHP Applications http://www.oracle.com/technology/tech/php/zendcore/ PHP versioned releases (source and Windows binaries) http://www.oracle.102/b14200/toc.html.html Oracle PL/SQL Programming by Steven Feuerstein.2) – Easy Connect Naming Method http://download.php.com/docs/cd/B19306_01/network.com/docs/cd/B19306_01/server. 2006 Other PHP and Oracle books are due to be published in 2007.oracle.oracle.html The PHP 5 Data Object (PDO) Abstraction Layer and Oracle.

net/package/PDO_OCI Windows PDO_OCI DLLs matching PECL PDO_OCI snapshots http://pecl4win.php.com/technology/products/jdev/htdocs/partners/addins/exchange/ php/index.dll PECL PDO_OCI source snapshot http://pecl.php PHPUnit PHP unit tester http://www.net/package/oci8 Windows OCI8 DLLs matching PECL oci8 snapshots http://pecl4win.org/ Utilities * PHP Extension for JDeveloper http://www.cgi/php-src/ext/oci8/ Snapshots of PHP's source code and Windows binaries http://snaps.php.php.net/ PHP Quality Assurance Site http://qa.oracle.net/viewcvs.phpunit.com/technology/tech/oci/instantclient/ PHP * * * * * PHP Home Page http://www.php/php_oci8.php.html 195 .php.php.php.net/ PHP Bug system http://bugs.de/ SimpleTest PHP unit tester http://www.net/ext.net/ext.net/ PECL OCI8 source snapshot http://pecl.dll Oracle Instant Client http://www.net/search.* * * * * * * OCI8 source code in CVS http://cvs.oracle.php/php_pdo_oci.php.php.simpletest.

Sign up to vote on this title
UsefulNot useful