HP Eloquence A.06.31 Release Notes

Web Integration using CGI

This document describes the installation, configuration and usage of the eloqcgi ("Common Gateway Interface") web integration utility.

Included is the eloqcgi web integration utility along with two sample applications and an example database. The eloqcgi web integration utility is intended to be used on the HP-UX and Linux platforms along with a web server (the configuration examples provided here refer to the Apache web server).

Please note that eloqcgi is currently not available on the Windows platform.

Contents of this document:

Installed files

The following eloqcgi Files are installed with HP Eloquence A.06.31 on the HP-UX and Linux platforms: 
 /opt/eloquence6/lbin/eloq.cgi
 
 /opt/eloquence6/share/example/eloqcgi/htdocs/eloq.cgi
 /opt/eloquence6/share/example/eloqcgi/htdocs/sample1.html
 /opt/eloquence6/share/example/eloqcgi/htdocs/sample2.html
 /opt/eloquence6/share/example/eloqcgi/htdocs/elogo100.gif

 /opt/eloquence6/share/example/eloqcgi/prog/HELLO.PROG
 /opt/eloquence6/share/example/eloqcgi/prog/Sample2.PROG
 /opt/eloquence6/share/example/eloqcgi/prog/Sample2b.PROG
In the /opt/eloquence6/share/example/eloqcgi/htdocs directory, the eloq.cgi is actually a symbolic link to /opt/eloquence6/lbin/eloq.cgi.

Additionally, the example database is installed in the opt/eloquence6/share/example/sampledb directory: 

 /opt/eloquence6/share/example/sampledb/sample.exp
 /opt/eloquence6/share/example/sampledb/sample.schema
 /opt/eloquence6/share/example/sampledb/mkdb.sh
 /opt/eloquence6/share/example/sampledb/README.sampledb

To create the example database into a running eloqdb6 database environment you can use the mkdb.sh script provided in this directory. For details, please refer to the README.sampledb documentation.

Web Server Configuration

Please note that the purpose of the decription here is just to get the example up and running quickly. For you own projects please refer to the configuration example in the chapter Writing CGI Programs with HP Eloquence below.

For convenience, an alias URL should be configured which should point to the directory containing the eloqcgi utility. In this directory, your web server should be enabled to execute the eloq.cgi binary.

As a configuration example for the Apache web server, this is accomplished by the following configuration lines. You should add them at the end of the Apache web server's httpd.conf configuration file (restart your web server afterwards). 

 # Enable HP Eloquence CGI examples
 Alias /eloqcgi/ "/opt/eloquence6/share/example/eloqcgi/htdocs/"
 <Directory /opt/eloquence6/share/example/eloqcgi/htdocs>
     AllowOverride None
     Options Indexes ExecCGI FollowSymLinks
     Order allow,deny
     Allow from all
     AddHandler cgi-script .cgi
 </Directory>

Assumed your web server's host name is www.your-domain.com, the eloqcgi directory can now be addressed with the following URL: 

 http://www.your-domain.com/eloqcgi/

Any such request is now redirected into the /opt/eloquence6/share/example/eloqcgi/htdocs directory.

HP Eloquence Configuration

The eloqcgi utility invokes eloqcore to run your HP Eloquence programs. These programs should be located in a directory outside your web server's document hierarchy for security reasons.

For this purpose you should configure a special HP Eloquence volume named WWW. This volume should specify a directory where all your web-served programs are located.

Add the following line to your eloq.config configuration file to associate the eloqcgi example directory with the WWW volume name: 

 VOLUME WWW /opt/eloquence6/share/example/eloqcgi/prog

Test your Configuration

Use a web browser to access the http://www.your-domain.com/eloqcgi/ URL (of course, replace www.your-domain.com with your web server's host name). You should see a directory listing containing the eloq.cgi binary along with the sample1.html and sample2.html examples and the elogo100.gif file. If not, check the configuration steps listed above.

Click the sample1.html file and enter your name into the form, then click the submit button. You should now see a response page which was generated dynamically by the HELLO.PROG program. If not, please check your web server's error log file for the reason of the failure and review your configuration.

Now you should have the eloqcgi environment running which means that you can invoke HP Eloquence programs from any browser. These programs however must be especially tailored to be web-aware. This is described below.

The sample2.html example requires installation of the example database which is located in the /opt/eloquence6/share/example/sampledb directory. The mkdb.sh script provided in this directory can be used to conveniently setup the example database if you have an eloqdb6 database server running. For details, please refer to the README.sampledb documentation in the same directory.

If you have setup the example database you can try the sample2.html example which uses the WEBQUERY.PROG program. This program demonstates how to use eloqcgi to implement a simple database query.

Writing CGI Programs with HP Eloquence

Your own eloqcgi projects should not be located in the HP Eloquence example directory. Instead, please follow these steps to setup your own eloqcgi environment:
  1. Create a subdirectory (for example eloq) below your web server's script directory (which is usually /cgi-bin/).

    For example: 

      mkdir /opt/apache/share/cgi-bin/eloq/
    Note: Replace /opt/apache/share/cgi-bin/ with the real location of your web server's script directory.

  2. Put a symbolic link to /opt/eloquence6/lbin/eloq.cgi into this new directory.

    For example: 

      ln -s /opt/eloquence6/lbin/eloq.cgi /opt/apache/share/cgi-bin/eloq/

  3. Configure this new directory so that it is enabled to follow symbolic links. For the Apache web server, the FollowSymLinks option must be set, usually in the httpd.conf configuration file.

    Example: 

      <Directory "/opt/apache/share/cgi-bin/eloq">
      Options FollowSymLinks
  </Directory>

  4. Restart your web server.

  5. Assumed your web server's host name is www.your-domain.com, your web server's script directory is /cgi-bin/ and the new directory has been named eloq, the eloqcgi utility can now be accessed with the following URL: 
      http://www.your-domain.com/cgi-bin/eloq/eloq.cgi

  6. Finally, configure the HP Eloquence WWW volume in your eloq.config configuration file so that it points to the directory where your web-served programs are located.

    For details about using HP Eloquence volumes with eloqcgi, please refer to the chapter How eloqcgi works below.

Please note that we cannot give you a complete introduction into CGI programming here. There are a lot of resources available, either as printed books or on the Internet. What we can give you here are some tips to give you a quick starting point.

The main issue with CGI programs is that they just process single HTTP requests. On each incoming request they are started, process it and terminate afterwards.

Each output must go to the standard output which is actually connected to the browser. Thus, your program should begin with 

 PRINTER IS STDOUT

Next, the HTTP protocol requires you to specify the type of content your program creates. If this is HTML, do the following: 

 PRINT "Content-type: text/html"
 PRINT
However, if it is plain text, do the following: 
 PRINT "Content-type: text/plain"
 PRINT
The extra blank line is required by the HTTP protocol. It specifies the end of the HTTP header. Before it, you can add additional header lines. For example, the following header line causes a redirection: 
 PRINT "Location: http://eloquence.marxmeier.com"

Please refer to our examples in the /opt/eloquence6/share/example/eloqcgi/prog directory for further techniques.

How eloqcgi works

The eloqcgi utility is invoked by the web server. It processes incoming web requests and starts your associated HP Eloquence program. This enables you to use HP Eloquence to dynamically create e.g. web pages out of your database contents.

Once eloqcgi is installed as shown above it is invoked by your web server whenever it receives a request for an URL like this: 

 http://www.your-domain.com/cgi-bin/eloq/eloq.cgi/TEST?id=12&no=34
        ^                   ^       ^    ^        ^    ^     ^
        |                   |       |    |        |    |     |
        |                   |       |    |        |    |   param #2
        |                   |       |    |        |    |
        |                   |       |    |        |  param #1
        |                   |       |    |        |
        |                   |       |    |  TEST.PROG,WWW
        |                   |       |    |
        |                   |       | eloqcgi utility
        |                   |       |
        |                   | eloq subdirectory
        |                   |
        |  your web server's script directory
        |
  your web server's host name

In this example, the name of the HP Eloquence program is TEST. This is expanded by eloqcgi to TEST.PROG,WWW, thus the named program is assumed to be located in the WWW volume's associated directory.

You can also specify an absolute path to your program, as with 

 http://www.your-domain.com/cgi-bin/eloq/eloq.cgi/home/prog/TEST
In this case the program /home/prog/TEST.PROG is run.

It is also possible to specify a different volume, as with 

 http://www.your-domain.com/cgi-bin/eloq/eloq.cgi/TEST,EXAMPLE
This runs the TEST.PROG located in the EXAMPLE volume's associated directory.

Please note that these options give you a lot of flexibility but also may cause serious security problems. To overcome this, you can force a specific volume to be used by setting the EQCGI_VOLUME environment variable in the web server configuration file. For example, you could put the following line into the httpd.conf configuration file, preferrable near to the HP Eloquence CGI section: 

 SetEnv EQCGI_VOLUME "WWW"
This way, all programs must be located in the WWW volume's associated directory. There is no way anymore to override this with absolute paths or alternative volume names. As in the example above, both 
   http://www.your-domain.com/cgi-bin/eloq/eloq.cgi/home/prog/TEST
or http://www.your-domain.com/cgi-bin/eloq/eloq.cgi/TEST,EXAMPLE
will result in running TEST.PROG located in the WWW volume's associated directory.

Decoding parameters

The URL shown above specifies an HTTP GET request with two parameters: 
   http://www.your-domain.com/cgi-bin/eloq/eloq.cgi/TEST?id=12&no=34
The first parameter's name is id, its value is 12. The second parameter's name is no, its value is 34.

The eloqcgi utility decodes these parameters and puts them into environment variables before your program is run, where the variable names are prefixed with WWW_. This way you can simply access these two parameters in your HP Eloquence program as follows: 

   Id$=GETENV$("WWW_id")
   No$=GETENV$("WWW_no")

Please note that all parameters are treated as text. This implies that any national characters are automatically converted from ISO 8859-1 to the HP Eloquence internal HP Roman 8 character encoding.

For your convenience, your program's output which is sent to the browser is automatically converted to ISO 8859-1. This way, you should not have to deal with any national character conversion when using eloqcgi.

The CGI ("Common Gateway Interface") standard defines two methods of passing parameters:

  1. The GET method, which works as shown above by appending the parameters to the URL, separated by ? and & (use ? before the first and & before each following parameter). Since the maximum length of an URL is limited, this should not be used to pass a large amount of data.

  2. The POST method, where the standard input is used to pass the parameters, so there is virtually no limit on the number of parameters and the size of the data passed.

Both methods are supported by eloqcgi automatically and can even be combined. Anyway, use of parameters is optional.

© Copyright 2001 Hewlett-Packard GmbH. All rights reserved.
Revision: 2001-09-26