PreviousBuilding Internet Programs Deploying and Running Your ApplicationNext

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:

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's 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's 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:

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:

You need to update the configuration files:

obj.conf
mime.types

Make these changes to obj.conf:

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


  2. 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:

For more information on debugging, see your Debugging Handbook.


Notes:



Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousBuilding Internet Programs Deploying and Running Your ApplicationNext