Chapter 20: 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:

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

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.

Supported Servers

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

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:

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

  2. Start the administration tool for your Web server (consult the Web server documentation if you don't know how to do this).

  3. 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 the section Changing Application URLs.

    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:


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:

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

  1. Locate each IS EXTERNAL FORM IDENTIFIED BY clause in your COBOL source code.

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

Deploying Internet Applications

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

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

After you have copied the files, follow these steps:.

  1. Create a script to set COBDIR and either LIBPATH, SHLIB_PATH or LD_LIBRARY_PATH (depending on your UNIX environment), and to start the application. (For details on using these environment variables see the appendix Environment Variables in your User's Guide.) 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 $*  
  2. 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

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.


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

Running Internet Applications

You run Internet applications just like any other COBOL application. For information on running applications, see the chapter Running in your 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.


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:

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.

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.

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.


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 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 their 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:


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