Archive for the ‘xe’ tag
Oracle XE Gateway Debug Mode
When developing Web applications using Oracle XE and the embedded PL/SQL gateway, you may find that debugging is a pain due to the lack of log files (like you’d normally find in Apache folders in a full Oracle application server install). Well, the good news is, that you can configure errors to be reported directly in the browser, so that rather than getting very unhelpful 404 and other HTTP error messages, you get a full debug trace of the error that occurred. Full credit for this find goes to Dietmar Aust, who has a great blog on Oracle XE and Application Express. See his original post for even more insight into this.
To switch on error reporting and the printing of debug messages to the browser, simply issue the following commands. Of course, be sure to replace “embosa” on line 3 with your own DAD name. Also, be sure to turn this back off again in a production environment, this should only be used for development and testing purposes.
begin
dbms_epg.set_global_attribute('log-level', 3);
dbms_epg.set_dad_attribute('embosa', 'error-style', 'DebugStyle');
end;
/
To test, simply go to a URL that doesn’t exist, and you should see a useful error message instead of a unhelpful “Not Found” message. See the screenshot below for an example of what this error message looks like.
Oracle XE and mod_plsql
In this post you will learn how to get a sandboxed PL/SQL web development environment up and running on a Windows machine. You will use the VMware Player virtualization system to run an Ubuntu 9.10 server image, on which you will install Oracle XE. You will then configure a DAD using DBMS_EPG which basically acts in the same way as mod_plsql does in Oracle HTTP Server. This will allow you to create Web applications using PL/SQL. Finally, you will learn how to work with virtual directories so you can store things like images, external stylesheets and external JavaScript files.
The first step you need to follow is to download and install the free VMware Player application on your system. This can be downloaded from https://www.vmware.com/tryvmware/?p=player&lp=1. Once this has downloaded, follow the simple instructions to install VMware Player. This application allows you to run other operating systems that are packaged in virtual machine images. Head over to http://www.thoughtpolice.co.uk/vmware/#ubuntu9.10 and download the appropriate image for Ubuntu 9.10 Karmic Koala. When this has finished downloading, extract the files to a convenient location on your file system, and find the file ubuntu-server-9.10-i386.vmx, and double-click it to start the virtual machine.
At this point, VMware Player should open and your Ubuntu VM will launch and boot up. After a few moments, you should see a prompt like the one shown in Figure 1:

Figure 1 - Ubuntu Login Prompt
To login, enter the login notroot and the password thoughtpolice. You will now be logged in and should see the Ubuntu shell prompt.
By default, the VM image you are using has 905208 bytes of swap space allocated. Unfortunately, this will cause the Oracle XE installer to fail, as its minimum is 1024MB. To prevent this from happening, you first need to assign some more swap space. Use the following commands to bump up the swap space to 1058800 bytes. If you are asked for your [sudo] password for notroot (you will be), enter thoughtpolice.
$ sudo dd if=/dev/zero of=/tmp/swap bs=1M count=150 $ sudo mkswap /tmp/swap $ sudo swapon /tmp/swap $ free
If the commands worked correctly, the output from the free command should look similar to the results shown in Figure 2 below:

Figure 2 - Configuring swap space
With the swap space issue resolved, you can now move on to the steps required to download, install and configure Oracle XE. First, you’ll need to add the Oracle repository to your apt sources list. Issue the following command to open the list in the nano text editor:
$ sudo nano /etc/apt/sources.list
Navigate to the end of this file (use Ctrl+V to scroll down page by page) and at the bottom add the following line:
deb http://oss.oracle.com/debian unstable main non-free
Save the file by pressing Ctrl+O, and then exit using Ctrl+X.
Now you can go ahead and download Oracle XE using the following commands:
$ wget http://oss.oracle.com/el4/RPM-GPG-KEY-oracle -O- | sudo apt-key add - $ sudo apt-get update $ sudo apt-get install oracle-xe
This process may take some time (XE is a 221MB package) and you may need to answer Y when asked if you wish to continue.
It’s worth pointing out that when I ran the above commands, I found that the download would sometimes freeze at a certain point. If this happens to you, press Ctrl+C to force exit the process and then re-issue the command to pick up from where you left off (you can press the up arrow key to quickly bring up the last command you entered).
When the process has finished, Oracle XE is now installed. Before you can use it, however, you will need to configure it. Issue the following command to start the Oracle Database configuration tool:
$ sudo /etc/init.d/oracle-xe configure
When asked for a port number for Application Express, accept the default option of 8080 by pressing Enter. Do the same when offered port 1521 for the database listener. Next, enter a system password, and confirm it when requested. Finally, accept the default setting of y when asked if you want XE to be started on boot. Oracle will now configure the Net Listener and the Database – this may take a few minutes. When it is done you should see a message like the one shown in Figure 3.

Figure 3 - Oracle install complete
The next step you need to follow is to set up the ORACLE_HOME and PATH variables on your system, which will make it easier to run the SQL*Plus client. Create your user .bash_profile file by issuing the following commands:
$ cd ~ $ nano .bash_profile
In the nano editor, insert the following two lines:
export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server
export PATH=${PATH}:${ORACLE_HOME}/bin
Press Ctrl+O to save and then Ctrl+X to quit nano. Now, log out of Ubuntu using the following command:
$ logout
You’ll be returned to the login prompt. Login once again using the username notroot and password thoughtpolice. Now, issue the following command to start the SQL*Plus client as the SYSTEM user:
$ sqlplus system@xe
Enter the password you chose when configuring Oracle when requested at the prompt. You should then see a message informing you that you are connected to Oracle. Now that you are logged in to the database, it is a good time to allow remote access to the Oracle XE web server, which runs Apex and which we will be using to run our PL/SQL web applications. To do this, issue the following command:
SQL> exec dbms_xdb.setlistenerlocalaccess(false);
You should see the message “The PL/SQL procedure successfully completed.” before being returned to the SQL prompt. Next, exit SQL*Plus by entering the following command:
SQL> exit
You will now be back at the Ubuntu shell prompt. The next thing you’ll need to do is determine the IP address of your virtual machine. To do this, use the command:
$ ifconfig
You should see output similar to the one shown below. You need to look for the entry for eth0, specifically for the value next to inet addr: – in my case it is 192.168.133.131, as shown in the screenshot in Figure 4.

Figure 4 - VM IP address
Now, back in Windows, fire up your favourite Web browser and enter the following address into the Address box, replacing my IP address with the one for your virtual machine:
http://192.168.133.131:8080/apex
You should see a screen like the one shown in Figure 5.

Figure 5 - Oracle Application Express Home Page
This interface is actually very useful, so let’s login and create a new database user, which you will later use as the schema for your PL/SQL web application. Enter the username SYSTEM and the password you entered during the Oracle configuration. From the next screen, click the arrow next to the Administration icon, and from the Database Users menu, select “Create User”. This will bring you to a form where you can enter the details for the new database user. Enter the username embosa and whatever password you like (for the sake of simplicity it would be wise to use the same password as you chose for the SYSTEM user – of course you would never do this on a production system!). Make sure that the roles CONNECT, RESOURCE and DBA are all checked, and press the “Create” button at the top right hand side of the form to create the user.
Next, hop back to your Ubuntu VM and enter the following command to login to Oracle using your new user:
$ sqlplus embosa@xe
Enter the password when asked, and hey presto, you’re logged in as the user embosa! Now, let’s go about creating a DAD so that we can publish HTML using PL/SQL. The following block of code will create, authorize and configure a DAD named embosa which will be accessible at the URL http://192.168.133.131:8080/embosa (again, replace the IP address with your own VM’s IP).
begin dbms_epg.create_dad(dad_name=>'embosa', path=>'/embosa/*'); dbms_epg.authorize_dad(dad_name=>'embosa', user=>'EMBOSA'); dbms_epg.set_dad_attribute(dad_name=>'embosa', attr_name=>'default-page', attr_value=>'home'); dbms_epg.set_dad_attribute(dad_name=>'embosa', attr_name=>'database-username', attr_value=>'EMBOSA'); end; /
This will create the DAD, next you need to create the “default page” by creating a procedure named home. To do so, use the following:
create or replace procedure home as
begin
htp.p('Hello, world!');
end home;
/
Now, hop back over to Windows and in your Web browser, navigate to the URL http://192.168.133.131:8080/embosa, replacing the IP address accordingly. You should see something like that shown in Figure 6.

Figure 6 - A basic PL/SQL Web Application
The final piece of configuration to do is to configure a virtual directory where you can store images, external styles and scripts and so on. Back in your Ubuntu VM, you should still be logged into SQL*Plus. In here, run the following command to open port 2100 for FTP connections:
SQL> exec dbms_xdb.setftpport('2100');
Now, enter exit to leave SQL*Plus, and create a test text file by issuing the following command:
$ echo testing! > test.txt
Next enter the command ftp to open the FTP client. At the ftp prompt, issue the following commands (you will be prompted for your username and password, these are your database username and password, so if you followed the instructions above your username will be embosa):
ftp> open localhost 2100 ftp> ls ftp> mkdir images ftp> cd images ftp> send test.txt
Now, go back to your web browser, and this time enter the URL http://192.168.133.131:8080/images/test.txt (again, change the IP as required) -Â you should see the message “testing!”. That’s it, your virtual directory is now created and you can use your favourite FTP client to upload images and other files to this directory. To connect to this folder from Windows, just enter the Ubuntu VM’s IP as the hostname, be sure to enter 2100 as the port number, and use the database username and password to login.
You should now have a usable alternative to mod_plsql up and running, which will allow you to create PL/SQL web applications on Oracle XE alone. I hope to post some more tutorials in the near future that will capitalise on this setup, showing you how to create useful PL/SQL Web applications. If you have any questions, comments or suggestions, feel free to leave a comment on this post.
Install Apache and mod_owa
In order to develop PL/SQL applications on Oracle XE, we are going to need to install a web server (Apache) and a PL/SQL gateway for Apache called mod_owa. On a regular Oracle Application Server you would probably be using Oracle HTTP Server (a modified Apache) and mod_plsql, amd you should also be able to follow my future tutorials if you have this type of setup.
Once again I will be assuming throughout this guide that you have followed my Oracle XE installation tutorial. If you didn’t, you may need to change usernames, passwords and service names to fit your setup. I will be walking through the setup process on a Windows XP machine, but it should be similar on another Windows version. Let’s get started!
IMPORTANT NOTE: If you are looking for the download for mod_owa, please note that the website for it has moved since this blog post was originally written. You can now find mod_owa on the Oracle OSS website at the following URL: http://oss.oracle.com/projects/mod_owa/dist/documentation/modowa.htm. I have updated this blog post to reflect this change.
The first thing you’ll need to do is download the relevant software. The easiest way to install Apache is to download and run the installer binary from the Apache website. At the time of writing, the latest stable version of Apache available is 2.2.9, but again the process should be similar for whatever version you are installing. You can download Apache from http://httpd.apache.org/download.cgi. You will also need to grab the Apache PL/SQL Gateway Module (mod_owa) from http://oss.oracle.com/projects/mod_owa/dist/documentation/modowa.htm. Click on the link for “Zip file for Windows”, which includes the source code and binaries for the Windows version of Apache.
The first stage in setting up our PL/SQL web development environment is the installation of the Apache web server. To start the installation, run the installer package you downloaded earlier (the filename should be something like apache_2.2.9-win32-x86-no_ssl-r2.msi). The screen should look similar to the one in Figure 3a below:
Click “Next >” to continue. On the screen that follows, read the license agreement and if you are happy with the terms, select “I accept the terms in the license agreement” and click “Next >” to move on to the readme screen, from which you can simply press “Next >” again. You should now be presented with the following screen:
Unless you are installing Apache for production use, it doesn’t matter too much what you enter into Network Domain, Server Name or Administrator’s email, but be sure to select the option to Install Apache “for All Users, on Port 80, as a Service”. Installing on Port 8080 would likely cause a conflict between Apache and the Application Express software that comes with Oracle XE, which runs on port 8080. As soon as you are ready, click “Next >” to continue.
On the “Setup Type” screen, you can safely leave the default option of “Typical” selected and click “Next >” to continue with the installation. Advanced users may wish to tweak their installation using the Custom option, but for the sake of this tutorial, there is no need to do so.
The Apache installer will now ask you where to install Apache on your hard disk. By default Apache is installed into a subfolder of the Program Files folder, but I find it easier to install Apache into a folder just beneath the root of the C drive, which I usually name “httpd”. You can safely accept the default destination, but from here on I will refer to all Apache configuration files as if you chose to install to C:\httpd\. To install to this directory, click on the “Change” button as in Figure 3d, which should popup a screen like the one in Figure 3e. In the textbox for Folder Name, enter C:\httpd\ and click “OK”. This will close the popup window and return you to the screen shown in Figure 3d. You can now click on “Next >”.
You can now safely click on the “Install” button, which will start the installation process. This should not take long, especially if you are using a modern PC. During the installation you should see a screen similar to that in Figure 3f below.
When the installation has completed, simply click the “Finish” button to exit the installer. You should now have a new icon in your system tray, like the one highlighted in Figure 3g. It should have a tiny green play symbol in it. If it has a red square stop symbol instead, left-click on the icon, and from the Apache2.2 menu, click “Start” to start the Apache service.
Before we move on to installing mod_owa, we will first check that Apache is up and running and functioning correctly. To do so, open your favourite web browser (I use Firefox), enter http://localhost/ in the address bar and press enter. If Apache is working, you will see a message like in Figure 3h:
Now that we have Apache up and running, it is time to install our PL/SQL gateway, mod_owa. The first thing we need to do is to unzip the archive we downloaded earlier, usually named windows_all.zip. You don’t need to worry about where you extract the files to, as we are only really interested in one of them. When the archive has extracted, open the folder you extracted them, and go into the modowa folder. From here, double click on apache22 and right-click on mod_owa.dll and click Copy.
We will now paste this into the modules folder under the Apache installation directory. Hold down the Windows key and press R to open the Run dialog and enter C:\httpd\modules\ as shown in Figure 3i:
This will open the modules folder. Go to the Edit menu and click on Paste to put a copy of the mod_owa.dll file here. Now that we have stored the module DLL file, we now need to tell Apache to load this module into the web server and set up a new Apache Location, which will act like an Oracle Document Access Descriptor (DAD) from where we can run our PL/SQL web applications. If none of this makes any sense to you at this point, don’t worry about it, just follow the instructions closely and you’ll be fine.
To open the Apache configuration file (httpd.conf) open the Run dialog once again (Windows+R or Start->Run). This time, enter notepad c:\httpd\conf\httpd.conf and click the OK button. Notepad should launch, with the Apache config file opened and ready for editing. Scroll down to the bottom of this file (or hold down the Ctrl button and press the End button) and below all other code, insert the text from listing 3a:
LoadModule owa_module modules/mod_owa.dll
<Location /somando>
AllowOverride None
Options None
SetHandler owa_handler
OwaUserid somando/somando1
OwaNLS WE8ISO8859P1
OwaDiag COMMAND ARGS CGIENV POOL SQL MEMORY
OwaLog "/usr/local/apache/logs/mod_owa.log"
OwaPool 20
OwaStart "doc_pkg.homepage"
OwaDocProc "doc_pkg.readfile"
OwaDocPath docs
OwaUploadMax 10M
OwaCharset "iso-8859-1"
order deny,allow
allow from all
</Location>
/
Listing 3a: mod_owa Options for Apache’s httpd.conf
When you have added the text above to your httpd.conf file, save the file, and on the Apache icon in your system tray, left-click and from the Apache2.2 menu choose the “Restart” option to restart the Apache service. If all has gone well, Apache will restart just fine and you will have a play icon in your system tray icon once again. If you did not follow my guide to install Oracle XE, you will need to change the OwaUserid parameter in the text above to your own database’s connect identifier.
Once Apache has been restarted, mod_owa should now be running from http://localhost/somando. To test this, enter that address into your favourite web browser, and if mod_owa was installed you should see an error message like the one displayed in Figure 3j. If you see a different error message, you may not have installed mod_owa correctly.
The final thing we are going to do to make sure our Apache+PL/SQL setup is working correctly is create a sample application which performs a database SELECT and displays the output in a HTML table. Before we create the PL/SQL procedure to do this, let’s run the query from the SQL*Plus command line to see what data we should expect to appear in our sample app. To open SQL*Plus, go to Start -> Programs -> Oracle Database 10g Express Edition -> Run SQL Command Line. When the command line appears log on by typing CONNECT and pressing Enter. When prompted, enter your database username and password (Username: somando Password: somando1 if you followed our Oracle XE installation guide) and as soon as you are connected, enter the SQL statement from Listing 3b to query the database.
SELECT INITCAP(LOWER(object_type)) type, COUNT(*) count FROM all_objects GROUP BY object_type;
Listing 3b: Query all_objects table by object_type
You should see a result similar to that illustrated in Figure 3j:
Now we are going to create a PL/SQL procedure that will output this data to a HTML table that we can access using our web browser. From the SQL Command Line, enter the command ed test_page. Notepad will open and say that it cannot find the test_page.sql file, asking if you would like to create a new file. Click on the “Yes” button, and paste the text from Listing 3c into the Notepad window:
CREATE OR REPLACE PROCEDURE test_page IS CURSOR get_data IS SELECT INITCAP(LOWER(object_type)) type, COUNT(*) count FROM all_objects GROUP BY object_type; BEGIN htp.p('<table border="1">'); htp.p('<tr><th>Type:</th><th>Count:</th></tr>'); FOR i IN get_data LOOP htp.p('<tr><td>'||i.type||'</td><td>'||i.count||'</td></tr>'); END LOOP; htp.p('</table>'); END test_page; /
Listing 3c: Create test_page PL/SQL Procedure
When you have pasted the above code into Notepad, click on File -> Save and then quit Notepad. Back in the SQL Command Line, you should have an SQL prompt. Here, enter the command @test_page to run the script we just created. If all goes according to plan, you should see a message “Procedure created”. We can now test this procedure from our web browser by navigating to http://localhost/somando/test_page which should display something like what you see in Figure 3k below:
That’s it! You are now ready to start developing PL/SQL web applications. In our next tutorial I will look at installing Oracle SQL Developer and how to set up a development environment for PL/SQL web application programming. Very shortly I will be writing tutorials on creating some neat web applications in PL/SQL.
Click here to view a printer friendly version of this tutorial. To download this tutorial to disk, right click here and choose “Save Target As” or “Save Link As”. You will need Adobe Reader to open this file.
Install Oracle XE
Oracle Database 10g Express Edition (I will refer to this as Oracle XE from here on) is a basic version of the Oracle Database 10g that is freely available for development, deployment and distribution. It is an excellent entry-level database for learning Oracle and PL/SQL and will run on most modern PCs and laptops. I will be using Oracle XE in the majority of the Oracle tutorials and sample applications on this website, so it is highly recommended that you install it so you can follow my examples closely and precisely.
In order to install Oracle XE on your computer, you will need to download it from Oracle’s website. It is available for Microsoft Windows and x86 Linux distributions. For the purpose of this guide I will be showing you how to install Oracle XE on Microsoft Windows XP, but the procedure should be similar for other Windows operating systems.
Oracle has an extensive Installation Guide for its Oracle XE product. Windows users can view this guide at: http://download.oracle.com/docs/cd/B25329_01/doc/install.102/b25143/toc.htm.
Linux users, check out Oracle’s Installation Guide at: http://www.oracle.com/technology/software/products/database/xe/files/install.102/b25144/toc.htm.
This guide will have many similarities to Oracle’s Installation Guide above, but if you follow any naming conventiones I use during installation it will make it much easier for you to follow any future Oracle guides I make available.
The first step in installing Oracle XE is to download the installation package from Oracle’s website. The direct URL to the Windows binary download page is http://www.oracle.com/technology/software/products/database/xe/htdocs/102xewinsoft.html. On this page, you must first accept the License Agreement by clicking on the radio button towards the top of the page. Once you have clicked on this, you can click on the relevant download links to download the installer. It is worth mentioning at this stage that you must be logged in to the Oracle Technology Network (OTN) to download Oracle XE. Registration to OTN is free and if you are not logged in you will be prompted to login or register before you will be allowed to proceed with the download.
The version I am using in my guides is the Oracle Database 10g Release 2 (10.2.0.1) Express Edition for Microsoft Windows (Western European). The download is highlighted in blue on Figure 1a above. It weighs in at a heavy 157mb, so it’s best to download this over a high-speed Internet connection if possible.
Once you have downloaded the installation package, run the OracleXE.exe file to start the installer.
On this welcome screen (see Figure 1b), press Next (Alt+N) to continue to the next screen.
On the License Agreement screen (Figure 1c), select “I accept the terms in the license agreement” (Alt+A) and then press the Next button (Alt+N) to move on.
On the “Choose Destination Location” screen (Figure 1d) leave the default values as they are in Figure 1d and press Next (Alt+N) to continue.
On this screen (“Specify Database Passwords” – Figure 1e), you can enter a password that will be used for the SYS and SYSTEM database accounts. Throughout the course of this guide I will always use the password somando1 and I suggest you do the same to make it easier to follow my guides. Obviously these passwords should only be used on development machines, with much stronger and secure passwords being used on production servers. Once you have entered and confirmed the password, hit Next (Alt+N) to continue.
You will now be presented with a summary of the installation options (make a note of the port numbers, they should be as in Figure 1f). If all looks in order, click Install (Alt+I).
The installation should now begin, and you may see a screen similar to Figure 1g. The installer will automatically copy the relevant files to your computer and will configure the database. This process may take a considerable amount of time depending on your computer’s specification. On my machine (an Intel Core 2 Duo T7300 2.00GHz with 2GB of RAM) the process took less than five minutes.
Once the installation has completed you will see a screen like in Figure 1h above. Leave the checkbox for “Launch the Database homepage” checked and click the Finish button. You have now successfully installed Oracle XE on your computer.
If you left the checkbox in Figure 1h checked, your default web browser will open and you will see a page similar to that shown in Figure 1i. Enter SYS in the field for Username and somando1 in the field for Password and click the Login button.
If you were able to login successfully, you should see a page similar to that in Figure 1j, which is basically a web-based control panel called Application Express. This utility is in fact a powerful web application which provides you complete control over your database. At this point I highly recommend that you click on the “Getting Started” link at the top right hand section of this screen, which will bring you to a local version of Oracle’s Database Express Edition Getting Started Guide. This guide can also be accessed online at http://download.oracle.com/docs/cd/B25329_01/doc/admin.102/b25610/toc.htm.
The Getting Started Guide will walk you through the process of unlocking a sample user, logging in under the sample user’s account, and creating and running a simple application with Application Express. It will take you 20 minutes to get through, and will give you an idea of how simple it is to create powerful applications using Application Express.
Finally, I will create a user/schema that I will be using in my guides. All the tables that I create in future guides will be created in this schema. To create a user, open the Database Home Page (Start -> Programs -> Oracle Database 10g Express Edition -> Go To Database Home Page) and login with the username SYSTEM and password somando1. Click on the Administration image, then click on Database Users, and then the “Create >” button.
On the Create Database User screen (as in Figure 1k above), enter the following details:
- Username: somando
- Password: somando1
- Confirm Password: somando1
- Expire Password: Leave this option unchecked
- Account Status: Unlocked
- Roles: Connect and Resource should be checked, DBA should be unchecked.
- Click on the Check All link at the bottom right of the User Privileges box to give this user all Direct Grant System Privileges.
Once you have filled out the form accordingly, click on the Create button at the top right hand corner of the Create Database User box. Once you click this button, the user/schema somando should be created. In order to verify that the user has been set up correctly, click on the Logout link at the right hand top corner of the page, and log back in, except this time log in with the username somando and the password somando1. If you can successfully log in, the user/schema has been created successfully.
That concludes this tutorial. In the next guide, I will be looking at creating tables and inserting data using Application Express. I will also be introducing the SQL Command Line (SQL*Plus) and some basic SQL statements.
Click here to view a printer friendly version of this tutorial. To download this tutorial to disk, right click here and choose “Save Target As” or “Save Link As”. You will need Adobe Reader to open this file.





















