Chapter 9 Web Server Redirector Plug-In

Installing the plug-in on Microsoft IIS

The plug-in is available with EAServer versions 3.6.1 and later and runs on Windows NT 4.0 and Windows 2000. The plug-in uses the ISAPI (Internet Server API) framework, which defines a DLL method of binding custom server-side processes to an instance of an IIS. The plug-in is a DLL that the IIS loads when the server is started and that stays in memory until the server shuts down.

To install and configure the redirector plug-in on an IIS:

Set the WSPLUGIN_CONFIG_FILE environment variable.
Install the IIS plug-in.
Edit the redirector configuration file.
Copy libraries from EAServer to your Web server.

Setting the WSPLUGIN_CONFIG_FILE environment variable

The WSPLUGIN_CONFIG_FILE environment variable identifies the redirector configuration file that the Web server requires to run the plug-in. Using the System Properties dialog box, create the WSPLUGIN_CONFIG_FILE variable, then set it to the full path of the configuration file. You can name the file whatever you want. For example, if the configuration file is redirector.cfg and it is in the c:\winnt\system32\iis directory, set WSPLUGIN_CONFIG_FILE to c:\winnt\system32\iis\redirector.cfg . The configuration file must be on the server where the plug-in is installed.

When you edit an environment variable, you must reboot your machine for the changes to take effect.

Installing the IIS plug-in

Your EAServer installation includes a libjeas_iis.dll file that implements the IIS Web server plug-in. To install the plug-in:

On Windows NT, choose Start | Program Files | Windows NT 4.0 Option Pack | Microsoft Internet Information Server | Internet Service Manager.

On Windows 2000, run the Control Panel | Administrative Tools applet, and select Internet Service Manager.
Highlight the Web site where you want to install the plug-in, right-click, and select Properties.
On the ISAPI Filters tab, click Add, and install libjeas_iis.dll as an ISAPI filter. Filters are invoked in the listed order. Sybase recommends that you install libjeas_iis.dll first in the list. Click OK.
Highlight the Web site where you installed libjeas_iis.dll, right-click, and select New | Virtual Directory. Create a virtual directory that corresponds to the location specified in the Connector.IIS.Extension_URI directive in the redirector configuration file--see "Editing the redirector configuration file". The default name for the virtual directory is "sybase." Enable read, log access, and execute permissions on the virtual directory.
Copy libjeas_iis.dll from your EAServer /lib subdirectory to the virtual directory location that you specified in the previous step.

Editing the redirector configuration file

Create a redirector configuration file in the location identified by the WSPLUGIN_CONFIG_FILE environment variable, then edit the file and configure these directives:

Connector.IIS.Extension_URI - identifies the virtual directory path to the plug-in DLL on the IIS; if not set, the default is /sybase/libjeas_iis.dll. If the path is incorrect, requests fail with an HTTP server error. Use this syntax to specify the virtual directory path:
```
Connector.IIS.Extension_URI /virtual-directory/libjeas_iis.dll
```
If your virtual directory name is "sybase", you do not need this directive in your configuration file.
Connector.IIS.URLS - identifies one or more context paths that the redirector handles. If the URL of an incoming request matches any of the path prefixes, the redirector handles the request. If you set the value to "/*", the redirector handles all the requests sent to the Web server. If this directive does not exist in the configuration file, the redirector does not handle any requests. Use this syntax to specify the context path:
```
Connector.IIS.URLS /context-path [, /context-path, ...]
```
For example, to configure the redirector to handle client requests for http://host-name/examples1/servlet/TestApp and http://host-name/examples2/* , add this line to the redirector configuration file:
```
Connector.IIS.URLS /examples1, /examples2
```
Connector.IIS.LogFile - specifies the full path of the redirector log file. A separate log file is required because IIS-based logging is limited to 80 bytes per request, which is not sufficient for debugging. The default log file name is redirector.log, which is created in the IIS current working directory. To specify another file name, use this syntax:
```
Connector.IIS.LogFile drive:\directory-name\file-name
```
Connector.LogLevel - determines how much information is written to the Web server log file. For a description of the logging level options, see Table 9-3. To specify the logging level, use this syntax:
```
Connector.LogLevel logging-level
```
Connector.WebApp - maps Web server requests to EAServer listeners; for examples, see "Mapping Web server requests to EAServer listeners".

Sample configuration file

This sample redirector configuration file:

Connector.IIS.Extension_URI /iis/libjeas_iis.dll
Connector.IIS.URLS  /myWebApp, /SRP
Connector.WebApp /myWebApp = http://neptune:8080
Connector.WebApp /SRP = http://pluto:8080
Connector.IIS.LogFile C:\temp\redirector.log
Connector.LogLevel verbose

Specifies that the Web server redirector plug-in DLL is in the target Web site's virtual directory iis
Directs the plug-in to forward client requests for the URL http://<host:port>/myWebApp/* to http://neptune:8080/myWebApp/* , and to forward requests for http://<host:port>/SRP/* to http://pluto:8080/SRP/*
Directs the plug-in to write debug information to C:\temp\redirector.log using the verbose option

Copying libraries from EAServer to your Web server

Copy these DLLs from your EAServer /lib subdirectory to a location in your system PATH:

libjctssecct.dll
libjcc.dll
libjsybscl.dll
libjintl.dll

To debug your application:

Use the debuggable version of these libraries, which are located in the EAServer /devlib subdirectory.
Set the Connector.Loglevel directive to "verbose."
Restart the Web server.