Building NSAPI Programs

State Maintenance Library Routines

Chapter 6: Deploying and Running Your Application

This chapter describes how to deploy and run your application. You will need to read the information in this chapter if you are:

Running an application on your development machine
You are deploying your application to a production machine

6.1 Overview

Deploying your application means putting it on a Web server so that it can be used either through the Internet or an intranet. This Web server might be your local UNIX system, while you to develop and debug your application to check that the application is performing as you expect, or a different UNIX system for users of your application.

To deploy your application onto a production Web server, you need to check:

Server Web share paths and application URLs
Which form files to ship
Build settings for your application

Before deploying your application on a Web server, you must read the licensing conditions for distributing applications. Licensing conditions are in a plain text file license.txt.

6.2 Supported Servers

You can build applications with NetExpress that conform to the CGI or NSAPI interfaces for Web programs. You should be able to run NetExpress applications on any Web server that fully conforms to one of these interfaces. At the time of publication, we have tested CGI programs created using Server Express on the following servers:

Apache
IBM Lotus Domino
Netscape Enterprise Server v3.5.1 (AIX/Solaris)

We have tested NSAPI programs created using Server Express on the following servers:

Netscape Enterprise Server v3.6.0 (Solaris).

Note: We do not support the creation of NSAPI programs for use on Netscape Enterprise Server v3.5.1 for AIX, due to operating system restrictions.

6.3 Setting up the Web Server

This section is about setting up the Web server to run Internet applications. The exact method for doing this differs from server to server, so you need to consult your server documentation for exact instructions on how to do this.

To set up your Web Server:

Install Application Server on the target machine. This sets up a run-time system for any Server Express applications you want to run on the machine.
Start the administration tool for your Web server (consult the Web server documentation if you don't know how to do this).

If you are deploying to a production system, set up the Web shares listed in the table below. A Web share is a mapping of a URL to an actual directory or folder on the Web server.

If you the Web shares are different on the target machine to those on your development machine, you will have to edit the files in your application as explained in Changing Application URLs. If you are deploying an NSAPI application, you will have to do this anyway, as the names of the executable files are slightly different.

Web share	Permissions	Description
*bin-share*	Execute	Put the executables for your application in this share.
*form-share*	Read-only	Put the forms and HTML pages (.htm files) for your application in this share.
*image-share*	Read-only	If your application has lots of images, you can put them in a separate share to make application maintenance easier.

Notes:

Not all servers work by setting different types of permission. For example, Netscape FastTrack uses the concept of CGI shares and Document shares. When you administer the FastTrack server, you set up CGI shares for your executables, and use Document shares for the other files. When FastTrack is installed, it sets up some default Web shares for documents and CGIs which you can use to deploy your application.
Some Web servers (for example, Netscape) are case-sensitive when they resolve Web share names, so /cgi-bin/ and /CGI-BIN/ are treated as different.

6.4 Changing Application URLs

When you are developing an application on your development system, the cgi-bin directory and the directories for HTML pages might have different names to the equivalent directories on your target system. If you need to change the directories that your application points to, you need to change:

On all input forms, the reference to the directory that contains the CGI or NSAPI application
On all forms, pathnames to any images
In any COBOL source files which output HTML pages using the DISPLAY verb, the pathnames to the page

To change the paths for HTML forms output by the DISPLAY verb:

Locate each IS EXTERNAL FORM IDENTIFIED BY clause in your COBOL source code.
Amend the filename to read:
```
"fullpath/htmlfile.htm"
```
where fullpath is the full physical path to the location on the Web server where the .htm file is to be installed, not the Web share name.

Rebuild your application, if necessary, after making these changes.

6.5 Deploying Internet Applications

To deploy your Internet application to a production Web server, you need to copy the files that make up your application:

Copy .htm files for input forms to the folder mapped to Web share form-share
If a form is always output by EHTML from one of your server-side programs, you don't need to copy it across to the Web server as it is embedded in the executable code for the program. All Form Designer generated code uses EHTML to output forms.
Copy image files, if your application has them, to the folder mapped to web share image-share
Copy the executable files for your application to the folder mapped to web share bin-share

The Web shares are the ones you set up in section Setting up the Web Server.

The way in which you deploy and run Internet programs on a production Web server running under UNIX differs between CGI applications and NSAPI applications.

CGI applications:

Create a script to set COBDIR and LIBPATH (on AIX) or LD_LIBRARY_PATH (on other SVR4-based systems), and to start the application. Set the execute permissions for this script to ugo+x.

For example, the script shown below is a typical script that needs to be executed. It sets up the COBOL environment and runs a program called cgiapp.

# Set COBDIR and COBPATH to locate the COBOL product 
# to run the program 

# Set the location of the COBOL system 
COBDIR=/usr/test/cobol 

# Set the COBOL program search path 
COBPATH=:/usr/test/cobol/progs 

# Set the PATH
PATH=$COBDIR/bin:$PATH

# Set the library path - on SVR4 systems it should be: LD_LIBRARY_PATH
LIBPATH=$COBDIR/lib:$LIBPATH

# Place these variables in your environment 
export COBPATH COBDIR PATH LIBPATH

# Run cgiapp becomes 
cobrun cgiapp $*

Start the server. The commands required to start a Web server differ depending on the type of Web server. The following example is for Enterprise Server V3.5.1:
```
/usr/netscape/suitespot/https-machinename/start
```

NSAPI applications:

Create a script to set COBDIR, COBPATH, PATH and LIBPATH (on AIX) or LD_LIBRARY_PATH (on other SVR4-based systems). Set the execute permissions for this script to ugo+x.

For example, the script shown below is typical of the script that needs to be executed.

# Set COBDIR and COBPATH to locate the COBOL product 
# to run the program 

# Set the location of the COBOL system 
COBDIR=/usr/test/cobol 

# Set the COBOL program search path 
COBPATH=:/usr/test/cobol/progs 

# Set the PATH
PATH=$COBDIR/bin:$PATH

# Set the library path - on SVR4 systems it should be: LD_LIBRARY_PATH
# You should also set the location of the NSAPI program on this path
LD_LIBRARY_PATH=$COBDIR/lib:$LIBPATH:nsapi-program-location

# If your program uses the CBL_DEBUGBREAK routine, you 
# need to set COBIDY=location-of-idy-files

COBIDY=/usr/test/cobol/progs

# Place these variables in your environment 
export COBPATH COBDIR PATH LD_LIBRARY_PATH COBIDY

Start the server. The commands required to start a Web server differ depending on the type of Web server. The following example is for Enterprise Server V3.6.0:
```
/usr/netscape/suitespot/https-machinename/start
```

For NSAPI applications, it might be useful to note the process ID in case the server crashes. You can do this with the UNIX commands:

echo "Debug Process : "`ps -fu nobody | tail -1 | awk '{ print $2 }'`

For Enterprise Server, you can also view the server process ID in the file:

/usr/netscape/suitespot/https-machinename/logs/pid.

If you ever need to stop the server (for example, if you have recompiled your application), you can stop the server (again, for Enterprise Server V3.5.1) using:

/usr/netscape/suitespot/https-machinename/stop

You can also kill or stop the Web server manually; for example, for Enterprise Server, you could use the UNIX command: using

kill 'cat/usr/netscape/suitespot/https-machinename/logs/pid'

Note: Killing the process manually might result in lost data. If possible, use the close down procedure required by your Web server.

6.6 Adding sstate to a Deployed Application

The server-side support mechanism described in the chapter Server-Side Programming uses a module called sstate, which is not part of the COBOL run-time system (the sources are provided for you to make changes if needed). Consequently, whenever you deploy an application which uses sstate you need to deliver it with your CGI or NSAPI executables.

You should compile the sstate module to a callable shared object (sstate.so) and copy it to the same directory on the target machine that will contain your CGI or NSAPI program. For NSAPI programs, sstate.so needs to be in a directory specified by LIBPATH (on AIX) or LD_LIBRARY_PATH (on other SVR4-based systems).

If your deployed NSAPI application uses the sstate module, you might at some point want to replace the module with one that you have recompiled. To do this, you need to stop your your Web server and restart it; this releases the current version of sstate from memory. You stop and start the Web server as described in the section Deploying the Application.

6.7 Running Internet Applications

You run Internet applications just like any other COBOL application. For information on running applications, see the chapter Running in your Server Express User's Guide. For information on deploying an Internet application to a production Web Server, see the previous section.

You should run your application from a script that sets up the environment for the Internet application, and then runs the application. An example script was given in the previous section.

To run your application, your form needs to know the name of the script on the production machine:

<FORM ACTION="/cgi-bin/script-name">
...
</FORM>

However, during application development you can use the cobrun triggers to start CGI programs. These triggers are described in the next section.

Note: You can use the cobrun triggers on your production machine; but you then cannot run a CGI application that has been created as a system executable.

6.7.1 The cobrun Triggers

Normally, you need root or administrator access to develop and run an application. You would also need to create a shell script to set-up the environment. However, Server Express provides various triggers and configuration files that make the development of CGI applications simpler. The configuration files for these triggers can also be used to define who has development access to the application.

You can use the cobrun or cobrun_t triggers to start a Web application, instead of a shell script; for example:

<FORM ACTION="/cgi-bin/trigger/myuserid/program">
...
</FORM>

where the parameters are:

`trigger`	cobrun or cobrun_t
`myuserid`	Your user ID
`program`	A Server Express executable file, such as an .int file or callable shared object

The triggers should be copied to the cgi-bin directory of the web server by your system administrator. A script to do this has been provided. To execute this script, type:

sh $COBDIR/bin/cgibin/cobrun.inst

This script also places a configuration file called usercgi.cfg in the cgi-bin directory of the web server. This file defines:

Which users can run the triggers
The location of their cgi-bin directories
Access privileges

usercgi.cfg is a text file that can be edited by using a text editor, or by using the program mfcgicfg.

Each line of the file has the format:

user:user_cgi_directory:access=options

where the parameters are:

user The user-id

user_cgi_directory The cgi-bin directory associated with that user name

options

Access option. This can be one of:

`full`	Anybody can access this user's cgi-bin directory
`denied`	Nobody can access this user's cgi-bin directory
`restricted`	Restrict access to those users specified in the file .mfcgiperms. This file should reside in the user's home directory.

6.7.1.1 Editing the Configuration File Using mfcgicfg

You can check, view and edit the usercgi.cfg configuration file using the utility $COBDIR/cgi-bin/mfcgicfg. This utility has the format:

mfcgicfg [option]

where the parameter is:

option One of the options described below.

The option parameter can have one of the following values:

`check`	Check for bad options, invalid directories and missing environment files
`list`	Read and display contents to the screen
`delete name`	Delete a user. For example: `mfcgicfg delete userid` where `userid` is your user ID.
`add name directory options`	Add a user. For example: `mfcgicfg userid www/cgi-bin access=full` where `userid` is your user ID.

6.7.1.2 Creating a User-defined Environment

You can create a user-defined environment in the configuration file .mfcgienv. This file can be located in your current environment, or in your cgi-bin directory. The environment defined here is added to your current environment before the Web application is executed.

Note: A quick way to create and edit this file is to type the command:

env >.mfcgienv

and then delete any environment variables you do not need.

6.7.1.3 Troubleshooting Trigger Problems

If you use the cobrun or cobrun_t triggers to run your CGI programs you might see the following error messages:

cobrun: Permission denied
	This error message is displayed if: No usercgi.cfg exists in the same directory as the installed cobrun triggers. Create a usercgi.cfg file. The user attempting to access the CGI program is not allowed access; that is, the user option in usercgi.cfg is set to "access=denied". Set the correct user option. The user attempting to access the CGI has root permissions, which is not allowed
no file name given
	This error message is displayed if the action tag in the form does not have program name given. Correct the action tag.
user defined in config file but does not exist on machine
.	Check the action tag in the form and see if the user name is valid; for example, `/cgi-bin/cobrun/valid-user-name/program` If this is valid then your administrator needs to add a entry to access control file (usercgi.cfg).
user defined in config file but does not exist on machine
	Ask the administrator of the access control file (usercgi.cfg) to check the entry for your userid
cannot access cgi-bin directory
	Run `mfcgicfg check`" to see if the usercgi.cfg is setup correctly.
unable to change supplementary group access list unable to change group id unable to change user id
	Check that the triggers have thier setuid permissions correctly set and that the file is owned by root.
	It is only required that the correct permissions are set to execute the cobrun[_t] triggers.

When you set up the access permissions for your cgi-bin directory on the web server, you should ensure that:

The cobrun and cobrun_t triggers exist in this directory
This directory does not have read or upload access, as this would enable a hacker to access the contents of access control file (usercgi.cfg) for the CGI triggers

Building NSAPI Programs

State Maintenance Library Routines