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.

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 > Help Topics, and from the Contents tab, select Reference > Compiler Directives.

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 > Help Topics, and on the Help Contents tab double-click Programming > CGI-based Applications > Debugging CGI-based Applications

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 programs 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.

Accessing Environment Variables from ISAPI Programs

To access Windows environment variables from an ISAPI program, include a call to the library routine PC_ISAPI_GET_EXT_BLOCK in your server-side program. This call returns the ISAPI extension block, and one of the fields in this is a pointer to the ISAPI routine getservervariable. You can then call the getservervariable routine. To use this technique, you must include the copy file provided in Net Express\base\source\isapiext.cpy in your program.

You should be aware that the naming conventions for the environment names in ISAPI programming is not the same as in CGI programming. To find out more about ISAPI environment variables, see the Microsoft ISAPI Extension documentation on the Microsoft Web site.

Here is an example program that calls PC_ISAPI_GET_EXT_BLOCK:

$set sourceformat(free) webserver(isapi) reentrant(1) case

 copy "isapiext.cpy"

 special-names.
     call-convention 74 is WINAPI.
 working-storage section.
 thread-local-storage section.
 01 ext-block usage extension-control-block.
 01 option-name pic x(255).
 01 option-value pic x(255).
 01 temp-1 pic 9(9) comp-5.

 procedure division.

     move length of extension-control-block to cbsize of ext-block
     call "PC_ISAPI_GET_EXT_BLOCK" using ext-block
     if return-code not = 0
         display "Not ISAPI environment"
         exit program
         stop run
     end-if

     move z"REQUEST_METHOD" to option-name *> string null terminated
     move length of option-name to temp-1
     move space to option-value(1:1)
     call WINAPI GetServerVariable using
                               by value     connid
                               by reference option-name
                                            option-value
                                            temp-1
*> temp-1 contains length of the value in option-value plus terminating
*> null byte
     subtract 1 from temp-1

     exit program
     .

For a description of the PC_ISAPI_GET_EXT_BLOCK routine see PC_ISAPI_GET_EXT_BLOCK.

Note: You should use the PC_ISAPI_GET_EXT_BLOCK routine only to obtain the getservervariable procedure pointer. Any other use might cause unpredictable results.

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 > Help Topics, and from the Contents tab, select Reference > Compiler Directives.

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)

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