5
Configuring the WebDB Listener and PL/SQL Gateway

After you have installed Oracle WebDB, you may need to configure the WebDB Listener and PL/SQL Gateway settings to ensure optimal performance.

This chapter contains the following sections:

5.1 Access From Within WebDB

To configure the Listener or PL/SQL Gateway from within WebDB, clickat the bottom of any WebDB page, then Listener Settings. A page displays fields for changing PL/SQL Gateway settings. To change Listener Settings, click the hypertext link Change Listener Settings at the top of the page.

Click the small help icon at the top of either page to display field-level help.

5.2 Access from Outside WebDB

To configure the Listener from outside WebDB, type the following URL into your Web browser's location or address field:

http://servername:port/admin_/listener.htm

To configure the PL/SQL Gateway from outside WebDB, type the following URL into your Web browser's location or address field:

http://servername:port/admin_/gateway.htm

where:

servername is the name of the server on which you installed WebDB.
port is the port you specified during installation of WebDB.

5.3 Starting and Stopping the WebDB Listener

You can manually start and stop the WebDB Listener from a command line prompt. In fact, if you have multiple Listeners on a single machine, this is the only way to start or stop them individually.

5.3.1 Windows NT

To start or stop the WebDB Listener on Windows NT:

To avoid any conflict between multiple Listeners, you must first reset the WebDB Listener Service from "Automatic" startup to "Manual" from the Windows NT Control Panel Services.
To start or stop the WebDB Listener in Windows NT, execute the appropriate command:
```
wdblsnr -console host port start 
wdblsnr -console host port stop 
```
where:

host is the name of the server on which you installed WebDB.

port is the port you specified during installation of WebDB.

5.3.2 Solaris

To start or stop the WebDB Listener on Solaris, execute the appropriate command:

wdbstart host port start
wdbstart host port stop

where:

host is the name of the server on which you installed WebDB.

port is the port you specified during installation of WebDB.

Additional Information: If you encounter a problem starting the WebDB Listener, see Chapter 9, "Troubleshooting" for help.

5.4 Configuring Oracle WebDB Listener

Listener settings that you can configure include directory mappings, MIME types, and the URL for the WebDB Home page. The WebDB Listener configuration file, wdbsvr.cfg, is located in the <ORACLE_HOME>\listener\cfg directory.

The following is the Oracle WebDB Listener Settings page:

Tip:
To display a specific HTML page after users log on to WebDB, enter a URL in the Home Page field. This setting overrides the DAD's Default (Home) page setting on the Oracle PL/SQL Gateway Settings page.

5.5 Configuring Oracle WebDB PL/SQL Gateway

The WebDB PL/SQL Gateway settings that you can configure include the Database Access Descriptor (DAD) settings for each instance you installed in the database and for each Web site you created using Oracle WebDB, including sites for public access.

The WebDB PL/SQL Gateway configuration file, wdbsvr.app, contains these settings.

The following is the Oracle WebDB PL/SQL Gateway page:

To get information for the current page, click the small Help icon on that page.

Note:
For security reasons, you may want to restrict access to the Oracle WebDB PL/SQL Gateway Settings page to authorized users. To do this edit the wdbsvr.app configuration file. See the administrators parameter section in "Editing WebDB Gateway Settings (wdbsvr.app)" for details.

5.6 Using the WebDB Listener to Run Multiple Virtual Hosts

You can set up WebDB to run multiple virtual hosts or instances of the WebDB Listener on the same machine. The best way to do this is to run the WebDB Listener from the command line.

The following example lists two commands that start two instances of the Listener, one bound to www.oracle.com and the other to web.oracle.com.

Windows NT

start wdblsnr -console www.oracle.com 80 start
start wdblsnr -console web.oracle.com 80 start

Solaris

wbstart www.oracle.com 80 start
wbstart web.oracle.com 80 start

The two instances will share the same configuration file because they are run with the WV_GATEWAY_CFG environment variable set to the same value.

On Windows NT, the WebDB Listener is controlled from the Services control panel by setting the WV_GATEWAY_CFG environment variable. However, Windows NT allows you to configure only one instance of the WebDB Listener from the Services Control Panel.

You can resolve this problem by writing a script that will easily set the correct environment variable and read the appropriate configuration file before starting an instance of the Listener. Create a script for each virtual host so that its associated Listener will read the correct configuration file.

On Windows NT, the contents of a simple batch file which starts two instances of the Listener might look like this:

SET WV_GATEWAY_CFG=D:\orant\listener\cfg\wdbsvr.app
start wdblsnr -console www.oracle.com 80 start 
SET WV_GATEWAY_CFG=D:\orant\listener\cfg\wdbsvr2.app
start wdblsnr -console web.oracle.com 80 start

You can have this batch file run at startup on Windows NT by editing the Windows NT registry with regedit in the following way:

\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

5.7 Accessing Static Files with the WebDB Listener

The WebDB Listener can access static files from your local file system. This is useful if you want to launch another WebDB application from this static HTML page. The Listener's virtual directory mappings must be configured to map URLs to your local file system.

The settings for these directory mappings can be configured from the Oracle WebDB Listener Settings page at:

http://yourhostname:port/admin_/listener.htm or from within WebDB

The following is the configuration panel for the WebDB Listener directory mappings:

To access static files with the WebDB Listener:

Choose a physical directory on your file system and copy the files you wish to access on the Web into that directory.
In the Physical Directory field, type the name of that directory.
In the corresponding Virtual Directory field, type a short name (virtual directory) to associate to the physical directory and click Apply.

For example, if the URL is http://myhost/public/test.html, the WebDB Listener will access test.html from the D:\Public directory on your local file system.

Note:
Be sure to add a trailing slash to each file-system and virtual directory name.
The WebDB Listener can access any type of file as long as your Web browser recognizes that file via the Listener's MIME type settings. The Listener includes default MIME types for most of the major file types. To configure new MIME types, type the string for the MIME type in the left column and the associated file extension in the right column as shown below. Once configured, the Listener sends the browser the correct MIME type and handles the file accordingly.

To verify that the directory mappings are recognized by the WebDB Listener, you can test them from your browser by typing:

http://<myserver>:<port>/<directory>/<htmlfilename>

5.8 Running PL/SQL Applications Using the WebDB Listener

The WebDB Listener is designed to run the PL/SQL packages included in WebDB and is therefore also well-suited to running other types of PL/SQL applications over the Web.

For example, you can create a new procedure using the Oracle WebDB Procedure Object Builder, storing it in the SCOTT schema and naming it "test". The following PL/SQL code creates the procedure.

Because the procedure is owned by SCOTT, you can configure the Listener to run PL/SQL Web applications from the SCOTT schema. This is done by setting the Database Access Descriptor Name to "SCOTT" on the Oracle WebDB PL/SQL Gateway Settings page (see screen).

Once the changes are applied, pointing your Web browser's location or address field to http://yourhostname:port/scott/scott.test displays the following page.

5.9 Manually Editing the Listener and Gateway Configuration Settings

Note:
This section is for advanced users only as manually editing configuration files without proper knowledge or guidance may cause adverse results to the WebDB Listener.

If you want greater control of the WebDB Listener and gateway settings, you can edit the WebDB Listener and PL/SQL Gateway configuration files in a text editor instead of using the WebDB Listener administration's user interface. All Listener and PL/SQL Gateway settings that you can specify within WebDB can be edited in the wdbsvr.app and wdbsvr.cfg files.

File Windows NT Location UNIX Location

Oracle WebDB Listener
wdbsvr.app

<ORACLE_HOME>\listener\cfg

<ORACLE_HOME>/webdb/listener/cfg

Oracle PL/SQL Gateway
wdbsvr.cfg

<ORACLE_HOME>\listener\cfg

<ORACLE_HOME>/webdb/listener/cfg

File	Windows NT Location	UNIX Location
Oracle WebDB Listener `wdbsvr.app`	`<ORACLE_HOME>\listener\cfg`	`<ORACLE_HOME>/webdb/listener/cfg`
Oracle PL/SQL Gateway `wdbsvr.cfg`	`<ORACLE_HOME>\listener\cfg`	`<ORACLE_HOME>/webdb/listener/cfg`

Notes:

To enable a parameter in the configuration file, make sure to remove the semi-colon (;) at the beginning of the parameter name. The semi-colon "comments out" the parameter.

These configuration files are organized into sections which are identified by brackets [ ].

5.9.1 Editing WebDB Gateway Settings (wdbsvr.app)

Use the information on the following table to help you configure the WebDB Listener settings appropriately. The table lists and describes the parameters contained in the wdbsvr.app file:

Parameter Description

[WVGATEWAY]

Marks the start of the gateway section.

defaultDAD

Specify a path that points to the default DAD. If the end user types a WebDB URL without specifying the DAD name, the home page for the default DAD will be displayed.
Default = WebDB

administrators

Allows you to specify those users who will have access to WebDB's administration pages (gateway.htm, listener.htm).
By default, this is set to "all" which permits any user to access these pages. To enforce security on these pages, type a comma separated list of users (administrators).
For example:
administrators = user1, user2, user3@webdb
Only the users who log on as user1, user2, and user3 with the correct password can access the gateway settings page on the webdb host (connect string).
Default = all

adminPath

The virtual directory location containing the gateway files. For example, the end user can type the following to display the gateway page:
http://myhost/WebDB/admin_/gateway.htm?schema=WEBDB
where /admin_ is the adminPath
Default = /admin_/

debugModules

Used to generate complete logging information. This parameter is enabled only when a problem is encountered and logging information is required by an Oracle representative to help resolve the problem.
Default = commented

[DAD_WebDB]

Marks the start of the first Database Access Descriptor (DAD) section. In this case, the DAD is named "WebDB." The WebDB's URL is based on this DAD name.
You can change this name by typing a new name.
Default = WebDB

connect_string

Type the tnsnames alias if you are using a remote database. Leave this parameter blank if the database is local.
Default = blank

password

Refers to the Oracle database account password. The password is typically set at WebDB installation, but you can change it by typing a new password for this parameter.
Note: There should always be an Oracle User Name and Password for PUBLIC Web site DADs. This enables public users to access the WebDB site without having to log on.
Default = blank

username

Refers to the Oracle database account user name. The user name is typically set at WebDB installation or during creation of new WebDB sites. You can change it by typing a new name for this parameter.
Default = WebDB

default_page

Refers to the WebDB default Home page. You can change it by typing a new name for this parameter.
Default = WEBDB.home

document_table

(For DADs related to the WebDB Site Builder features only.)
Type the name of the database table to be used for storing uploaded files. The default value for this parameter is based on the name of the schema in which you created the WebDB site.
Default = WEBDB.wwv_document

document_path

(For DADs related to the WebDB Site Builder features only.)
Type a path in the URL for the current installation that is used to indicate a document is being referenced.
The default value for this parameter is based on the name of the schema in which you created the WebDB site.
Default = docs

document_proc

(For DADs related to the WebDB Site Builder features only.)
Type the procedure that will be used to upload and download documents.
Default = based on the name of the schema in which you created the WebDB site.
For example, WEBDB.wwv_testdoc.process_download

after_proc

To execute a particular stored procedure after execution of every other stored procedure. For example,
after_proc = webdb.show_footer
This stored procedure would display the footer after a stored procedure is executed.
Default = commented (null)

before_proc

To execute a particular stored procedure before execution of every other stored procedure. For example,
before_proc = webdb.show_header
This stored procedure would display the header before a stored procedure is executed.
Default = commented (null)

reuse

Allows you to choose whether, after processing one URL request, the database connection should be kept open to process future requests. In most configurations, specify Yes for maximum performance.
Default = Yes

conmax

Type the number of simultaneous connections allowed to the database that will be used to service applications.
Tip You'll need to adjust this number depending on your server, its capacity, and the number of connected users. As a rule of thumb, set this number at between 5 and 10 at a medium sized installation (approximately 200 users).
Default = 4

Parameter	Description
[WVGATEWAY]	Marks the start of the gateway section.
defaultDAD	Specify a path that points to the default DAD. If the end user types a WebDB URL without specifying the DAD name, the home page for the default DAD will be displayed. Default = WebDB
administrators	Allows you to specify those users who will have access to WebDB's administration pages (gateway.htm, listener.htm). By default, this is set to "all" which permits any user to access these pages. To enforce security on these pages, type a comma separated list of users (administrators). For example: `administrators = user1, user2, user3@webdb` Only the users who log on as user1, user2, and user3 with the correct password can access the gateway settings page on the webdb host (connect string). Default = `all`
adminPath	The virtual directory location containing the gateway files. For example, the end user can type the following to display the gateway page: http://myhost/WebDB/admin_/gateway.htm?schema=WEBDB where `/admin_` is the `adminPath` Default = `/admin_/`
debugModules	Used to generate complete logging information. This parameter is enabled only when a problem is encountered and logging information is required by an Oracle representative to help resolve the problem. Default = commented
[DAD_WebDB]	Marks the start of the first Database Access Descriptor (DAD) section. In this case, the DAD is named "WebDB." The WebDB's URL is based on this DAD name. You can change this name by typing a new name. Default = WebDB
connect_string	Type the tnsnames alias if you are using a remote database. Leave this parameter blank if the database is local. Default = blank
password	Refers to the Oracle database account password. The password is typically set at WebDB installation, but you can change it by typing a new password for this parameter. Note: There should always be an Oracle User Name and Password for PUBLIC Web site DADs. This enables public users to access the WebDB site without having to log on. Default = blank
username	Refers to the Oracle database account user name. The user name is typically set at WebDB installation or during creation of new WebDB sites. You can change it by typing a new name for this parameter. Default = WebDB
default_page	Refers to the WebDB default Home page. You can change it by typing a new name for this parameter. Default = `WEBDB.home`
document_table	(For DADs related to the WebDB Site Builder features only.) Type the name of the database table to be used for storing uploaded files. The default value for this parameter is based on the name of the schema in which you created the WebDB site. Default = `WEBDB.wwv_document`
document_path	(For DADs related to the WebDB Site Builder features only.) Type a path in the URL for the current installation that is used to indicate a document is being referenced. The default value for this parameter is based on the name of the schema in which you created the WebDB site. Default = docs
document_proc	(For DADs related to the WebDB Site Builder features only.) Type the procedure that will be used to upload and download documents. Default = based on the name of the schema in which you created the WebDB site. For example, WEBDB.wwv_testdoc.process_download
after_proc	To execute a particular stored procedure after execution of every other stored procedure. For example, `after_proc = webdb.show_footer` This stored procedure would display the footer after a stored procedure is executed. Default = commented (null)
before_proc	To execute a particular stored procedure before execution of every other stored procedure. For example, `before_proc = webdb.show_header` This stored procedure would display the header before a stored procedure is executed. Default = commented (null)
reuse	Allows you to choose whether, after processing one URL request, the database connection should be kept open to process future requests. In most configurations, specify Yes for maximum performance. Default = Yes
conmax	Type the number of simultaneous connections allowed to the database that will be used to service applications. Tip You'll need to adjust this number depending on your server, its capacity, and the number of connected users. As a rule of thumb, set this number at between 5 and 10 at a medium sized installation (approximately 200 users). Default = 4

Note:
WebDB creates three DADs for each WebDB site: public, private, and administrator. Configure each DAD section in the file as required using the above table.

5.9.2 Editing WebDB Listener Settings (wdbsvr.cfg)

Use the information on the following table to help you configure the WebDB PL/SQL Gateway settings appropriately. The table lists and describes the parameters contained in the wdbsvr.cfg file:

Parameter Description

[SERVER]

Marks the start of the Server section.

HomePage

Refers to the WebDB default Home page. You can change it by typing a new name for this parameter.
Note: The setting for this parameter overrides the default DAD setting in the gateway configuration file, wdbsvr.app.

DefaultMimeType

Displays the MIME type that is used by the Listener when a MIME type for a given URL request can't be determined.
Default = application/octet-stream

LoggingLevel

Displays how much logging information will be captured by logging files located in the Listener log directory. You can use this information for debugging purposes and for performance analysis.
You may want to test the following Logging Level settings to determine how much logging information you want to capture:
NONE, STANDARD, TEST, ETEST, EXTENDED, ERROR, DEBUG, EDEBUG
Default = EXTENDED

MaxCGIThreads

Not used for WebDB CGI. This parameter is currently used by Oracle Reports.
Default = 5

MaxFileThreads

Displays the number of threads that serve static files off the file system. As a rule of thumb, increasing the number of threads improves performance, although this is contingent on operating system limitations.
Default = 5

MaxDispatcherThreads

Displays the number of threads used to dispatch HTTP requests. As a rule of thumb, increasing the number of threads improves performance, although this is contingent on operating system limitations.
Default = 7

MaxQueueSize

Connection requests from clients are queued up to a maximum queue size. This parameter determines the maximum length of the queue for pending connections on the Listener socket.
If a connection request arrives and the Listener queue is full, the client receives an error, "Connection Refused".
Default = 64

ReceiveTimeOut

This parameter determines the number of seconds the Listener will wait to receive data from across the network before it signals a timeout.
This parameter should be configured according to your network connection. If you have a really slow network connection, you may want to increase this parameter so that the Listener waits longer before timing out. For Example, to set the timeout to 2 minutes, add the following line
ReceiveTimeOut = 120
Default = 60 (seconds)

OnlyClient

This parameter can be used to restrict access to the WebDB Listener so that only a specific client can access it. This parameter can be set to a specific IP address and only a client having that specific IP address will have access to the Listener. For example, setting this value to the following:
OnlyClient = 144.25.84.254
will restrict access so that only a client with an IP address of 144.25.84.254 can access the Listener.

[DirMaps]

Marks the start of the directory mapping section. Is used to map virtual directories specified in your WebDB URL to physical directories on the filesystem.

[CGIDirMaps]

Marks the start of the CGI directory mapping section. Currently used with Oracle Reports and Oracle Forms.

[MIMETypes]

Marks the start of the MIME types section.
Each line contains the type of file and the file extension(s) that WebDB recognizes.
Default WebDB MIME Types are used when returning content to the browser as a result of a URL request.

audio/x-wav

wav

text/html

htm   html

image/jpeg

jpg   jpeg   JPG

image/gif

gif   GIF

text/plain

txt   jsg   1st

application/pdf

pdf

application/powerpoint

ppt   PPT

application/msword

doc   dot   DOC   DOT

application/x-tar

tar   TAR

application/zip

zip

text/edi

edi

application/excel

xls   XLS

x-world/x-vrml

vrml

application/x-gzip

gz   Z

application/x-director

dcr

application/oracle-magic

yyy

application/oracle-video

mpi   mpg   osf

Parameter	Description
[SERVER]	Marks the start of the Server section.
HomePage	Refers to the WebDB default Home page. You can change it by typing a new name for this parameter. Note: The setting for this parameter overrides the default DAD setting in the gateway configuration file, wdbsvr.app.
DefaultMimeType	Displays the MIME type that is used by the Listener when a MIME type for a given URL request can't be determined. Default = application/octet-stream
LoggingLevel	Displays how much logging information will be captured by logging files located in the Listener log directory. You can use this information for debugging purposes and for performance analysis. You may want to test the following Logging Level settings to determine how much logging information you want to capture: NONE, STANDARD, TEST, ETEST, EXTENDED, ERROR, DEBUG, EDEBUG Default = EXTENDED
MaxCGIThreads	Not used for WebDB CGI. This parameter is currently used by Oracle Reports. Default = 5
MaxFileThreads	Displays the number of threads that serve static files off the file system. As a rule of thumb, increasing the number of threads improves performance, although this is contingent on operating system limitations. Default = 5
MaxDispatcherThreads	Displays the number of threads used to dispatch HTTP requests. As a rule of thumb, increasing the number of threads improves performance, although this is contingent on operating system limitations. Default = 7
MaxQueueSize	Connection requests from clients are queued up to a maximum queue size. This parameter determines the maximum length of the queue for pending connections on the Listener socket. If a connection request arrives and the Listener queue is full, the client receives an error, "Connection Refused". Default = 64
ReceiveTimeOut	This parameter determines the number of seconds the Listener will wait to receive data from across the network before it signals a timeout. This parameter should be configured according to your network connection. If you have a really slow network connection, you may want to increase this parameter so that the Listener waits longer before timing out. For Example, to set the timeout to 2 minutes, add the following line `ReceiveTimeOut = 120` Default = 60 (seconds)
OnlyClient	This parameter can be used to restrict access to the WebDB Listener so that only a specific client can access it. This parameter can be set to a specific IP address and only a client having that specific IP address will have access to the Listener. For example, setting this value to the following: `OnlyClient = 144.25.84.254` will restrict access so that only a client with an IP address of 144.25.84.254 can access the Listener.
[DirMaps]	Marks the start of the directory mapping section. Is used to map virtual directories specified in your WebDB URL to physical directories on the filesystem.
[CGIDirMaps]	Marks the start of the CGI directory mapping section. Currently used with Oracle Reports and Oracle Forms.
[MIMETypes]	Marks the start of the MIME types section. Each line contains the type of file and the file extension(s) that WebDB recognizes. Default WebDB MIME Types are used when returning content to the browser as a result of a URL request.
audio/x-wav	wav
text/html	htm html
image/jpeg	jpg jpeg JPG
image/gif	gif GIF
text/plain	txt jsg 1st
application/pdf	pdf
application/powerpoint	ppt PPT
application/msword	doc dot DOC DOT
application/x-tar	tar TAR
application/zip	zip
text/edi	edi
application/excel	xls XLS
x-world/x-vrml	vrml
application/x-gzip	gz Z
application/x-director	dcr
application/oracle-magic	yyy
application/oracle-video	mpi mpg osf

Note:
You can add additional MIME types to this list to support other file types that you plan to have on your database.

5Configuring the WebDB Listener and PL/SQL Gateway