3
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 Oracle Portal. 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. The PL/SQL Gateway supports other Oracle products such as WebDB 2.2 and includes a number of new features.

See also:
"Using the PL/SQL Gateway" guide (A86263-02) 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.

3.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 3-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.6, "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 servicing 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.

3.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:

3.2.1 Oracle HTTP Server powered by Apache start and stop script

This script is used to start and stop 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 3-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 on UNIX: `<ORACLE_HOME>/Apache/modplsql/cfg/wdbsvr.app` Default on Windows NT `<ORACLE_HOME>/Apache/modplsql/cfg/wdbsvr.app`

If you want to have the PL/SQL Gateway running in another Oracle Home, remember to 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, you can 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.

3.2.2 Oracle HTTP Server powered by Apache configuration file

The Oracle HTTP Server powered by Apache configuration file is located in:

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

This configuration file defines the behavior of the Oracle HTTP Server. You can set your port number as well as other server settings.

3.2.2.1 mod_plsql setup file

The mod_plsql setup file is located in:

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

This configuration file describes settings for the mod_plsql module in the PL/SQL Gateway. There 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:
  
  <ORACLE_HOME>/bin/modplsql.dll
<Location <MOUNT_PATH>> - the prefix in the URL for which mod_plsql is invoked.
- Default: /pls

3.2.3 mod_plsql configuration file

The mod_plsql configuration file is located in:

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

This is the main mod_plsql configuration file. It contains all the DAD information. Please 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 3.3, "Accessing the Gateway DAD Configuration Page".

3.3 Accessing the Gateway DAD Configuration Page

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 3-3 PL/SQL Gateway URL path

Parameter Description

Parameter	Description
hostname	Is 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 application server is listening. If omitted, port 80 is assumed.
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 will display the Gateway DAD configuration page, given that the user is listed in the administrators configuration setting: `http://www.myserver.com/pls/admin_/gateway.htm`

hostname

Is 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 application server is listening. If omitted, port 80 is assumed.

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 will display the Gateway DAD configuration page, given that 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.

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

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

3.3.1.2 Windows NT

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

3.4 Starting and Stopping the Oracle HTTP Server powered by Apache

The following commands can be executed from your command prompt in 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.

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

3 Configuring the PL/SQL Gateway