- 55

- Oracle WebSystem and the World Wide Web Interface Kit

- The Oracle World Wide Web Interface Kit

- HTTP Servers

- Common Gateway Interface
- Forms
- HTTP Port

- General Installation Recommendations
- WOW Gateway
- WORA
- DECOUX
- ORAYWWW
- TSS Demo
- PL/SQL Compiler

- WOW Gateway

- A Simple Demonstration of WOW Using SQL*Plus
- wowstub: the Agent Component
- The WOW Shell Script
- Extending WOW Using PL/SQL
- WOW's Limitations

- Oracle WebSystem

- OWS Components
- Comparison to WOW
- WOW Conversion Issues

- WebSystem

- WebSystem Installation

- Prerequisites
- WebServer Option Installation
- Starting Up the Web Listener
- Setting Up the Web Agent
- Learning More About WebSystem
- Summary

#
55

## 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 http://www.oracle.com/.

### 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 http://dozer.us.oracle.co:8080/ftp/sdk10/owik.tar.Z. 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 http://www.oracle.com/.

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 http://www.chatsoft.com/cgi-bin/test-cgi, the test-cgi script runs. The following segment shows the contents of the test-cgi script:

    #!/bin/sh

    echo Content-type: text/plain

    echo

    echo CGI/1.0 test script report:

    echo

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

    echo

    echo SERVER_SOFTWARE = $SERVER_SOFTWARE

    echo SERVER_NAME = $SERVER_NAME

    echo GATEWAY_INTERFACE = $GATEWAY_INTERFACE

    echo SERVER_PROTOCOL = $SERVER_PROTOCOL

    echo SERVER_PORT = $SERVER_PORT

    echo REQUEST_METHOD = $REQUEST_METHOD

    echo HTTP_ACCEPT = "$HTTP_ACCEPT"

    echo PATH_INFO = "$PATH_INFO"

    echo PATH_TRANSLATED = "$PATH_TRANSLATED"

    echo SCRIPT_NAME = "$SCRIPT_NAME"

    echo QUERY_STRING = "$QUERY_STRING"

    echo REMOTE_HOST = $REMOTE_HOST

    echo REMOTE_ADDR = $REMOTE_ADDR

    echo REMOTE_USER = $REMOTE_USER

    echo AUTH_TYPE = $AUTH_TYPE

    echo CONTENT_TYPE = $CONTENT_TYPE

    echo CONTENT_LENGTH = $CONTENT_LENGTH

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:

image/gif | Graphic Interchange Format (GIF) images
audio/x-wav | X-wave format sound files
application/zip | 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.

##### Forms

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:

- Buttons
- Checkboxes
- Radio buttons

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

    <H1>

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

    </H1>

    <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>

    </FORM>

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.

##### HTTP Port

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 http://www.chatsoft.com:8080/.

#### 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.

#### WORA

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 http://weirdb.jinr.dubna.su/wora/wora.html.

#### DECOUX

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 http://moulon.inra.fr.

#### ORAYWWW

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 http://www.nofc.forestry.ca:80/oraywww/.

#### 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, plarsson@astrakan.se.

#### 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 http://gserver.grads.vt.edu/, 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 http://gserver.grads.vt.edu/subscribe_sample.html.

### 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:

- WOW is a shell script provided in C-shell format but easily converted to Bourne or Korn shell to provide the same functions, namely setting environment variables related to the database connection.
- wowstub is an OCI program that converts POST data into calls to stored procedures with arguments passed correctly as entered, that is with + replaced by space and so on.
- HTP is the hypertext package containing all procedures used by the WOW gateway.
- HTF is the hypertext package containing all functions used by the WOW gateway. The functions return values, whereas the procedures do not. The functions are required to check error conditions and alter behavior as needed.

#### 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: *****

    Connected.

    SQL> SET SERVEROUTPUT ON

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

    <B>This is a test</B>

    PL/SQL procedure successfully completed.

    SQL>

#### 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 www.chatsoft.com 80

    Trying 555.137.257.36 ...

    Connected to chatsoft.com

    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/1.0.0.0.1

    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

    begin

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

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

              cvalue || '">');

    end;

    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:

- Oracle HTTP Listener
- Oracle Web Agent
- Oracle7 Server

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:

- Vertical product integration—Using Oracle Installer technology, the management of the OWS products is integrated with other Oracle products. No longer is the management of Oracle/Internet technology a manual, homegrown job. Additionally, the agent technology is a registerable service in SQL*Net Version 2. This further facilitates the management of multiple Web-based applications through a known interface, the Oracle Network Manager.
- Product evolution—As HTTP, HTML, and other Internet standards progress, so will OWS. Already, OWS supports proposed HTML3 extensions including background GIFs and tables.
- Improved performance—Traditional HTTP servers expected to move files, not database-resident information. As such, their performance was based on getting the same information out many times. The best means for file serving was through multithreaded processing where each new connection invoked a new server process. The Oracle Web Listener accomplishes its improved throughput through a single process/single thread asynchronous engine. As such, time to service a request is significantly reduced, which increases response time, especially under heavy loads.
- Improved flexibility—As part of the Oracle Web Server, multiple languages are supportable simultaneously. This might not have been available under other servers, and it certainly wasn't available transparently for the WOW user.
- Improved security—In addition to Secure Network Services (SNS), an option already available to WOW users running SNS, the Oracle Web Listener provides several additional securing mechanisms: Basic and Digest Authentication, IP-based restriction, Domain-based restriction, file-based restriction, and, in later releases, encryption. Also, both Secure Sockets Layer (SSL) and Secure HTTP (S/HTTP) will be supported in future releases of Oracle Web Listener and PowerBrowser.
- Client side processing—Additionally, through PowerBrowser, WebSystem provides integrated client-side processing, enabling business-rule processing and sophisticated programmability at the front end as well.

#### 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.

- The WOW PL/SQL packages, previously called HTP and HTF, have been consolidated into a single package called OWA.
- The default signature procedure, wow.sig, is now owa_util.signature.
- The WOW procedure, wow.showsource, is now called owa_util.showsource.
- The WOW C program, wowstub, is now called owa.
- To accommodate the use of existing WOW code, OWA_DEFAULT_SERVICE is provided. It enables the Web administrator to specify the default service owa will use if the URL provides an unknown service. You can think of services as applications or PL/SQL packages.
- The following procedures and functions have been renamed. To accommodate these differences, change the names of the affected subprograms in your application.

    WOW Name
    OWA Name
url | anchor
gif | img
formUndo | formReset
item | listItem
ddef | dlistDef
dterm | dlistTerm

- The use of the following procedures and functions might also require coding changes. The procedure formText is now called formTextarea. The procedure formText is now used for single-line text fields. Text areas are scrollable sections of n-rows by n-columns. In addition to the name change, the new formTextarea also accommodates initialization of the text area. To do this, issue a text outputting call between the formTextareaOpen and the TextareaClose statements.
  ...
  htp.formTextareaOpen('comments',10,60);
  htp.print('This text will appear in the comments field as
  the default text.');
  htp.formTextareaClose;
  ...
- As mentioned previously, the formField procedure required extension to set both its width and initial value. This still applies. However, there is also another required modification. In cases where only the initial value is provided, you should use the following form:
  formText(cname, NULL, NULL, cvalue);
- Fixing a previous limitation, the formDo button has been renamed and extended. It is now called formSubmit in keeping with the HTML name for the object it represents, a submission button. What was previously missing was a means of setting the both the name associated with the name/value pair passed to WOW and the label displayed on the button. You can recode existing calls to formDo as follows:
  formSubmit(NULL, label);
  To fully utilize the feature and enable multiple buttons in a single form, you should instead use the following form:
  formSubmit(cname, cvalue, cattributes);

### WebSystem

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.

### Prerequisites

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:

- Make certain ORACLE_HOME is set.
- Make certain ORACLE_SID is set.
- If installing only the WebServer Option, copy the oweb.tar.Z file to $ORACLE_HOME.

### WebServer Option Installation

Following is the script of one installation:

    # cd $ORACLE_HOME

    # pwd

    /export/home/oracle

    # 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

    /export/home/oracle/owsins/ows/install

    # install.sh

    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.

    Example: oraweb.oracle.com: www.chatsoft.com

    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:

             http://www.chatsoft.com:8888/ows-abin/register

        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

    /export/home/oracle

    $ 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 http://www.chatsoft.com:8888/ows-abin/register. 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 http://www.chatsoft.com/doc/.

Figure 55.6. WebSystem's online documentation.

### Summary

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:

- Thomas Dunbar's site at http://gserver.grads.vt.edu/
- Oracle's home page at http://www.oracle.com/
- The Oracle Users forum on CompuServe
- comp.databases.oracle newsgroup
- comp.infosystems.www newsgroup