This chapter describes how to deploy and run your application. You will need to read the information in this chapter if you are:
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.
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:
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:
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:
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:
"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.
To deploy your Internet application to a production Web server, you need to copy the files that make up your application:
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.
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:.
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 $*
/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.
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.
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.
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:
|
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. |
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.
If you use the cobrun or cobrun_t triggers to run your CGI programs you might see the following error messages:
This error message is displayed if:
This error message is displayed if the action tag in the form does not have program name given. Correct the action tag.
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).
Ask the administrator of the access control file (usercgi.cfg) to check the entry for your userid
Run mfcgicfg check
" to see if the usercgi.cfg is setup correctly.
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.