INFO: Troubleshooting Windows CGI Applications with IIS

• Microsoft Internet Information Server version 1.0

SUMMARY

NOTE: The following acronyms are used within this article:

- Internet Information Server (IIS) - Common Gateway Interface (CGI) - Internet Server Application Programming Interface (ISAPI) - Dynamic Link Library (DLL) - Software Development Kit (SDK) - World Wide Web (WWW)

Below is a description of three common server extension technologies.

ISAPI Extensions

ISAPI server extensions are implemented as DLL files. A small set of functions allow the DLL to communicate with the WWW server. The DLL actually becomes part of the WWW server. ISAPI extensions are by far the fastest. Because function pointers are used to communicate with the server, languages that cannot accommodate function pointers cannot be used (for example, Microsoft Visual Basic).

CGI Applications

CGI server extensions are implemented as console applications. Input and output are communicated with normal standard input, standard output, and environment variables. CGI EXEs run in their own process space, and one process is created per request. Some languages do not support standard input, standard output, and/or environment variables.

Windows CGI Applications

Windows CGI server extensions are implemented as Windows-based GUI applications. INI files (profiles) and temporary files are used to communicate input and output. For each request, an INI file is created, along with all necessary temporary files. Output is written to a pre- designated temporary file. While writing a Microsoft Visual Basic application conformant with Windows CGI is easy, the interface is dependent on files and is inherently slow.

IIS directly supports two types of server extensions: CGI executables and ISAPI DLLs. All other interfaces are supported through either CGI or ISAPI. Specifically, IIS supports Windows CGI executables (usually written with Microsoft Visual Basic) through the use of an ISAPI DLL.

Windows CGI support is available via the IS2WCGI sample provided in the Win32 SDK. Is2wcgi.dll, an ISAPI application, translates the ISAPI environment into the Windows CGI environment. This article provides tips on running existing Windows CGI applications with IS2WCGI.

NOTE: The Windows CGI specification is totally different than the CGI specification. Do not confuse the two.

MORE INFORMATION

Windows CGI applications are Windows-based executables, commonly written with Microsoft Visual Basic. The Windows CGI spec (authored by Robert B. Denny) first appeared in the O'Reilly Website product.

In order to translate ISAPI into Windows CGI, IS2WCGI does the following three things:

• It formats inbound browser data according to the Windows CGI spec.
• It runs the Windows CGI executable.
• It passes output to the browser via ISAPI.

TEST 1: Does Is2wcgi.dll work with Is2wcgi.exe on your computer?

The first step to determining the problem is to make sure the DLL is functional using the sample Windows CGI executable provided. Is2wcgi.dll and Is2wcgi.exe must be in the same directory, and they are copied to C:\Inetsrv\Scripts\Sdk by the Win32 SDK makefiles.

1. Make sure you are using the latest version of Is2wcgi.dll. Check www.microsoft.com/intdev for updates of the Win32 SDK.

2. To be safe, shut down all IIS services (FTP, WWW, and Gopher) with the administration tool, and then start them again. This will force all IIS service components to reload.

3. Test your installation of IIS by using a browser to view the default HTML page. Make sure this page is not cached by the browser (choose reload).

4. Verify that the DLL and EXE are located in the same directory. Use the IIS administration tool to verify that the directory is listed as a virtual root and has execute permission (and only execute permission). Read permission is inappropriate for server extensions. It is OK to use a child directory when the parent is marked as a virtual root with execute permission.

5. Enter your server's web address (the URL) manually with your browser, followed by a path to Is2wcgi.dll. For example, type:

         http://myserver/scripts/sdk/is2wcgi.dll
   

After you complete step 6, you should get a reply back from the server reflecting the profile created by the Is2wcgi dll. If this works, go to Test 6 below.

TEST 2: Upon receiving a reply, is the browser asking you to save

        something?

TEST 3: Is the IUSR_Guest and SYSTEM account set up properly?

IIS creates a guest account for anonymous web accesses during installation. Verify that an account similar to IUSR_YourMachineName has read, write, create, delete, and execute permission in the directory containing Is2wcgi.dll. Remember that the DLL creates temporary files, runs the Windows CGI application, and deletes the files after it is done. Also, remember that the IUSR account is part of the Guest group and inherits guest restrictions. Is2wcgi.dlls HttpExtensionProc function will run in the IUSR_Guest account, and the Windows CGI application will run in the local system account. Any permissions granted to IUSR_Guest should also be granted to the local system account.

If you discovered that IUSR_Guest or the local system account did not have appropriate access, modify access, restart the WWW service, and go back to Test 1.

TEST 4: Are all necessary DLLs available on your NT server? Do they have

        appropriate permissions?

1. Use a tool such as Dumpbin.exe to list the imports of Is2wcgi.dll. DUMPBIN comes with Microsoft Visual C++. Type the following from the command prompt:

         DUMPBIN IS2WCGI.DLL /imports
   

2. Use the output of DUMPBIN to determine which DLLs are required. Kernel32.dll and User32.dll are part of Microsoft Windows NT. Another DLL such as Msvcrt40.dll may be listed and is not part of Windows NT.

3. Verify that all required DLLs are installed in the System32 subdirectory of your Windows NT installation. C runtime DLLs come with the compiler.

4. Your Windows CGI executable may also be dependent on runtime DLLs. A Visual Basic application is dependent on VB runtimes (Vbrun300.dll for example). Verify that all required DLLs are installed in the System32 subdirectory (or elsewhere in your system path).

5. Verify that both the SYSTEM account and the IUSR_Guest account have access to all necessary DLLs. For anonymous accesses, the DLL will run in the context of IUSR_Guest, and the Windows CGI EXE will run in the SYSTEM account. (The IUSR_Guest account on your machine will be named IUSR_Yourmachinename.)

TEST 5: Was the DLL ever loaded?

At this point, something was missed. Verify that IIS loaded the DLL by copying over it or deleting it. When IIS is running and has Is2wcgi.dll loaded, you will not be able to copy over it or delete it.

If Is2wcgi.dll was not ever loaded, start over and conduct careful troubleshooting. If it is loaded, see other techniques below for more ideas on how to troubleshoot.

TEST 6: Try Is2wcgi.dll with your form.

Use Is2wcgi.exe as a diagnostic tool for your form. Modify the ACTION attribute in your HTML form so Is2wcgi.dll is executed. For example, the FORM tag should look similar to the following:

   <FORM ACTION="http:/Scripts/SDK/IS2WCGI.DLL" METHOD=POST>

TEST 7: Try your own Windows CGI app.

With Is2wcgi.exe working, you are ready to try your own Windows CGI application. If your sample name is Sample.exe, copy the working copy of Is2wcgi.dll to Sample.dll. The base names must always match.

Assuming your application is named SAMPLE.EXE, make sure your form ACTION is running SAMPLE.DLL.

Load the form in your browser, then choose submit. If this does not work, carefully go through each test again.

OTHER TECHNIQUES:

Windows CGI support is not built into the IIS WWW service, because Is2wcgi.dll comes as a sample in the Win32 SDK. Because of this, you have full source code to the translator and can modify it and improve it to suit your needs. When troubleshooting, you might add MessageBox calls before all return points and determine what HSE_ constant IS2WCGI.DLL is returning. Remember to specify MB_SERVICE_NOTIFICATION because ISAPI DLLs are running as a desktop-less service.

You might also make use of OutputDebugString and use Dbmon.exe to view the debug messages. DBMON will not work unless the account that the ISAPI DLL runs in has certain rights. You may also add IUSR_Guest to the administrators group temporarily for debugging. Finally, you might run IIS as a console application and step through IS2WCGI code line-by-line. See the ActiveX Readme.txt for information about running IIS as a console application.

Finally, there is a constant defined in Is2wcgi.cpp that may help. Including the constant definition disables HTTP header processing by the translator, and is necessary when your Windows CGI application does not return header information. See the source code comments for details.

For additional information, please see the following sources: