Server-side Programming

Editing Form Designer Output

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 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 NetExpress 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 as 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, and change them to ISAPI or NSAPI programs when you are satisfied 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.

1. Write your server-side program as a CGI program. Don't forget to allow for resource contentions on things like data files - these affect all server-side programs.

   ISAPI programs run as part of the Web server service process. Because they are running inside a service, you shouldn't try to access the Windows NT shell. For example, you shouldn't try to create any windows or dialog boxes.

   Never use STOP RUN in an ISAPI or NSAPI program - because these programs run inside the web server process, a STOP RUN could hang the server. Always use EXIT PROGRAM or GOBACK to return control from an ISAPI or NSAPI program.

2. Build and debug your program as a CGI program.

3. When you are happy that your program does not have errors that could cause protection violations, rebuild it as an ISAPI or NSAPI program, as explained below.

4. Test the program on a Web server supports the API you have adopted.

5. Deploy the program.

The next three sections explain how you change COBOL compiler directives, and NetExpress built 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 NetExpress 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)

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, start the NetExpress help, and from the Contents tab, select Reference Bookshelf, Compiler Directives.

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 and NSAPI program as a .dll file (dynamic link library). This is covered in detail in the chapter Deploying Your Application, in the section Building a Shared Run-time System ISAPI or NSAPI 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 referred to:

/share-name/program.exe

Now they should refer to:

/share-name/program.dll

Server-side Programming

Editing Form Designer Output