Building Internet Programs

Deploying and Running Your Application

Chapter 5: Building NSAPI Programs

This chapter explains how to build NSAPI programs and how you can change a CGI program to a NSAPI program by changing Compiler directives. It is assumed that you have built your Internet application as a CGI program, as suggested in the chapter Building Internet Programs

5.1 Writing NSAPI Server-Side Programs

You can write 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 NSAPI programs when you are satisfied they work correctly.

Note: The CGI environment variables are not recognised by NSAPI. If your program relies on the use of CGI environment variables, you need to change your NSAPI program.

When you are happy that your program does not have errors that could cause protection violations, rebuild it as a NSAPI program, as explained below. You are advised to test the program on a Web server that supports NSAPI before finally deploying it.

The next two sections explain how you change COBOL Compiler directives, and build settings, to rebuild a CGI program as a NSAPI program.

5.1.1 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 a 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 a 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.
REENTRANT"2"
Ensures that it is safe to have multiple copies of this program running.

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

$set webserver"nsapi,entry-point-name" 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, see the chapter Compiling Programs in your Server Express User Guide

5.1.2 Building NSAPI Programs

You build a NSAPI program as a callable shared object. To convert the file to a NSAPI callable shared object, use the cob command; for example:

cob -vtyU -C 'webserver"nsapi,myentrypoint"' fred.cbl -o fred.so

The -y flag specifies that the program is to linked as a self contained callable shared object; the -t flag specifies that this program is to be multi-threaded; the -U flag specifies that all references are resolved at run-time.

For more information about building applications see your Server Express User Guide.

Once you have rebuilt a CGI server-side program as an NSAPI callable shared object, you must change all the URLs on Web pages or forms which refer to the program. The URLs in a CGI program refer to:

/share-name/program

In a NSAPI program they should refer to:

/entry-point-name.ext

where the parameters are:

`entry-point-name`	The entry-point name of the program
`ext`	A MIME type defined in the configuration files obj.conf and mime.types. For more information see the section Before Running NSAPI Applications below.

5.2 Before Running NSAPI Applications

Before you run a NSAPI server-side program (whether on your development system to test and debug the application, or on a production system) you must:

Create a script to set PATH, COBPATH, COBDIR and LIBPATH (on AIX) or LD_LIBRARY_PATH (on other SVR4-based systems) to the required directories. You must specify the directory that contains your NSAPI program on LIBPATH or or LD_LIBRARY_PATH. If you are debugging you program using the CBL_DEBUGBREAK routine, you also need to set COBIDY=location-of-idy-files.
Set the execute permissions for this script to ugo+x.
Modify the NSAPI server configuration files.
Change the Action property on your form.

When you have carried out these steps (and deployed the files to the production Web server machine, if necessary) you have to shut the server down and restart it to load the NSAPI program.

Modifying the NSAPI Server Configuration Files

The modifications in this section are for Netscape's Enterprise server; if you are using a different server consult the documentation supplied with it.

The modifications set up:

The physical executable file and entry point are defined as modules to be loaded as part of the server initialization
The entry point for the NSAPI program is defined as a service, and associated with a new MIME type
The new MIME type is associated with a particular extension

You need to update the configuration files:

obj.conf
mime.types

Make these changes to obj.conf:

Add the following line to load your server-side program when the server is started:

Init fn="load-modules" shlib="executable_file.so" funcs="entry-point-name"

where the parameters are:

`executable_file`	The physical path and name of the server-side program. Note: Use forward-slashes "/", not back-slashes "\" in the path, even if your application might be deployed on Windows platforms.
`entry-point-name`	The entry-point name you specified when compiling the program, in the directive WEBSERVER"NSAPI,entry-point-name". See the section Setting Compiler Directives for NSAPI.

Between the <OBJECT name="default"> and </OBJECT> tags, add the following line to associate the entry-point for your program with a new MIME type:
```
Service fn="entry-point-name" method="(GET|POST)" type="magnus-internal/new-type"
```
where the parameters are:

new-type A name for a new MIME type to be associated with the program.

entry-point-name The entry-point name you specified above.

To associate the new MIME type you defined above with an extension add the following line to mime.types:

type=magnus-internal/new-type exts=extension

where the parameters are:

`new-type`	The MIME type name you associated with the program above.
`extension`	A file extension for your program. Note that you are not limited to three character extensions.

Changing the Action Property

Your NSAPI program is started whenever the Browser requests the new MIME type you defined in the previous section. You need to change the Action property on any forms which call this program to request the new MIME type. Open the form in an editor, and change the Action property to read:

program.extension

where program is the entry-point for your program, and extension is the extension for the new MIME type defined in the previous section.

Save the form, and deploy the new version of the .htm file.

You also need to create a dummy file with the name program.extension in the documents directory (that is, the directory mapped to form-share) on the web server. The dummy file is used by Enterprise Server when loading your NSAPI program. For details on the form-share directory, see the section Setting up the Web Server in the chapter Deploying and Running Your Application.

5.3 Debugging NSAPI Programs

To debug a NSAPI program using Animator, you need to run the program on a Web server. Before starting the Web server:

Add the following to your environment:
```
DISPLAY=xserverforanim:0.0
```
before you start the Web server.
Add the following statement to the start of each of your NSAPI programs:
```
call "CBL_DEBUGBREAK"
```
When executed, this statement starts the Animator.
Rebuild your application

For more information on debugging, see your Debugging Handbook.

Notes:

If a NSAPI program executes a STOP RUN statement the Web server also stops. Always use EXIT PROGRAM statements instead of STOP RUN statements in a NSAPI program.
If you are debugging a NSAPI program you must ensure that you stop debugging your program using the Animator Detach function, otherwise the Web server stops when you exit Animator.

Building Internet Programs

Deploying and Running Your Application

`new-type`	A name for a new MIME type to be associated with the program.
`entry-point-name`	The entry-point name you specified above.