Skip to main content.

Web Based Programming Tutorials

Homepage | Forum - Join the forum to discuss anything related to programming! | Programming Resources

Oracle Unleashed

Oracle Unleashed oun55fi.htm

Previous Page TOC Next Page Home


Oracle WebSystem and the World Wide Web Interface Kit

by Kenneth R. Zimmerman

As described in Chapter 54, "Oracle PowerBrowser," the World Wide Web is the Internet technology that provides universal access to file-based information. In February 1995, Oracle Corporation became the first major relational database management system (RDBMS) vendor to release technology enabling safe and reliable access to enterprise data from the World Wide Web (WWW). This technology, known as the WOW (Web-Oracle-Web) Gateway, is part of the Oracle WWW Interface Kit.

The World Wide Web Interface Kit is a set of software created independently around the world by developers attempting to solve the problem of incorporating database resident information with the WWW's file-based server technology. Each component in the WWW Interface Kit solved a particular problem in dealing with Web-RDBMS integration. The WOW Gateway, Oracle's own contribution to the kit, is the most universal and extensible of the solutions. A year after its introduction, practically an eon in the Web's time frame, it remains superior to other vendors' offerings.

The distribution of the World Wide Web Interface Kit to thousands of users internationally led Oracle to create a commercial superset of this technology. Oracle WebSystem was first demonstrated during International Oracle User Week in Philadelphia at the end of September 1995 as part of the PowerBrowser, then named WebStation, product launch. Consisting of three parts, the Oracle Web Listener, Oracle Web Agent, and the Oracle7 Server, WebSystem provides a single integrated solution to the problem of effective Web-RDBMS integration.

Complete information and trial versions of most of Oracle's technologies are on its home page. The Uniform Resource Locator (URL) for Oracle's home page is

The Oracle World Wide Web Interface Kit

The WWW Interface Kit consists of several independently developed technologies along with one from Oracle, the WOW Gateway. The components are Common Gateway Interface (CGI) gateways, search engines, and a PL/SQL compiler. You can download the complete kit as a set or each individual component separately.

As Oracle moves to a single solution for Oracle/Web integration, it might not continue to carry the WWW Interface Kit. The kit is not displayed on Oracle's home page but is still available from Each component other than the WOW Gateway has a home URL is provided in the descriptions that follow.

HTTP Servers

All the components in the WWW Interface Kit depend on the presence of an HTTP server. An HTTP server is the software that listens for Web page requests and then provides the information. It is similar to other Internet services such as FTP and Telnet. The Oracle WebServer, described later in this chapter, is one such HTTP server. If you're using WebServer, however, the components of the WWW Interface Kit are less attractive in light of Oracle WebSystems' extensive features. In that case, use WebSystem exclusively.

Don't have a copy of WebServer yet? As with most of Oracle's server technologies, Oracle WebServer is available for free 90-day trial from Oracle's home page at

The role of an HTTP server is to listen for Web page requests, resolve aliases and other redirections that might take place, and finally return the Web page to the requesting client. Another role of the HTTP server is to launch scripts as defined by a standard called the Common Gateway Interface (CGI).

Common Gateway Interface

When you request a page from a directory that is identified in the HTTP server's configuration file as containing scripts, the server runs the specified file and returns its contents as a Web page. For example, the standard NCSA HTTP server installation has a cgi-bin directory and a shell script called test-cgi. If you specify the URL, the test-cgi script runs. The following segment shows the contents of the test-cgi script:


echo Content-type: text/plain


echo CGI/1.0 test script report:


echo argc is $#. argv is "$*".



















You see that the first thing the script provides is the identifying line that precedes all Web pages:

Content-type: text/plain

You include this line because of another standard followed by Web browsers, the Multipurpose Internet Mail Extensions (MIME). When the Web browser sees the preceding line, it knows how to handle the rest of the transmitted file. Other examples of MIME types include the following:


Graphic Interchange Format (GIF) images


X-wave format sound files


Zip format compressed archives

Upon receipt of the Content-type: preamble, the Web browser launches the appropriate helper program to complete the request. In many cases, the helper program is built in to the Web browser. This is the case with most common MIME types as well as Oracle's own PowerBrowser Web client.


As dynamic as CGI programs might be, to be truly versatile there must be a means to respond to input. This is accomplished with forms. Forms are Web pages that contain fields which the user can enter and transmit to the server. Figure 55.1 from the Oracle WebServer shows one such form.

Figure 55.1. A simple Web form.

Forms can also contain other GUI elements besides fields. The following list shows some other graphical form elements:

The following segment is a portion of the HTML that creates the form shown in Figure 55.1:


<IMG SRC="autotit.gif" alt="The Oracle Web Auto Dealer">


<IMG SRC="image/nsx.gif"><P>

Welcome to the <STRONG>Oracle Auto Dealer</STRONG>!

Check out our exciting new collection of cars and vans! <BR>

<FORM METHOD="POST" ACTION="/cgi-bin/wow/auto.register">

Account: <INPUT TYPE="text" NAME="pCustid">

Password: <INPUT TYPE="password" NAME="pPassword">

<INPUT TYPE="submit" VALUE="Let's go shopping!"><BR>


The HTML tags <INPUT TYPE="text" ... > and <INPUT TYPE="password"...> capture the user name and password. Using TYPE="password" means the user will see asterisks when he types instead of the password itself. TYPE="submit" indicates a button, and VALUE= specifies the name appearing on the button.


As with other Internet services, HTTP is a well-known service. This means that applications expect to communicate with it through a known service or port number. In the case of HTTP servers, this number is usually 80 or 8080. Most Web browsers automatically issue the request to port 80, but a different port number might be specified in the browser's setup or in the URL itself as in

General Installation Recommendations

You can download the components of the World Wide Web Interface Kit individually or all at once. They are available as source code only or in precompiled binary form for Sun4 SunOS 4.1.3 systems.

Even if you are running SunOS 4.1.3 on a Sun4 machine, you should download the source code only and recompile. This ensures that the code runs properly on your system, and you can also modify it for your particular needs. Most importantly, it provides an opportunity for you to understand how CGI processing takes place.

Regardless of the path you take, you should heed the following recommendations from Oracle to make it easier to start using the various technologies.

  1. Determine where you want to place the Interface Kit files.

  2. Create a link to this location and call it /oraweb. For example, if you want to place the files in the /opt/oraweb directory, under UNIX, the following command creates the link to /oraweb:

    $ ln /opt/oraweb /oraweb

    If the /opt and the / (root directory) are on different file systems, you might have to use the -s option to the link command in the following way:

    $ ln -s /opt/oraweb /oraweb

  3. If you're installing the entire source distribution, which is recommended, create a source directory under oraweb.

    $ mkdir /oraweb/sdk-src

  4. If you are already running an HTTP server such as the NCSA HTTPd, you should create a link to the httpd directory under the oraweb directory.

Following are brief descriptions of each component in the World Wide Web Interface Kit.

WOW Gateway

The WOW Gateway is a PL/SQL-based gateway developed by Magnus L[um]onnroth of Oracle Corporation. This is the best product in the kit and the precursor to the Oracle Web Agent. It is covered in detail in the section "WOW Gateway," later in this chapter.


Constantin Ocrainets of Russia developed WORA, an Oracle table browser. WORA is a single-program Pro*C executable that functions as both the CGI gateway and server application. It connects to the Oracle7 server and uses the data dictionary system tables to extract information on tables, views, and columns.

WORA generates HTML forms from which users can specify and view a list of available tables, views, and columns, specify query conditions, and view the result set of the query. WORA does not allow updates, but source code is provided so the user can add this functionality. WORA functions quite well as a simple data browser.

WORA uses the GET method, one of two form processing methods specified in the CGI 1.0 standard. There are system limits on the number of parameters, their lengths, and the length of the query condition. The POST method is preferred but not implemented in WORA.

Most of the items in the World Wide Web Interface Kit rely on UNIX operating system features to compile and run; however, you can modify some to run on other operating systems that offer similar features.

The home URL for WORA is


A post-processing gateway by Guy Decoux of France, DECOUX relies on several configuration files that specify which predefined query and action to perform. It is accessed via a Pro*C executable, and an Oraperl solution is also available. DECOUX relies on another CGI parameter called ISINDEX to perform its functions. ISINDEX is simply a GET tag that causes the browser to display a standard input box with a message prompting for key words. Unfortunately, it is subject to the same problems as any other GET method CGI program.

The home URL for DECOUX is


An Oraperl-based gateway and form builder by Arthur Yasinski of Canada, ORAYWWW facilitates the creation of HTML forms dynamically. The forms can allow queries only, or you can write them to update and delete data as well. Its strength is its capability to selectively specify both allowed user functions and the columns displayed.

The home URL for ORAYWWW is

TSS Demo

TSS is a free-text indexing and search system with a PL/SQL front end by Peter Larsson of Sweden. TSS is a complicated system but is simple to get up and running. It uses several Oracle Call Interface (OCI) daemons to perform its functions of searching and indexing. The actual API for the software is in PL/SQL. The interaction required between Oracle and the operating system is performed using the DBMS_PIPE package. This provides the means of reading documents through a user-developed function.

For more information, contact Peter Larsson,

PL/SQL Compiler

pls.sun4 (or PL/Web) is a stand-alone PL/SQL compiler for the SunOS 4 operating system. It contains built-in extensions to PL/SQL to provide HTML processing. It provides a means for developers to produce PL/SQL applications without an Oracle7 database. It also provides the capability to interactively develop PL/SQL HTML applications, which requires use of HTML pages provided with the compiler. You can then save the code as source files on the server.

This compiler is available only for SunOS 4 and there are no other sites for it.

A sure sign of the WWW Interface Kit's grassroots acceptance is in the Samples mailing list. Created and managed by Thomas Dunbar, Research & Graduate Studies, Virginia Tech, Samples, along with its companion Web site, is dedicated to PL/SQL-based interfaces. Both are increasingly peppered with Web-based application queries including those for the WOW Gateway and Oracle WebSystem.

To join the mailing list, fill out the HTML form found at

WOW Gateway

In early 1994, Oracle became the first major RDBMS to release a gateway for the WWW. Called WOW for Web-to-Oracle-to-Web, it was released into the public domain and remains the best means of getting Oracle databases on the Internet for little or no cost. Commercial operations that require more robust and supported operation (WOW is an unsupported product) should use the Oracle WebServer, which is covered fully later in this chapter.

Traditionally, most gateways are coded in C, perl, or shell scripts. WOW is remarkable in that it provides the capability to develop all Web applications in PL/SQL. This means that the same language that developers already use to write other Oracle applications can be harnessed to the power of the Internet and the World Wide Web. This is all done using traditional CGI call mechanisms so that the programs are called as if they were files in the CGI directory.

WOW consists of several components:

A Simple Demonstration of WOW Using SQL*Plus

To grasp what WOW does, look at a simple example using SQL*Plus. PL/SQL until recently did not provide a means of exchanging data except through tables. In Oracle7, there are a number of packages that extend the facilities available to the language. One of these new packages is DBMS_OUTPUT. Within this package are several functions, including put_line(), which sends its arguments to a buffered stream. The following example illustrates its use.

DBMS_OUTPUT.PUT_LINE('Your total order comes to ' || TO_CHAR(total_order));

DBMS_OUTPUT specifies the package name, and put_line() specifies the particular function within that package. A single character string value or expression is required. This case uses an expression concatenating a character string and a total value, which is first converted from numeric to character string type.

In addition to DBMS_OUTPUT, you must have a program that knows to extract such buffered information. The likely choice is SQL*Plus. Whenever you call a PL/SQL stored procedure or an anonymous PL/SQL block, an inline program is executed. Provided that you'd previously issued the SET SERVEROUTPUT ON command, the output is sent to the standard output of the application upon completion of the block or procedure.

In fact, to appreciate how WOW works, you should see an example in SQL*Plus. For the purposes of this example, assume that the HTP and HTF packages were installed under a user ID called wowuser. A call to the bold procedure results in the following output with the appropriate HTML bracketing tags for boldface output:

$ sqlplus wowuser

enter password: *****



SQL> EXECUTE htp.bold('This is a test');

<B>This is a test</B>

PL/SQL procedure successfully completed.


wowstub: the Agent Component

Of course, you don't want to have to invoke SQL*Plus every time you produce HTML, so instead, the wowstub program fills the need as the primary CGI interface program. wowstub itself does not perform the application functions but functions as a pipeline between the HTML server and the Oracle database. Be aware that the program need not be called wowstub; however, if you change the name, you must also change references to that program name. They are found in HTML files and in the WOW shell script.

When invoked, wowstub evaluates several environment variables and determines whether the GET or POST method is used. Additionally, it checks to see if the program was invoked in debug mode. Finally, it reads the parameters from standard input for POST or from the INFO environment variable for GET and ISINDEX requests and connects to the database using the name and password specified in the environment variables. It is very important that the gateway is installed such that the contents of the agent are not visible to unauthorized users. Otherwise, with the name and password in plain sight, wowstub and the data with which it interacts are compromised. Count on it!

The WOW gateway provides a database server-resident means of seamlessly tying business rules into Web forms processing. Web forms are the interactive Web pages that enable user interaction with the Web site. Unlike traditional, static Web pages, forms enable Web developers to create highly customized and interactive Web sites.

You can test a correctly configured server using Telnet. You can instruct Telnet, which traditionally connects to well known port 23, to use the Web server's port 80 instead. The following example of this technique illustrates what happens during a Web page request. User entries are shown in bold. You must end the HEAD statement with two line feed or Ctrl+J characters.

# telnet 80

Trying 555.137.257.36 ...

Connected to

Escape character is '^]'.

HEAD / HTTP/1.0¿¿

HTTP/1.0 200 OK

Date: Thursday, 24 Aug 95 10:15:22 GMT

Allow: GET, HEAD

Server: Oracle Web Server/

Content-Length: 1973

Content-type: text/html

Last-modified: Thursday, 17 Aug 95 8:12:23 GMT

URI: <index.html>

Connection closed by foreign host.

The WOW Shell Script

In order for the wowstub program to properly execute, you must have a wrapper program that takes care of setting up environment variables and any other functions to be performed each time the gateway is called. This is the purpose of the WOW shell script. As in the case with the wowstub program, you can change the name to something more appropriate with the application it performs. For the following examples, however, I use the name WOW.

Extending WOW Using PL/SQL

PL/SQL is Oracle Corporation's procedural SQL-based programming language. Based on ADA, PL/SQL offers object-oriented features to fully harness SQL's potential. Combining polymorphism and encapsulation with SQL data manipulation language (DML) statements, users can craft the most sophisticated of business rules and execute them efficiently within the Oracle7 engine. Additionally, you can use PL/SQL to develop the procedural code within Oracle's development applications, such as Forms, Graphics, and Reports. As such, Oracle developers need not learn a new language to process HTML.

In the WOW gateway, PL/SQL packages such as htp.bold and htp.italic are written in two pieces, the called procedure and a matching function. This is due to the inability to call a function without capturing the result, which is consistent with strongly checked languages such as ADA and with current solid code practices. Frequently, in less rigorous languages, errors arise from unchecked result codes and return values. You will notice that all of the functions conclude with a call to the print or p procedure. This places the output in the put buffer from which the application, wowstub in this case, extracts the results.

The following code segment shows the contents of the htf.bold function. You see how it merely encapsulates the passed string in the HTML tags for bolding; <B> and </B> and returns it to the calling htp.bold procedure. The htp.bold procedures always perform the htp.p procedure to place the text on the output buffer.

function bold   (ctext  in varchar2) return varchar2 is

begin return('<b>' || ctext || '</b>' ); end;

procedure bold   (ctext  in varchar2) is

begin p(htf.bold(ctext)); end;

When a certain feature is not available in WOW, you can add it either to the application or, better yet, to the HTP and HTF packages. An example of a common limitation will further illuminate this choice.

When developing HTML forms using WOW, you can specify input fields in the following forms:

procedure formField(cname in varchar2, nsize in integer);

procedure formField(cname in varchar2);

procedure formField(cname in varchar2, cvalue in varchar2);

All of the forms require the name of the field as the first argument. This is how values are tagged before passing through to the CGI program. Depending on whether the next argument is missing, an integer, or a varchar2 field, PL/SQL expects to set the field to a default width, the specified width, or the default width with an initial default value. What is missing is the capability to create a field with a specified width and an initial default value. To do this, you extend WOW by adding the following procedure prototype, function prototype, procedure, and function. All are required.

function formField(cname in varchar2, nsize in integer, cvalue in varchar2)

    return varchar2;

function formField(cname in varchar2, nsize in integer, cvalue in varchar2)

    return varchar2 is


   return('<input type="text" name="' || cname || '" size="' ||

          to_char(nsize) || '" value="' ||

          cvalue || '">');


procedure formField(cname in varchar2, nsize in integer, cvalue in varchar2);

procedure formField(cname in varchar2, nsize in integer, cvalue in varchar2) is

begin p(htf.formField(cname,nsize,cvalue)); end;

WOW's Limitations

As groundbreaking as WOW is, it is usually not appropriate for commercial utilization without extensive extensions to the feature set. Because WOW product support is not available from Oracle, feature extension is left up to the individual developer as the HTML standard evolves. Additionally, WOW requires manual setup for each Web server's implementation. Ideally, there should be a one-stop solution: Web server, gateway, agent. Oracle has such a product in the Oracle Web Server.

Oracle WebSystem

As the Internet became more accepted as an information conduit, many organizations established an Internet presence in an effort to be available to both customers and resources. The need to potentially service tens of millions users was an impediment to setting up a home on the WWW, which required flexible, secure, and reliable Web access and management. Developers needed a reliable solution to the problems of scalability, information partitioning, and life-cycle management. Such a need drove the development of the Oracle WebSystem (OWS). It provides integrated installation, management, and development tools along with its use of native language (PL/SQL) server-side processing to take advantage of extant business rules.

OWS Components

The Oracle WebSystem is actually three complementary products:

The Oracle Web Listener is an optimized HTTP server intended for use in high-traffic mission-critical environments. It is tuned for the requirements of highly interactive database originated processing and data sourcing. It provides information from flat files, the Oracle Web Agent, and other CGI/1.1-compliant applications.

The Oracle Web Agent is the successor to WOW itself. It is a highly improved production-quality version of the WOW, wowstub, and HTP/HTF packages. It has been greatly extended, secured, and optimized for use in the Oracle Web Server environment. The agent concept is also exploited in Oracle Mobile Agents. Because the agent is placed close to the source of information, functions for the remote client are performed far more quickly than through the multiple round trips required in a traditional client/server architecture. This is because the local agent has a higher speed connection than the remote browser, which is likely to be many hops away.

The Oracle7 Server is the same Oracle7 technology that corporations have relied on to reliably service worldwide applications. It provides desktop management capabilities in an eminently scalable relational database management system. For enterprises that want to use an existing Oracle7 server, the Oracle WebServer Option provides all the features without the additional Oracle7 server.

Comparison to WOW

WOW paved the way for OWS. It proved that the Web-agent-server path was reliable, flexible, and technically viable. It also demonstrated that support and vertical integration were necessary to make it commercially viable. OWS provides the following features that were missing from WOW:

WOW Conversion Issues

In order to extend the facilities in OWS and resolve some earlier architectural vagaries, the Oracle Web Agent packages contain many extended and renamed package components. In order to use existing WOW applications with the Oracle Web Server, you must accommodate the following differences.

WOW Name

OWA Name














WebSystem offers all the features of the WOW gateway and more. Commercial support, future enhancements, and tighter integration with other Oracle technologies including Oracle Applications through Oracle Internet Commerce are all a part of WebSystem's offerings.

WebSystem Installation

WebSystem even goes farther offering effectively one-button installation. Whether you're installing the full WebSystem package using Oracle Installer or WebServer Option for when you already have an Oracle7 database, the procedure is simple.


Initially, WebSystem was released for the Sun Solaris 2.4 platform whose installation is shown here. The process is similar for all platforms.

Prior to installing WebSystem, you must do the following:

WebServer Option Installation

Following is the script of one installation:


# pwd


# zcat oweb.tar | tar xvf -    # unpack the oweb.tar.Z

x owsins/ows/mesg/owsus.msb

x owsins/ows/mesg/owsus.msg




# cd owsins/ows/install

# pwd



Creating product area /export/home/oracle/ows

Copying the Web Server binaries to /export/home/oracle/bin

Please enter the port number you want to use as your administration server. Valid port numbers range from 1 to 65535 [default 8888]:

Please enter hostname (including domain) name for your machine.


Please enter the name of the 'oracle' software owner: oracle

Please enter the name of the 'oracle dba' group: dba

Setting Oracle Web admin password to 'manager'

    Installation of the Oracle WebServer file set is complete.

You now need to ensure your ORACLE_HOME environment variable is set

    and run the following command as the oracle software owner to start

    the Administration Server:

         /export/home/oracle/bin/wlctl start 8888

    To complete installation of the Oracle WebServer, open the

    following URL location with your web browser:

    and follow directions as they appear on the pages.

    When you attempt to use the Administration Server you will

    be requested to authenticate youself by entering the username

    'admin' with password 'manager' in the appropriate login screen.

That's it! The installation of the software package is complete.

Starting Up the Web Listener

The following code segment shows how to start the Web Listener to complete the registration and setup process.

$ pwd


$ bin/wlctl/start 8888

Oracle Web Listener, Version 1.01fc5

Copyright 1995 Oracle Corp.  All Rights Reserved.

Information: Listening on port 8888

Information: The server started successfully

Server now running as process 882

Once the Web Listener is running, you complete the rest of the process using a Web browser and the WebServer itself.

Setting Up the Web Agent

As indicated in the previous installation messages, connect to the WebServer using the URL You see the screen in Figure 55.2.

Figure 55.2. WebServer Registration form.

You must fill in every field. Once this form is completed and submitted, you see the screen shown in Figure 55.3.

Figure 55.3. WebServer Installation form.

At this point, follow the remaining tasks to complete the installation:

  1. Configure an Oracle Web Agent service, OWA_DBA, for the Administration Server that you are currently using.

  2. Configure your first Oracle Web Listener.

  3. Configure a default Oracle Web Agent service, OWA_DEFAULT_SERVICE, for your first Oracle Web Listener that you configured in step 2.

Figure 55.4 shows the fields and buttons that you use to set up the Agent service.

Figure 55.4. Agent SetupInstallation form.

Finally, create the first Web Listener other than the Administrative Server by completing the form section below the WebServer Installation form section. It is shown in Figure 55.5.

Figure 55.5. Creating an Oracle Web Listener.

Learning More About WebSystem

Once the system is up and running, all of the product documentation is provided in the /doc/ directory of the WebServer directory. Figure 55.6 shows how to access this section using the URL

Figure 55.6. WebSystem's online documentation.


Oracle led the development of commercial Web/RDBMS integration. It freely released a set of technology, the WOW Gateway, which continues to be vital as a result of grassroots support. WebSystem now provides the commercial, high-performance secure gateway to enterprise data, which companies have increasingly needed. As you work with these technologies, keep in mind that they are all extensible. If you need additional features, build them in! All of the components are provided in source code so that you can improve them for your own needs. And, if you are stuck, check out the various Internet and commercial service provided forums covering Web/RDBMS technologies:

Previous Page TOC Next Page Home