ISAPI Perl Primer

by Gunther Birznieks

ISAPI Perl is a version of Perl for ISAPI-compliant Microsoft Windows-based Web servers. Essentially, ISAPI Perl builds on CGI/Perl. In the early days of Web servers, Common Gateway Interface (CGI) allowed Perl programs to interact with a user's browser through the Web server.

ISAPI Perl is a version of Perl for ISAPI-compliant Microsoft Windows-based Web servers. Essentially, ISAPI Perl builds on CGI/Perl. In the early days of Web servers, Common Gateway Interface (CGI) allowed Perl programs to interact with a user's browser through the Web server.

However, CGI/Perl applications have one primary disadvantage: speed. Every time a CGI/Perl-based application is launched by the Web server, a new process is started, and the Perl script must be compiled by the Perl interpreter.

ISAPI is a Microsoft-created API that stands for Internet Server API. In concept, ISAPI is similar to Apache's Web Server API and Netscape Web Server's NSAPI or WAI interface.

Essentially, these APIs allow programmers to write hooks into the various stages of Web server processing. These hooks are typically program modules that do things like authenticate a user, but they can also be programmed to be a full-blown application. In the case of ISAPI Perl, Perl itself is embedded into the Web server using the ISAPI interface.

The difference between ISAPI and CGI is that ISAPI programs remain loaded in the Web server memory after an ISAPI program has first been loaded in memory. Thus, ISAPI programs tend to be much faster than CGI programs that are started and cleaned up for each and every Web application request from the user's Web browser.

There is only one version of ISAPI Perl: ActiveState Perl. When Perl is download from ActiveState, it comes with a normal, command-line version of Perl, ISAPI Perl, and PerlScript for scripting inside of Active Server Pages.

ISAPI Perl used to be a bear to install on Microsoft's Internet Information Server (IIS) because associating ISAPI Perl with an application required registry settings. Thanks to the ingenuity of the ActiveState guys, the more recent versions of ActiveState Perl come with an installer that detect IIS and make this association for you.

Active Server Pages

An alternative to using ISAPI Perl on some Win32 Web servers involves using Active Server Pages, a technology introduced with Microsofts IIS servers. Active Server Page technology enables HTML pages to have embedded Perl. Other than the syntax of embedding Perl inside HTML, PerlScript offers the same basic advantages as ISAPI Perl since the PerlScript module runs inside the Web server just like ISAPI Perl does.

However, should you wish to understand what it takes to do this, instructions are included with the ActivePerl Documentation. Specifically, the IIS 4.0 Installation Section of the Web Server Config FAQ.

One thing to note is that although the process of including ISAPI Perl on IIS is straightforward with Windows NT, it is a bit trickier to get it to work on Windows 98. This is partially because even though Personal Web Server for Windows 98 is basically a clone of IIS, it is not entirely identical to IIS.

If you are using Windows 98, you can increase your chances of success with installing ISAPI Perl by shutting down Personal Web Server before you install Perl. After you are done installing Perl, you should reboot your machine completely before attempting to use ISAPI Perl.

Setting up CGI/Perl scripts to run on a Win32 Web server is not as straightforward as on a Unix server. On a Win32 Web server there are two main issues to watch out for.

First, not all Win32 Web Servers allow CGI/Perl scripts to execute based on the interpreter listed on first line of the script.

Second, not all Win32 Web servers preserve the current working directory from which the script is executing. Since ISAPI Perl shares both of these negative Win32 server traits, the subsequent section summarizes how to get Perl scripts working with ISAPI Perl.

Unix has always enjoyed the capability of inherently running shell scripts based on the location of the interpreter in the first magic line of the file prefixed with #! (eg #!/usr/local/bin/perl). Unfortunately, Windows NT and other Win32-based systems do not enjoy that standard. Each Win32-based Web server seems to have its own method of figuring out how and when to execute CGI/Perl scripts.

Another issue with running CGI/Perl scripts under Win32 Web servers is that not all servers preserve the current working directory of the script. This is a problem because it is much easier to maintain CGI/Perl scripts of the paths relative to the main program. Relative paths enable the user to move the whole CGI application from different subdirectories and still have it work.

Since ISAPI Perl honors neither of these conventions, workarounds must be provided. The workaround for the first line of the Perl script convention is that ISAPI Perl is associated with a file extension when ActiveState Perl was first installed. Thus, to run a CGI script under ISAPI Perl, the script should match the ISAPI Perl file extension specified when the ActiveState Perl installation program was run.

IIS and ISAPI Perl also have a problem recognizing the current working directory of a script. There are two ways around this problem: Give a hint to the Web server to let it know the current working directory of the script, or tell the script itself what the absolute path is to all the programs.

The easiest way to solve the problem is to provide a simple "hint" to the Web server about the current working directory in which the script should run. It turns out that IIS is not entirely clueless with regard to the path: It just needs a push in the right direction.

Setting up a Virtual Root on the IIS Server provides this "push." In the IIS management console, Virtual Roots essentially map a URL directory name to a physical directory on your machine. One of the default virtual roots is /cgi-bin -- which may point to a directory such as:


The tricky thing is that any scripts under that /cgi-bin virtual root are forced by IIS to use c:\inetpub\wwwroot\cgi-bin as the current working directory regardless of whether the script itself lies in a subdirectory.

To get around this problem, create a virtual root that points to the actual directory that the script lies in. For example, to create a virtual root to a calendar script, you might consider calling the virtual root /calendar-bin, and have it point directly to


If you have many scripts, however, adding virtual roots all the time can be a pain. To make it less odious, you might consider either modifying all the paths in the script to use absolute directory references or add a chdir() command to the top of the script.

The chdir() command is usually an easier solution, as it allows the script to maintain references to all data files and libraries using relative path references. The chdir command for the example above would be:


Remember, if you choose to use the MS-DOS convention of separating path names using the backslash, then you must escape the backslash when using Perl. The above chdir command using backslashes would look like the following:

One last thing: It is unfortunate, but ISAPI Perl installs by default in a manner that is not as secure as it could be. Specifically, a feature of Perl known as taint mode places Perl on a constant and vigilant alert to hacking attempts. More information on taintmode can also be found at the Taint Mode FAQ.

ISAPI Perl installs without this feature enabled. If you wish to enable this feature, you must go into the Web Server Config section of the ActiveState Perl documentation discussed earlier and place a "-T" in between the "perl.exe" and "%s %s" command-line parameters.

The "-T" flag tells Perl to run in taint mode. We should note, however, that many Perl scripts are, unfortunately, not written with taint mode in mind, so adding this flag may break existing scripts! Be sure to test thoroughly if you do choose to set this flag.

ISAPI Perl is a useful Win32 performance enhancement compared to plain CGI/Perl. To summarize, the following major points were covered in this tutorial:

  • ISAPI Perl vs. CGI/Perl
    • CGI was the first protocol
    • ISAPI gave a performance boost
  • Configuring a Web Server for ISAPI Perl
    • Fairly straightforward, just use the installer
    • Win98 ISAPI installation may require tweaking
    • Consider enabling taint mode
  • Using CGI Scripts under ISAPI Perl
    • Getting ISAPI Perl to be associated with a Perl script
    • Get IIS to recognize the current working directory using the chdir() command or setting up an IIS virtual root

This article was originally published on Wednesday Aug 16th 2000
Mobile Site | Full Site