Chapter 8: CGI, ISAPI and NSAPI Programs

This chapter explains the differences between the three APIs for server-side programs and how you can switch between them by simply changing compiler directives.

8.1 Overview

There are currently three APIs available for running server-side programs:

CGI (Common Gateway Interface)
This is the oldest API and is supported by all Web servers. It is also the easiest to use for debugging, so we recommend that you develop all your server-side programs using CGI.
ISAPI (Internet Server API)
This is a Microsoft API and provides speed improvements over CGI programs. It is supported by Microsoft Internet Servers and Web servers from some other vendors.
NSAPI (Netscape Server API)
This is a Netscape API and also provides speed improvements over CGI programs. It is supported by Netscape Web servers and Web servers from some other vendors.

ISAPI and NSAPI server-side programs start faster than standard CGI applications for two reasons:

With these APIs, a server-side program is started by the Web server as a separate thread. A standard CGI program is started as a separate process. A thread can be started faster than a new process.
The server-side program is compiled as a dynamic link library (.dll file), which the server keeps loaded after the program has been run once. Subsequent restarts are much faster.

Because ISAPI and NSAPI programs are run as separate threads, rather than separate processes, they must be multi-threaded. You can make any COBOL program multi-threaded by setting the REENTRANT(2) compiler directive. For more information on setting compiler directives, click Help Topics on the Net Express Help menu, and from the Contents tab, select Reference, Compiler Directives.

8.2 Writing ISAPI and NSAPI Server-Side Programs

You can write ISAPI and NSAPI applications in the same way that you write CGI applications, using ACCEPT/DISPLAY and EHTML for input and output. We recommend that you develop and debug your server-side programs as CGI programs, changing them to ISAPI or NSAPI programs when you are satisfied that they work correctly. Web servers running ISAPI are not very forgiving of bugs: if an ISAPI program crashes it can lock up the Web server software, forcing you to reboot. For further information about building and testing ISAPI applications, click Help Topics on the Net Express Help menu, and from the Contents tab, select Debugging and Animating Programs, Overview - debugging and animating programs.

The procedure we recommend you use to develop your server-side programs is as follows:

Write your server-side program as a CGI program. Don't forget to allow for resource contentions such as data files - these affect all server-side programs.
ISAPI programs run as part of the Web server service process. Because these programs are running inside a service, you should not try to access the Windows NT shell. For example, you should not try to create any windows or dialog boxes.

Note: Because ISAPI or NSAPI program run inside the web server process, you should always use EXIT PROGRAM or GOBACK to return control from these programs. The STOP RUN statements used in a CGI application may cause the server to hang if used in ISAPI or NSAPI programs.
Build and debug your program as a CGI program.
When you are sure that your program does not have errors that could cause protection violations, rebuild it as an ISAPI or NSAPI program, as explained below.
Test the program on a Web server that supports the API you have adopted.
Deploy the program.

The next three sections explain how you change COBOL compiler directives and Net Express build settings to rebuild a CGI program as an ISAPI or NSAPI program.

8.2.1 Setting Compiler Directives for ISAPI

Set the following compiler directives before rebuilding ISAPI programs:

WEBSERVER(ISAPI)
Tells the compiler that this program is an ISAPI application.
CASE
Prevents external symbols (including names of called programs) from being converted to upper case. If you don't do this, when an end-user attempts to run the ISAPI they see a "not found" message on their Web browser.

REENTRANT(2)
Ensures that it is safe to have multiple copies of this program running.

If your application uses Open ESQL, you must also include this directive:

SQL(THREAD=ISOLATE)
Prevents each thread's SQL resources and transactions from being shared with other threads.

Data access applications built with the Internet Application Wizard all use Open ESQL.

You can ensure these are set every time the program is compiled by including a $SET statement at the top of your program. For example:

$set webserver(isapi) case reentrant(2)

The dollar sign ($) must appear in column 7 of your source code unless you have set directive SOURCEFORMAT"FREE", in which case it can appear in any column. For more information on setting compiler directives, click Help Topics on the Net Express Help menu, and from the Contents tab, select Reference, Compiler Directives.

8.2.2 Setting Compiler Directives for NSAPI

Set the following compiler directives before rebuilding NSAPI programs:

WEBSERVER(NSAPI,entry-point-name)
Tells the compiler that this program is an NSAPI application. The value entry_point_name is a user-defined name. The compiler creates a hidden entry point with entry_point_name to enable the NSAPI web server to start your program.

When you deploy this application on an NSAPI server, use entry_point_name as the value for funcs attribute on the Init fn when you modify the server's obj.conf file. See the section Modifying the NSAPI Server Configuration Files in chapter Deploying Your Application.
CASE
Prevents external symbols (including names of called programs) from being converted to upper case. If you don't do this, when an end-user attempts to run the ISAPI they see a "not found" message on their Web browser.

REENTRANT(2)
Ensures that it is safe to have multiple copies of this program running.

If your application uses Open ESQL, you must also include this directive:

SQL(THREAD=ISOLATE)
Prevents each thread's SQL resources and transactions from being shared with other threads.

Data access applications built with the Internet Application Wizard all use Open ESQL.

You can ensure these are set every time the program is compiled by including a $SET statement at the top of your program. For example:

$set webserver(nsapi,run_update_1) case reentrant(2)

8.2.3 Linking ISAPI and NSAPI Programs

When you build a CGI program, you build it as an .exe file. You build an ISAPI or NSAPI program as a .dll file (dynamic link library). This is covered in detail in the section Building a Shared Run-time System ISAPI or NSAPI Application in the chapter Deploying Your Application.

Once you have rebuilt a CGI server-side program as an ISAPI or NSAPI .dll file, you must change all the URLs on Web pages or forms which refer to the program. When the program is a CGI, the URLs refer to:

/share-name/program.exe

Now, as an ISAPI or NSAPI, they should refer to:

/share-name/program.dll

Server-side Programming

Editing Form Designer Output