6
Configuring the PL/SQL Gateway

This chapter discusses the PL/SQL Gateway, a module provided by Oracle HTTP server powered by Apache and installed with Oracle9i Application Server. The PL/SQL Gateway provides support for building and deploying PL/SQL-based applications on the Web. PL/SQL stored procedures can retrieve data from database tables and generate HTTP responses containing data and code to display in a Web browser.

See also:
"Using the PL/SQL Gateway" guide which is provided as part of the Oracle9i Application Server documentation set.

This chapter contains the following sections:

See also:
For additional information about mod_plsql, see the "Using mod_plsql" guide which is provided with your Oracle9i Application Server documentation.

6.1 Oracle HTTP Server Modules (mods)

In addition to the compiled Apache mods provided with Oracle HTTP server powered by Apache, which support current Internet application technologies to deliver dynamic Web pages, Oracle has enhanced several of the standard mods and has added Oracle-specific mods:

Table 6-1 Oracle HTTP Server Modules (mods)

Module	Description
mod_ssl	Provides standard HTTPS that is fully supported by Oracle; enables secure listener connections with an Oracle-provided encryption mechanism via the Secure Sockets Layer (SSL). See also: Chapter 2, Section 2.8, "Enabling Secure Socket Layer (SSL)".
PL/SQL Gateway including mod_plsql	Routes PL/SQL requests to Oracle8i PL/SQL service, which, in turn, delegates the handling of requests to PL/SQL programs.
mod_perl	Forwards Perl application requests to the Perl Interpreter that is embedded in Oracle HTTP Server, providing power and speed.
mod_jserv	Routes all servlet requests to Apache JServ servlet engine that is embedded in Oracle HTTP Server; can share servlets across multiple zones and ensures that requests get routed to the same servlet engine.

See:
For a list of Oracle9i Application Server documentation, see "Related Publications" in the Preface.

The remainder of this chapter discusses the PL/SQL Gateway.

6.2 Configuring the Oracle HTTP Server powered by Apache

The installation creates configuration files that you can edit, including the following that affect the PL/SQL Gateway:

6.2.1 Oracle HTTP Server powered by Apache Start and Stop Script

This script starts and stops the Oracle HTTP Server powered by Apache and is located in the Oracle Home in which your Oracle HTTP Server is running:

<ORACLE_HOME>/Apache/Apache/bin/apachectl

The contents of this file include three environment variables that affect the PL/SQL Gateway:

Table 6-2 Environment variables set in the apachectl script

Environment Variable	Description
ORACLE_HOME	The Oracle Home in which the PL/SQL Gateway runs. Default: `<ORACLE_HOME>`
LD_LIBRARY_PATH	The Oracle libraries required by the PL/SQL Gateway. This must point to an Oracle 8.1.7 database installation. This parameter is for UNIX only. Default: `<ORACLE_HOME>/lib`
WV_GATEWAY_CFG	The mod_plsql configuration file. Default: `<ORACLE_HOME>/Apache/modplsql/cfg/wdbsvr.app`

If you want to have the PL/SQL Gateway running in another ORACLE HOME, change both the ORACLE_HOME and LD_LIBRARY_PATH settings.

On UNIX, if you want the PL/SQL Gateway to use a different WV_GATEWAY_CFG configuration file, edit the apachectl file to point to the new configuration file.

On Windows NT/2000, choose Start-> Settings-> Control Panel-> System. Click the Environment tab, modify the system variable named WV_GATEWAY_CFG that points to the new WV_GATEWAY_CFG configuration file. Then, restart your computer for all changes to take effect.

6.2.2 Oracle HTTP Server powered by Apache Configuration File

This Oracle HTTP Server configuration file defines the behavior of the Oracle HTTP Server. You can set your port number as well as other server settings in this file. The Oracle HTTP Server powered by Apache configuration file is located in:

<ORACLE_HOME>/Apache/Apache/conf/httpd.conf

6.2.2.1 mod_plsql Setup File

This configuration file describes settings for the mod_plsql module in the PL/SQL Gateway. These settings are configurable:

LoadModule plsql_module <MOD_PATH> - the location of the mod_plsql module.

Default on UNIX:

<ORACLE_HOME>/Apache/modplsql/bin/modplsql.so

Default on Windows NT/2000:

<ORACLE_HOME>/bin/modplsql.dll

<Location <MOUNT_PATH>>

The prefix in the URL for which mod_plsql is invoked. Default: /pls

The mod_plsql setup file is located in:

<ORACLE_HOME>/Apache/modplsql/cfg/plsql.conf

6.2.3 mod_plsql Configuration File

The main mod_plsql configuration file is located in:

<ORACLE_HOME>/Apache/modplsql/cfg/wdbsvr.app

This file contains all the DAD information. Do not edit this file directly. Use the Gateway Database Access Descriptor configuration page in Oracle Portal, which you can access through your browser as shown in Section 6.3, "Accessing the Gateway DAD Configuration Page".

6.3 Accessing the Gateway DAD Configuration Page

You can access the DAD Configuration page from the Oracle Portal user interface or by entering its URL in your Web browser:

6.3.1 Accessing from Oracle Portal

DADs are created from the Database Access Descriptor configuration page in Oracle Portal which you can access in Oracle Portal or via a browser:

In the Services portlet, click Listener Gateway Settings. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.
Click Gateway Database Access Descriptor Settings.
In the Edit/Delete Database Access Descriptors section, click
Text description of the illustration pobrega.gif next to the node's DAD entry. The DAD configuration page is displayed.

6.3.2 Accessing from Browser URL

To access the Gateway Database Access Descriptor configuration page, enter the following URL in your Web browser:

http://<hostname>:<port>/pls/DAD/<admin_path>/gateway.htm

where:

Table 6-3 PL/SQL Gateway URL path

Parameter	Description
`hostname`	The machine where the application server is running. This name must also match the `ServerName` parameter in the Apache configuration file, `httpd.conf`, located in: `<ORACLE_HOME>/Apache/Apache/conf`
`port`	Specifies the port at which the Oracle9i Application Server is listening. If omitted, port 80 is assumed.
`pls`	Defines the virtual path and indicates that the request is for a PL/SQL procedure which alerts the Oracle HTTP Server powered by Apache to reroute the request to the PL/SQL Gateway.
`admin_path`	Specifies the URL path element that identifies an administration page. The default is admin_. For example, if you specify the default of `admin_`, the following URL displays the Gateway DAD configuration page, if the user is listed in the administrators configuration setting: `http://www.myserver.com/pls/admin_/gateway.htm`

Configuration settings are protected by the administration security settings. The Web administration page can only be accessed by those users whose user names appear in the Administrators setting in the configuration file.

6.3.3 plsql.conf Configuration File

The Oracle HTTP Listener configuration file includes the modplsql configuration file named plsql.conf. The contents of plsql.conf are provided in the appropriate section below:

6.3.3.1 UNIX

# 
# Directives added for mod_plsql 
# 
LoadModule plsql_module %ORACLE_HOME%/modplsql/bin/modplsql.so 

# 
# Enable handling of all virtual paths beginning with "/pls" by mod-plsql 
# 
<Location /pls> 
  SetHandler pls_handler 
  Order deny,allow 
  Allow from all 
</Location>

6.3.3.2 Windows NT/2000

#
# Directives added for mod-plsql
# 
LoadModule plsql_module %ORACLE_HOME%\bin\modplsql.dll

#
# Enable handling of all virtual paths beginning with "/pls" by mod-plsql
#
<Location /pls>
  SetHandler pls_handler
  Order deny,allow
  Allow from all
</Location>

Note:
The ORACLE HOME referenced in the plsql.conf file refers to the home location of your Oracle9i Application Server installation.

6.4 Starting and Stopping the Oracle HTTP Server powered by Apache

UNIX

To start the Oracle HTTP Server powered by Apache, enter:

<ORACLE_HOME>/Apache/Apache/bin/apachectl start

To start the Apache listener with SSL. support, enter:

<ORACLE_HOME>/Apache/Apache/bin/httpdsctl startssl

To stop the Oracle HTTP Server powered by Apache, enter:

<ORACLE_HOME>/Apache/Apache/bin/apachectl stop

To start the Oracle HTTP Server powered by Apache with SSL support, enter:

<ORACLE_HOME>/Apache/Apache/bin/apachectl startssl

Note:
You require root access to run this command.

Windows NT/2000

On Windows NT/2000, the Oracle HTTP Server is installed as a service. To start the Oracle HTTP Server with SSL support:

Select Start->Settings->Control Panel.
Select Services.
Highlight the OracleHTTPServer service.
Click Start.

To stop the Oracle HTTP Server:

Select Start->Settings->Control Panel.
Select Services.
Highlight the OracleHTTPServer service.
Click Stop.

6.5 Accessing Help

For more information about the PL/SQL Gateway, click the Help buttons displayed from the following locations:

http://<machine_name>:<port>/pls/admin_/gateway.htm

Click Text description of helpl.gif follows.
Text description of the illustration helpl.gif to display the "Using the PL/SQL Gateway" guide which provides additional information.

Click Text description of helps.gif follows.
Text description of the illustration helps.gif to display Help for configuration parameters on the following displayed mod_plsql pages:

http://<machine_name>:<port>/pls/admin_/globalsettings.htm
http://<machine_name>:<port>/pls/admin_/dadentries.htm

6 Configuring the PL/SQL Gateway