DataCraft, Inc.
DataCraft logo
.
.
DataCraft -> Oracle WebServer 2.0 Paper

Building Your First WebServer Application: A Tutorial

February 1997
William L. Pribyl 
DataCraft, Inc. 

Introduction

True to web culture, this paper was written in a "just-in-time" fashion.  While every effort at accuracy has been made, please visit http://www.datacraft.com/ for any corrections or late additions. 

After spending months building a moderate-size application with Oracle's WebServer 2.0 and 2.1, it seems to me there are a lot of things Oracle left out of the manuals.  Not secrets, really, just omissions that would have made life easier if they'd been in there.  The most frustrating part was getting started.  Installation was easy enough - as long as you follow Oracle's instructions to the letter, and review all the log files - but after that I was clueless.  Yes, I knew PL/SQL, plus I knew a fair amount about HTML and web servers in general, but there was a large gray muddle between the two that the docs didn't wipe away.  (And in case you're wondering, I didn't have time to go to class, I had a deadline.)  This paper contains the information I wish I had known when I was just starting. 

The application on which I worked was almost all PL/SQL - no Java, no custom cartridges, no SSL security, no LiveHTML.  If you want to see the finished product, there is a slightly crippled demonstration of it at http://oracle.raid.com/imagebase (or try http://208.206.97.20/imagebase).  The web site is only for demonstration, not for download of the application, and without a privileged userid no updates are allowed.  At any rate, we used Designer/2000 as the starting point to generate the PL/SQL, which generated some functional (and rather ugly) read-only web pages, to which we added insert/update/delete features later.  While others on the team worked on cosmetic issues and wrote some oraperl CGI scripts to handle calls to various Unix utilities and programs, this paper concentrates on PL/SQL, which I believe to be easiest, and probably the most common, WebServer application development technique (and will be until WebForms is widely available).  If you just want information on using cartridges or other approaches, you can skip this paper. 

At the time of this writing (February 1997), all of my experience has been with WebServer version 2.1 and its predecessors.  WebServer 3.0 was in beta, and although Oracle was kind enough to let me fill out their web-based form requesting it, they replied with an automatic rejection saying only that the beta program was closed.  I know that version 3.0 adds a type of "transaction" support which may change your approach to updates, but I suspect that the fundamental PL/SQL programming model has not changed. 

Acknowledgments 

I am grateful to the kind folks at GeneSys LLC, an integrator of high performance computing systems for the print and new media industries, for their assistance in bringing a WebServer solution to reality, as well as for their undying confidence in my Oracle skills, not to mention their willingness to take late-night phone calls. Thanks are also due Thomas Kyte/Oracle Government, who through his many web postings and emails helped me understand what I was doing; and the ORAWEB-L Internet mailing list community. 

Before You Start 

What Version Should I Use? 

I know a lot of people have this question: Why buy WebServer 2.x when 1.0 is free? First off, an (unconfirmed) statement from an Oracles salesperson indicated that Version 2.0 would be bundled free with the Oracle server once Version 3.0 goes into production. By the time you read this, this change may be old news. 

Hoping for a definitive statement from Oracle, I asked the WebServer product manager to provide some documentation on the exact differences between the products, as well as a comment on where Oracle was headed with respect to bundling of functionality with the core server. So far Iíve waited a week; no reply yet. Not to be dissuaded, I tried other avenues to get this information. 

In 1.0, there is a CGI program for connecting to the database. WebServer 2.x adds support for "cartridges" and includes the Web Request Broker cartridge which an improvement (how much of an improvement is something of a debate) over CGI. Version 2.x also includes SSL, which is essential if you need secure connections; a Java virtual machine for server-side Java programs which can call PL/SQL; and LiveHTML for Server-Side Includes. While Version 2.0 allows you to use Netscape Fasttrack Server as the web server, Version 2.1 has an ability to use more third-party web servers such as Netscape Commerce Server and Microsoft IIS.  

You might think that you can start practicing with 1.0 and upgrade to 2.x later. True enough, but each new version also includes a variety of new and enhanced PL/SQL utilities in the toolkit. Also, later versions crash less frequently. Personally, I would hesitate to put a V1 solution into wide production use when V2 is available. Itís fine for demonstrations of the core functionality, though. 

According to Barry Johnson, a contributor on the ORAWEB-L Internet mailing list, new features for 3.0 are mainly: Intercartrdige Exchange (ICX); improved LiveHTML, because of ICX; a Perl cartridge; XA-compliant Transaction Management; CORBA-compliant WRB/ORB; and database-based authentication. Maybe next year Iíll be able to write a paper on how those things will help your application. 

Skills Assumed 

This paper assumes youíve created at least one PL/SQL package and have created a web page of some sort. Much as Iíd like to, I don't have the space to teach these fundamentals here. To be productive in WebServer PL/SQL, youíll want to know PL/SQL version 2 at least well enough to write packages, procedures, and functions; you should have a thorough knowledge of exception handling; and you would benefit from understanding the PL/SQL "table" data type. Youíll also want to have a bit of HTML knowledge, some of which you can pick up as you go. Something people often ask about is "good books about HTML;" my favorite is OíReilly & Associatesí HTML: The Definitive Guide by Chuck Musciano & Bill Kennedy, although it is getting a bit dated, and it does not treat CGI programming, both of which are not a big problem if youíre a WebServer neophyte. 

The Bare Minimum about Installation and Configuration 

If youíve ever installed Oracle on a Unix box, you know there is a root.sh script that gets generated and which you must run as root after performing the install with orainst. If youíve installed WebServer along with the Oracle server, then (assuming your WebServer product directory is ows2) root.sh will call the script $ORACLE_HOME/ows2/install/fmods.sh, which in turn will set some file permissions and then attempt to start a special WebServer administrative listener on using a command of the form "wlctl21 start admin $ORACLE_HOME". If you connect with a web browser to the URL prompted by fmods.sh, probably http://myhost.mydomain:port/ows-abin/boot), one of the first things it does is ask for the username/password combination which you supplied to prompts during orainst. If you canít remember it, just look in the file $ORACLE_HOME/ows2/svadmin.cfg Ė itís there in plain, gloriously unprotected text! 

Then you will confront a series of screens that lets you configure your first listener and PL/SQL agent (previously known as the "web agent" or "Oracle web agent" and abbreviated OWA). The listener consists of one or more background processes that respond to HTTP requests; the PL/SQL agent is the part of WebServer that connects to the Oracle RDBMS using the username and password that you designate. You can decide whether the PL/SQL agent connects via CGI, which I think largely exists for backward compatibility, or as a cartridge, in this case called the OWA cartridge, for the Web Request Broker. Although the details of the architecture are outside this paperís scope, suffice it to say that the WRB/cartridge approach is the more efficient alternative and has been highly touted by Oracle. 

Creating a PL/SQL Agent to and Configuring it to Use the Web Request Broker 

If you, like me, are not too keen on using Oracleís defaults, one of the first things you will want to do is set up your own Database Connection Descriptor (DCD) for you app rather than using those created during the installation. The DCD is a set of information that tells Oracle connection specifics such as username, password, connect string (TNS service name), and log file. This information, like almost all WebServer configuration data, is stored in an ASCII file, but it is modifiable from a web browser through the WebServer Manager screens. The agent connect data can be found in $ORACLE_HOME/ows2/admin/owa.cfg, 

There are at least two steps here: first, setting up the Oracle user and connection description (DCD); and second, telling the WRB about it. 

How to do it. First, choose a name for the Oracle user and for the corresponding DCD. In our application, we chose to make the Oracle userid invisible to the end user, so the choice of userid was pretty arbitrary. I suggest making it a short name, though, because you may be typing it a lot during application development. The DCD name will show up in URLs, so you may want to choose a concise name that your users can remember and/or type when needed. For this paper, weíll assume you are want a DCD name of "myapp" and that the Oracle userid will be mywebuser. 

Weíll also assume that you want to go through the OWA cartridge rather than CGI, that the administrative listener is running on its default port (8888), and that you want to be able to connect to your application via ports 80 and 8888. Iím including a lot of detail in the steps below because this is one of the areas I got massively confused on. Now, thankfully, you wonít have to end up like me. 

Creating the DCD for the PL/SQL Agent  Configuring the Agent to use the WRB 
    Virtual Path
     /myapp/owa
    App.
    OWA 
    Physical Path 
    /u01/app/oracle/product/7.3.2/ows2/bin (or your physical path to this exact directory)
12. Click on Modify Web Configuration 

13. Now you have to restart the listener. Go to the Listener Administration page at http://myhost.mydomain:8888/ows-abin/wladmin. 

14. Click on STOP 

15. Click on START 

That ought to do it. To confirm that everything worked, you will want to write a quick PL/SQL program to display something from the database. See below for instructions. 
About the Predefined Oracle packages 

In step 6 above, you caused a script to run which built a number of packages needed by the PL/SQL agent. This script was probably in the file $ORACLE_HOME/ows2/admin/owains.sql. If you have a number of PL/SQL agents, you will probably want to install only a single set of these packages and sharing access to them by granting execute privilege to them and creating synonyms. I think this approach is described somewhere in Oracleís online documentation, but if not, just do a select object_name from user_objects where object_type = 'PACKAGE' while logged on as the first agent, and run the grants and synonyms against this list. 

These packages are extended and improved from one release of the WebServer to the next. I have had success in back-porting them from 2.1 to 2.0 but I doubt whether doing so is supported by Oracle. 

The Typical URL 

You are going to be setting up applications that will be run by pointing a web browser to a specified URL. Itís important to understand the Oracle WebServer-specific components of the URL that follow the slash after the hostname. Look at an example: 

http://www.host.com/media/owa/search..listall?searchfor=blue+meanies&show=20 

This URL will cause the listener to look for a virtual mapping of media/owa which includes the DCD name, media, and the virtual path, owa, which could be associated with either the CGI or the cartridge OWA implementation. Here, search is the PL/SQL package name, and listall is a procedure. This URL will pass two arguments to the procedure, searchfor, with a value of "blue meanies" (in an URL, the + indicates a space), and show, with a value of 20. 

While some web server configurations allow the user to browse available files in a directory, there is no way that I know of to discover the names of existing packages and procedures using variations on this URL.  

Your First Web Page: "Hello, Web!" 

Via Static HTML files 

Although not a horribly interesting feature, WebServer does allow you to display static text via conventional ".html" text files. As with other web servers such as Apache or Netscape, you have to map the actual on-disk directory path to a "virtual" path that will be part of the URL after the host name. To set up a path for a static HTML file, from the WebServer home page, go to WebServer Manager, then Oracle Web Listener, and click on Configure for the currently running listener. Navigate your way down to the "Directory Mappings" section and put in something like this. 
    File-system directory: 
    /u01/app/myapp/www/ 
     Flag:
    NR 
    Virtual Directory:
    /myapp/pages/