Chapter 4: Building Internet Programs

This chapter explains how you build Internet programs; it includes information on how to compile and debug programs.

Server Express supports the following APIs 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.
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. NSAPI server-side programs start faster than standard CGI applications for two reasons:
- With NSAPI, 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 starting a new process.
- The server-side program is compiled as a self-contained callable shared object (.so file), which the server keeps loaded after the program has been run once. Subsequent restarts are much faster.

Because 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, see the chapter Compiling Programs, and for details on the REENTRANT directive, see the chapter Directives for Compiler, both in your Server Express User's Guide. For information on multi-threaded programming, see your Multi-threaded Programming book.

This chapter describes how to build the server-side program as a CGI program, as this is the simplest to run and animate. You can change your program to NSAPI when you have it working - this is documented in the chapter Building NSAPI Programs.

For information on how to run Internet programs, see the chapter Deploying and Running Your Application.

4.1 Building a Server-Side CGI Program

To build a server-side CGI program:

cob -C 'webserver(cgi)' flags programs

where flags can be:

-i	To create an .int file
-t	To create a multi-threaded program
-u	To create an .gnt file
-z	To create a callable shared object
-x	To create a system executable file

For example, to compile cgiprg.cbl to a system executable:

cob -C 'webserver(cgi)' -x cgiprg1.cbl

If you want to compile directly to a NSAPI application:

cob -C 'webserver(nsapi,userentrypoint)' -ty cgiprg1.cbl

where userentrypoint is the service name for the NSAPI application.

For information on using the cob command, see the COBOL System Interface (cob). For information on cob flags, see the chapter Descriptions of cob Flags. Both chapters are in your Server Express User's Guide.

4.1.1 Choosing a Run-time System

Applications created with this COBOL system default to using the non-threaded run-time system.

You must change the way your applications are built if you want to deploy the application as NSAPI programs. NSAPI programs must be multi-threaded.

Note: You can write CGI applications to use multi-threading. For example, you could create three threads to perform three unconnected database queries and display the results in the browser.

4.2 Debugging the Application

You can debug your web application in various ways. On X terminals, you can use:

Animator from the command line
Animator from the CBL_DEBUGBREAK routine
Just-in-time animation

In a non-X environment, you can use the command cobanimsrv (or cobanimsrv_t with multi-threaded applications).

To run and debug the application on your development system, your development system needs to be running a Web server. See the chapter Deploying and Running Your Application for details.

4.2.1 Using Animator from the Command Line

You can switch on Animator from the command line by setting the COBOL switch +A, and telling the X terminal server where to display the animator. This can be done by setting these environment variables in the user environment file .mfcgienv:

COBSW=+A
DISPLAY=$REMOTE_ADDR:0.0

In the above example, the DISPLAY variable enables Animator to be displayed on the X server that generated the execution of the CGI program. You can set the DISPLAY variable to any other value you require.

Note: If you use X windows you might need to enable the host machine via the X command xhost.

For details on setting switches, see the chapter Running in your Server Express User's Guide.

4.2.2 Starting Animator from CBL_DEBUGBREAK

If a program contains the CBL_DEBUGBREAK library routine Animator starts, on the user specified X window, when program execution reaches this routine. Set the DISPLAY variable in the .mfcgienv configuration file to specify the X window; for example:

DISPLAY=$REMOTE_ADDR:0.0

4.2.3 Just-in-time Debugging

You can start the Animator only when something goes wrong, for example a run-time system error 173; this is known as just-in-time debugging. To specify just-in-time debugging, you need to set the DISPLAY variable in the .mfcgienv configuration file to specify the X window; for example::

DISPLAY=$REMOTE_ADDR:0.0

You also need to set various run-time tunables. For details on just-in-time debugging, see the chapter Starting Animator in your Debugging Handbook.

4.2.4 Using cobanimsrv

If you are not using X windows, and need to debug the application using a dumb terminal, you can use the cobanimsrv command.

If you type:

cobanimsrv

or, for multi-threaded programs:

cobanimsrv_t

in your cgi-bin directory, Animator starts but waits to debug the program until any application in the current directory is executed, via the cobrun trigger, by the browser/server.