2
Configuring Oracle Plug-in for Microsoft IIS

This chapter describes how to register and load Oracle Plug-in for Microsoft IIS and how to configure access to PL/SQL and Java Web components.

This chapter contains these topics:

• Prerequisites

• Registering Oracle Plug-in for Microsoft IIS for Web Component Access

• Loading Oracle Plug-in for Microsoft IIS

• Stateless Versus Stateful Transactions

• PL/SQL Web Component Access

• Java Web Component Access

Prerequisites

Enabling PL/SQL and Java Web component usage requires the following:

• Client Configuration: You have installed Oracle Plug-in for Microsoft IIS on the same computer as IIS. For installation details, see the installation guide for your product.

• Back-end Database Configuration: You have installed Oracle8i release 8.1.7 database server. Oracle Servlet Engine (OSE) server resides within the Oracle database.

• You have developed and published your PL/SQL and Java Web components.

Software Requirements

The following are the software requirements for Oracle Plug-in for Microsoft IIS.

Software	Version
Operating System	Microsoft Windows NT 4.0 with Service Pack 3.0 and above
Web server	Microsoft Internet Information Server (IIS) 4.0 and above
Web browsers	Netscape 4.0.8 and above Microsoft Internet Explorer 4.0.1 with Service Pack 1 and above

Registering Oracle Plug-in for Microsoft IIS for Web Component Access

To access PL/SQL and Java Web components in the IIS environment, you must configure an Internet Server Application Programming Interface (ISAPI) filter that is triggered when each HTTP request is processed.

ISAPI filters use Dynamic Link Libraries (DLLs) to redirect client HTTP requests passed to the Web server. The filter is executed within the IIS process. ISAPI loads a single instance of the DLL in the IIS memory space and remains in memory, where it can carry out additional requests, until IIS is stopped or restarted.

After the filter is loaded within the IIS process, it redirects all HTTP requests to the filter which checks for PL/SQL and Java Web component configuration information. If the configuration parameters are present, then the filter rewrites the request for the ISAPI extension and the extension executes the request. Otherwise, the request is passed back to IIS for processing.

This section describes the tasks to register Oracle Plug-in for Microsoft IIS.

• Task 1: Creating a New ISAPI Filter

• Task 2: Creating a New Virtual Directory

• Task 3: Setting the Directory Security

Task 1: Creating a New ISAPI Filter

1. From Microsoft Management Console (MMC), right-click the Web site where you are configuring the Oracle Plug-in for Microsoft IIS filter and select Properties.

2. Select the ISAPI Filters tab and choose Add.

   The Filter Properties dialog box appears.

   
   
   Text description of the illustration fltrprop.gif
3. Enter the following information for Oracle Plug-in for Microsoft IIS ISAPI filter:
   • Filter Name: (enter any name)

   • Executable: x:\ORACLE_BASE\ORACLE_HOME\bin\oraiisp8.dll

     where x is the hard drive and \ORACLE_BASE\ORACLE_HOME\ is the root directory of the Oracle Plug-in for Microsoft IIS installation.

4. Choose OK, and then Apply.

   Note: If other ISAPI filters are also installed, then make sure there is no conflict in functionality between the filters. Consult your Microsoft documentation for more information.

Task 2: Creating a New Virtual Directory

1. From MMC, right-click the Web site where you are enabling the filter and select New > Virtual Directory.

   The New Virtual Directory Wizard appears.

   
   
   Text description of the illustration wiz1.gif
2. Enter OraclePlugin as the alias for the new virtual directory.

   Note: The virtual directory name is not case-sensitive but must be one word and called OraclePlugin.

3. Choose Next.

   
   
   Text description of the illustration wiz2.gif

4. Enter the physical path such as x:\ORACLE_BASE\ORACLE_HOME\bin.

5. Choose Next.

   
   
   Text description of the illustration wiz3.gif

6. Accept the default settings, Allow Read Access and Allow Script Access, and then select Allow Execute Access (includes Script Access).

7. Choose Finish.

Task 3: Setting the Directory Security

1. From MMC, right-click the virtual directory you just created and select Properties.

   The OraclePlugin Properties dialog box appears.

   
   
   Text description of the illustration dirprops.gif
2. Select the Directory Security tab.

3. Choose Edit in the Anonymous Access and Authentication Control section.

   The Authentication Methods dialog box appears.

   
   
   Text description of the illustration authmeth.gif
4. Deselect Windows NT Challenge/Response.

5. Select Basic Authentication (Password is sent in Clear Text).

6. Choose OK.

   Note: HTTPS is supported for additional security.

Loading Oracle Plug-in for Microsoft IIS

This section provides information about the following:

• Starting and Stopping the Web Service

• Verifying Oracle Plug-in for Microsoft IIS Status

Starting and Stopping the Web Service

The Web site where Oracle Plug-in for Microsoft IIS is configured must be stopped and restarted to load the plug-in's ISAPI filter.

1. From MMC, right-click the Web site where Oracle Plug-in for Microsoft IIS is configured and select Stop.

   The Web service is stopped.

2. Right-click the Web site where Oracle Plug-in for Microsoft IIS is configured and select Start.

   The Web service is restarted.

   Note: You may have to reboot IIS in order to load Oracle Plug-in for Microsoft IIS.

Verifying Oracle Plug-in for Microsoft IIS Status

Before you can access PL/SQL and Java Web components, the Oracle Plug-in for Microsoft IIS must be registered and loaded within IIS.

To check the status of Oracle Plug-in for Microsoft IIS, perform the following steps:

1. From MMC, right-click the Web site where Oracle Plug-in for Microsoft IIS is configured and select Properties.

2. Choose the ISAPI Filters tab.

3. Select Oracle Plug-in from the list box.

   In the details information box, the filter status should be Loaded.

   
   
   Text description of the illustration filtload.gif

   Note: If the Oracle Plug-in for Microsoft IIS filter is not loaded, then reboot your computer.

Stateless Versus Stateful Transactions

Oracle Plug-in for Microsoft IIS provides support for building and deploying the following:

• Stateless PL/SQL stored procedures

• Stateless PL/SQL Server Pages

• Stateful and stateless JavaServer Pages

• Stateful and stateless Java servlet

Web components can retrieve data from database tables and generate HTTP responses to display in a Web browser.

In a stateless environment, each HTTP request from a client maps to a new database session. Application state is typically maintained in HTTP cookies or database tables. Transaction state cannot span across requests. If a Web component executes successfully, an implicit commit is performed. If it executes with an error, an implicit rollback is performed.

In a stateful environment, each HTTP request from a client maps to the same database session. A transaction can span across requests because no implicit commits or rollbacks are performed.

PL/SQL Web Component Access

PL/SQL Web components are PL/SQL stored procedures written using the PL/SQL Web Toolkit and PL/SQL Server Pages.

Access to PL/SQL Web components stored in the Oracle database requires Database Access Descriptors (DADs). Typical DADs store the connection information of the Oracle database (the connect string which is also knows as the network service name) containing the stored procedures that you want to execute. Also, DADs contain optional information such as authentication mode, connection pooling, and username and password information.

Oracle Plug-in for Microsoft IIS uses Apache's PL/SQL Gateway Configuration Menu (mod_plsql) Web page to configure DADs.

Oracle Plug-in for Microsoft IIS supports only stateless PL/SQL Web components. However, a component can contain state information in a common store such as a database or browser cookie.

See Also: "Creating Web Components" for information about the PL/SQL Web Toolkit Using the PL/SQL Gateway for detailed information about DAD settings and the Gateway Configuration Menu

Setting up Web Access

This section provides information about the following:

• Accessing the PL/SQL Gateway Configuration Menu

• Configuring PL/SQL Web Component Access

Accessing the PL/SQL Gateway Configuration Menu

Enter the following URL in your Web browser to display the Gateway configuration Menu:

http://hostname[:port]/prefix/admin_path/

Where...	Specifies...
hostname	The computer where IIS is running.
port	The port at which IIS is listening for Web components. If omitted, port 80 is assumed.
prefix	The virtual path mapped to Oracle Plug-in for Microsoft IIS. This setting must be pls
admin_path	The URL path element that identifies an administration page. The default is admin_

Figure 2-1 shows the Gateway Configuration Menu.

Figure 2-1 Configuring PL/SQL Web Component Access

Text description of the illustration gwconfig.gif

Configuring PL/SQL Web Component Access

PL/SQL Web component access is determined by DADs configured from the Gateway Configuration Menu. From the Gateway Configuration Menu choose the Gateway Database Access Descriptor Settings link. See Figure 2-1.

See Also: Using the PL/SQL Gateway for detailed information about DAD settings, the Gateway Configuration Menu, and sample URLs for accessing PL/SQL Web components.

When configuring DADs, leave the Session State set to No because Oracle Plug-in for Microsoft IIS does not support stateful PL/SQL Web components.

Note: Each DAD Session State must be set to No.

Java Web Component Access

Before accessing Java Web components you must:

1. Publish your Java components in the Oracle Servlet Engine (OSE) server. OSE is a built-in Web server running inside the Oracle8i release 8.1.7 database which supports Java Web components. JavaServer Pages (JSP) and Servlets are executed under a Java Virtual Machine (JVM) in the OSE server.

2. Connect to the OSE server and generate the Web domain information. This information must be stored in the Java configuration file, oraiisjp.cfg, and the file must be saved in the \ORACLE_BASE\ORACLE_HOME\iisplugin directory. Create the Java configuration file using the session shell tool (sess_sh), a Java Web management and publishing tool, which creates the configuration file in the format required by IIS.

The Java configuration file stores the virtual paths that map to a stateless or stateful mode and whether a specific file extension is required. Oracle Plug-in for Microsoft IIS supports stateful and stateless Java Web component access.

See Also: Oracle9i Oracle Servlet Engine User's Guide for complete information about publishing components, mapping virtual paths, and an overview of session shell tool commands. Oracle9i Java Tools Reference for a complete description of the session shell tool commands

Creating the Java Component Configuration File

1. From the command prompt, enter the following command to invoke the session shell:

   sess_sh -s transportURL/ -u user -p password
   

Where...	Specifies...
transportURL	Any of these supported URLs:
	jdbc:oracle:type:spec	The Java Database Connection (JDBC) URL that connects to the database using JDBC.
	http://hostname:port	The HTTP URL indicating the host and port used to connect to the administrative Web server preinstalled in the database.
	sess_iiop://hostname:port[:sid]	The SESS_IIOP URL indicating the host, port, and SID for the GIOP listener on the server.
user	The login name for the database session.
password	The password during login.

From the session shell prompt, enter the following information:

exportwebdomain -format iis -netservice TNS_connect_string \
webdomain &> \ORACLE_BASE\ORACLE_HOME\iisplugin\oraiisjp.cfg

Where...	Specifies...
TNS_connect_string	How to connect to the OSE server. This connect string information is stored in the configuration file.
webdomain	The Sun Java Naming and Directory Interface (JNDI) location of the Web domain to export. The JNDI namespace is an API storing the OSE server information and contents, and provides naming and directory functionality to applications written in the Java programming language.
\ORACLE_BASE\ORACLE_HOME\iisplugin\oraiisjp.cfg	The fully qualified name of the configuration file.

Note: Your Java component configuration file must be copied to the \iisplugin directory and be named oraiisjp.cfg.

Java Web components are now accessible.

To see how OSE server connection strings look, see Example 2-1. Note that the OSE server is differentiated by the presentation type.

See Also: Net8 Administrator's Guide for detailed information about connection strings. This manual is available from OTN. See "Related Documentation" for information on how to access OTN.

Example 2-1 Sample Database Connection String for the OSE Server

test.world=(Description=(Address=(Port=1521)(host=test-pc)(Protocol=tcp))

(Connect_Data=


(Service_name=test.us.oracle.com)
(Presentation=http://admin)
)
)

The oraiisjp.cfg file stores the TNS connect string information which specifies how Java Web components connect to the OSE server. In Example 2-2, AuroraService is the OSE server name and test.world is the HTTP connection name.

The oraiisjp.cfg file consists of three columns.

Column Heading	Description
Virtual Path	The location of the published Java Web components within the OSE server.
Type	The Java Web component state. Stateful and stateless Java component access and stateful Java-based applications are supported.
Extension	The Java Web component file extension to execute on the OSE server.

Example 2-2 Sample oraiisjp.cfg File

#
# IIS configuration 
# Domain: /admin_
# Virtual Path         Type               Extension
#

                  AuroraService           test.world
                  Maxworkers              100
#
# Context for VPATH /
#
/admin/shell            Stateful
/errors/internal        Stateless         snoop
/examples/counter       Stateful
/examples/snoop         Stateful

#
# End of configuration
#

Using the preceding example, Example 2-2, incoming requests use the test.world connection string to connect to the OSE server as follows:

• For all incoming requests containing the virtual path /errors/internal/, Oracle Plug-in for Microsoft IIS sends the request with the .snoop extension in stateless mode. Requests without the .snoop extension are returned to IIS for processing.

• For all incoming requests containing the virtual path /admin/shell, Oracle Plug-in for Microsoft IIS sends all requests in stateful mode regardless of extension.