17.1 How do I…Administer Database Access Descriptors (DADs) and Cartridges?

Problem

I have installed Oracle Web Application Server 3.0 and now I want to configure it to access the database by setting up a Database Access Descriptor (DAD). I also need to create a PL/SQL Agent that the PL/SQL Cartridge will use to connect to the database and execute stored procedures. How do I administer DADs and Cartridges?

Technique

Database Access Descriptors (DADs) and PL/SQL Agents are not created automatically during installation, and DADs are required for database access. The PL/SQL Cartridge executes a PL/SQL procedure stored in an Oracle database in response to a web request. It also uses configurable PL/SQL Agents to execute stored procedures and an incoming request is mapped to an appropriate PL/SQL Agent. The DAD associated with PL/SQL Agent is then used to connect to the database. The PL/SQL Agent also contains the necessary information to invoke the database stored procedure. A PL/SQL Agent is a configuration description and not a program. You can use the web-based administration pages to configure and administer DADs and PL/SQL Agents. If you have only one DAD, all web applications connect using the same database account. Different web-based applications can be used to separate DADs in order to manage object privileges.

A new DAD and PL/SQL Agent are created by using the web administration URL. A new user account can be created before creating a DAD, or an existing user account can be assigned to the new DAD. After creating the DAD, a PL/SQL Agent must be created to use the DAD. The PL/SQL Web Toolkit packages can be installed in the user account’s schema when the PL/SQL Agent is created or modified. Once a new PL/SQL Agent is created, the WRB parameters should be configured in order to make a virtual directory reference specifying the PL/SQL Agent and virtual path for the PL/SQL Cartridge. The default port for the administrative listener is port 8888.

Steps

1. By default, the installation procedure assigns 8888 as the port number for the administration Web Listener and port 80 for the default WWW Web Listener. The WRB processes and the administration Web Listener services must be started, which can be done by using either one of the following two procedures:

a) Select the Control Panel menu option from the Settings section of the Windows NT start menu. Enter the NT service manager by double-clicking Services. For each of the services—starting with OracleWWWListener30, OraMedia, OraWeb—if the status of the service is Stopped, then click the Start button to start the service. If the Startup column for the service indicates Manual and you want the service to start automatically whenever there is a request for that service, then double-click the line describing the service or single click the Startup button. Now click the radio button to the left of the word Automatic and click the OK button. Do not change the Web Listener’s OracleListener30ADMIN and OracleListenerWWW to Automatic startup mode. Start the OracleListener30ADMIN and the OracleListenerWWW Web Listeners, if the status of the service is Stopped. Ensure that the Oracle SQL*NET services and the database have been started on the host. The Windows NT Service Manager is shown in Figure 17.1.

b) The owsctl utility can be used to start, stop, reload, and display the status of listeners and Cartridge processes. The owsstat utility is used to monitor the status of the Web Listener. The syntax for these commands is as follows:

owsctl { start | stop | reload | status }

owsctl { start | stop | status } { [-e] wrb | cartridge | -p

| ncx }

owsctl { start | stop | status } -stat listener_name [ -p

| -uri | -timeout | -action

]

In order to start the WRB processes and the Web Listener services, you need to open a DOS window and type three simple commands:

C:\ORANT\OWS\3.0\BIN>owsctl start wrbj

C:\ORANT\OWS\3.0\BIN>owsctl start admin

C:\ORANT\OWS\3.0\BIN>owsctl start www

2. Run a web browser and open the http://localhost:8888/ URL, where localhost is the host name of the machine on which OWAS 3.0 is installed and 8888 is the default port number assigned to the administration Web Listener. You will be prompted for the web administration user name and password, which are case-sensitive. Follow the links to install a new DAD by clicking the Create New DAD link. Enter the values as shown in Figure 17.2.

The DAD name field specifies the name of the DAD to be created. The Database User field contains the name of the user account that will be used to connect to the database. If the user account does not exist, it can be created in this process.

The Identified by field specifies how the password is supplied while connecting to the database. The ORACLE_HOME field defaults to the current value of ORACLE_HOME for the default database. The ORACLE_SID field specifies the system identifier of the local database to which the user connects. If the Web Agent is not on the same computer as the database, use the SQL*NET V2 Service field instead. The checkbox for Store the User Name and Password in DAD should be checked. Click the Submit New DAD button to create the new DAD. Figure 17.3 shows the results of the operation.

3. Follow the links to install a new PL/SQL Agent: Click Cartridge Administration, PL/SQL Cartridge, and then Create New PL/SQL Agent. Enter the values as shown in Figure 17.4. The Name of PL/SQL Agent field specifies the name of the new PL/SQL Agent to be installed. In the select list for Name of DAD To Be Used, select the newly created WAITES DAD created in Step 2. The Protect PL/SQL Agent select list specifies whether or not you want to protect the PL/SQL Web Toolkit procedures and packages directly accessed from the URLs. The default is TRUE, to provide a secure application environment. The Authorized Ports field specifies the web listener ports the PL/SQL Agent will use. A Web Listener must be set to listen to the port specified. By default, port 80 is assigned to WWW Web Listener during the installation of OWAS 3.0. If you need to add, delete, start, and stop Web Listeners or to configure existing ones, the http://localhost:8888/ows-abin/wladmin URL can be used.

The rest of the fields are optional. The HTML Error Page field is used to specify the pathname of an HTML file to be displayed when an error occurs. If you leave this field blank, the PL/SQL Cartridge returns a default error message. The Error Level field specifies the error level of reporting to use to display detailed error messages in the client browser from the Web Application Server and database server. This parameter takes values between 0 and 2; 0 masks all errors, 1 includes the time stamp from the error, and the name of the URL accessed. With 2, it displays all the information about the error in a HTML page. It includes the timestamp, the URL that called the PL/SQL procedure name, and parameters. The checkbox for Install Web Application Server Developer’s Toolkit PL/SQL Packages should be checked in order to install the PL/SQL Toolkit packages into the schema of the user account specified in the DAD. If you have already installed the packages for the DAD, you do not need to re-install them. Press the Submit New Agent button to create the new PL/SQL Agent. Figure 17.5 shows the results of the operation.

4. To configure the WRB parameters for the PL/SQL Cartridge, follow the Configure Web Request Broker Parameters for PL/SQL link from the main PL/SQL Agent administration page. The Update Cartridge form appears. Move to the Virtual Paths section of the document by scrolling through the document. Add a new line here with /OWA_WAITE/PLSQL to the Virtual Path and %ORAWEB_HOME%\bin to the Physical Path. This causes any URL beginning with /OWA_WAITE/PLSQL to be handled by the PL/SQL Cartridge in the %ORAWEB_HOME%\BIN directory. Without this entry, the user will receive an URL not found error when attempting to use the new service. Click the Modify Cartridge button to apply the changes. Once the changes to the Cartridge are successfully made, it must be restarted for the changes to take effect.

5. Stop and start the Web Listener named WWW to make the changes effective. You can do this from the http://localhost:8888/ows-abin/wladmin document where you can click the Stop link to stop the port 80 listener.

After the listener has been stopped, click the Start link to restart the listener. Alternatively, you can use any of the two methods from Step 1. You also need to stop and restart the WRB processes for the WRB configuration changes to be effective. You can test samples from http://localhost:8888/samples.html and examples from this chapter to test whether the installation and configuration was done properly.

How It Works

A new DAD and PL/SQL Agent combination enables you to have applications to use separate user accounts for accessing the database. Agents are created and maintained through the Web Agent administration forms. The administration listener must be started before you can access these forms. Once an Agent is created, the WRB must be modified to include the virtual directories for referencing the Agent.

Step 1 shows how you can start and stop Web Listeners from the Control Panel or by using the owsctl utility. Step 2 creates a new DAD and Step 3 creates a new PL/SQL Agent. Step 4 configures the WRB parameters for the PL/SQL Cartridge to include the virtual directory for the new service. Step 5 restarts the Web Listener for the changes to take effect.

Comments

In previous versions, a separate Web Listener was required for applications using different user accounts. With OWAS 3.0, you can use the same Web Listener but simply create a new DAD and a PL/SQL Agent that makes use of the new DAD. If you want separate Web Listeners, then you can set that up as well by creating new Web Listeners and having the PL/SQL Agent accept requests from the ports serviced by one or more Web Listeners.