Eloquence B.07.10 Release Notes

Overview / Web Integration using CGI

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 along with a web server (the configuration examples provided here refer to the Apache web server).

As of Eloquence B.07.10, eloqcgi is available for the HP-UX, Linux and Windows platforms.

Contents:

Installed files
Web Server Configuration
Eloquence Configuration
Test your Configuration
Writing CGI Programs with Eloquence
How eloqcgi works
Decoding parameters
Environment Variables
Uploading files

Installed files

The following eloqcgi Files are installed with Eloquence B.07.10 below the Eloquence installation directory:

 lbin/eloq.cgi
 
 share/example/eloqcgi/htdocs/eloq.cgi
 share/example/eloqcgi/htdocs/sample1.html
 share/example/eloqcgi/htdocs/sample2.html
 share/example/eloqcgi/htdocs/upload.html
 share/example/eloqcgi/htdocs/download.html
 share/example/eloqcgi/htdocs/elogo100.gif

 share/example/eloqcgi/prog/HELLO.PROG
 share/example/eloqcgi/prog/Sample2.PROG
 share/example/eloqcgi/prog/Sample2b.PROG
 share/example/eloqcgi/prog/UPLOAD.PROG
 share/example/eloqcgi/prog/DOWNLOAD.PROG
 share/example/eloqcgi/prog/DOWNLOADFILE.PROG

On HP-UX and Linux, the Eloquence installation directory is /opt/eloquence6. On Windows, you can choose it in the Eloquence installation program (by default it is C:\Program Files\Eloquence).

On HP-UX and Linux, in the share/example/eloqcgi/htdocs directory, the eloq.cgi is actually a symbolic link to /opt/eloquence6/lbin/eloq.cgi. On Windows, symbolic links are not supported so that share/example/eloqcgi/htdocs/eloq.cgi is actually a copy of lbin/eloq.cgi.

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

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

On HP-UX and Linux, 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 Eloquence below.

This example refers to HP-UX and Linux. On Windows, please replace /opt/eloquence6 with your Eloquence installation directory on Windows (for example: c:/program files/eloquence).

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

Eloquence Configuration

The eloqcgi utility invokes eloqcore to run your 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 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 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 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:

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.
On HP-UX and Linux, 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/
```
On Windows, copy lbin/eloq.cgi into this new directory (Windows does not support symbolic links).
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>
```
Restart your web server.
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
```
Finally, configure the 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 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 Eloquence program. This enables you to use 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 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 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 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 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:

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

Environment Variables

The following environment variables are recognized by eloqcgi.

EQCGI_VOLUME

If set, the specified volume will always be used regardless if a different volume or an absolute path has been specified in the URL

NOTICE: For security reasons we strongly recommended that this option is set.

EQCGI_MAXPOST

Maximum number of bytes which may be sent in a single HTTP POST request. Default is 1M (1 megabyte), 0 = unlimited.

Examples:

256000 : 250 kilobytes (250 * 1024 bytes)
250k : 250 kilobytes (also 250K)
10M : 10 megabytes (also 10m)

EQCGI_MAXUPLOAD

Maximum upload file size. Default is 1M (1 megabyte), 0 = unlimited.

EQCGI_TMPDIR

Directory used to hold temporary files (ie. upload files). If not set the system-defined default directory is used.

EQCGI_ARGS

Additional arguments to be passed to the eloqcore program.

Example:

 SetEnv EQCGI_ARGS "-t3 -d*3 -log /tmp/eqcgi.log"

Please note that the options -n -b are always passed.

EQCGI_BIN

Location of the eloqcore executable (only useful for debugging purposes)

EQCGI_DEBUG

Enables the eloqcgi debug mode. The following values are supported:

1: display variables
2: display variables and show Eloquence program output

These variables are normally specified in the web server configuration, for example by means of the SetEnv directive in the Apache httpd.conf file.

Example:

 <Directory /opt/apache/share/cgi-bin/eloq>
     SetEnv EQCGI_VOLUME "CGI"
 </Directory>

This sets the EQCGI_VOLUME environment variable to "CGI", assuming that the eloq.cgi program is located in the directory /opt/apache/share/cgi-bin/eloq

Uploading files

This release of the eloqcgi program supports HTTP file uploads. Files are uploaded as part of a HTTP POST request. Two upload methods are supported.

multipart/form-data

This combines form data with file upload. Example HTML code:

 <form method="post"
       enctype="multipart/form-data"
       action="/cgi-bin/eloq/eloq.cgi/UPLOAD">

  Login: <input type="text" name="login">
  <p>
  Password: <input type="text" name="password">
  <p>
  Document: <input type="file" name="document">
  <p>
  <input type="submit" value="Upload">
 </form>

In this example, a form will be displayed with two text input fields (Login and Password) and a file upload field. The file upload field will have an additional browse button which allows the user to select a local file. The form along with the file contents will be submitted when the user clicks the Upload button. The submitted data is sent to the UPLOAD.PROG,WWW program.

The following environment variables are passed to the Eloquence program (the variable names are taken from the name="..." attributes of the input fields prefixed with WWW_):

WWW_login: The text entered into the Login field
WWW_password: The text entered into the Password field
WWW_document: Absolute path of the temporary file holding the uploaded data of the file which was entered into the Document field
WWW_document_NAME: Original file name of the uploaded file
WWW_document_TYPE: Mime type of the uploaded file (eg. text/plain, application/msword, ...)
WWW_document_SIZE: Size of the uploaded data in bytes (ie. temporary file size)

Notes:

An uploaded file has 4 environment variables associated with it to specify the temporary and original file names, the mime type and the file size.
It is possible to upload multiple files in a single POST request by simply putting multiple <input type="file" ...> with different names into a form. In this case, multiple temporary files are created, one for each file.
The uploaded data is limited to EQCGI_MAXPOST (see above, default is 1MB). This is the maximum size of the entire post request including any contained uploaded file contents.
A single uploaded file is limited to EQCGI_MAXUPLOAD (see above, default is 1MB).

Any temporary files are automatically removed after the program has terminated. A program is free to move the temporary file to a different location before it terminates. In this case the file will not be removed.

You find a demonstration of this functionality in the upload.html and download.html examples in the Eloquence share/example/eloqcgi/htdocs installation directory. These examples use the UPLOAD.PROG, DOWNLOAD.PROG and DOWNLOADFILE.PROG programs in the share/example/eloqcgi/prog directory.

text/xml

This is normally used for XML data exchange. The uploaded file is saved into the temporary files directory (see EQCGI_TMPDIR above).

The following environment variables are passed to the Eloquence program:

XML_TEMPFILE: Absolute path of the temporary file holding the uploaded data
XML_TEMPFILE_SIZE: Size of the uploaded data in bytes (ie. temporary file size)

Note:

The uploaded data is limited to EQCGI_MAXPOST (see above, default is 1MB).

The temporary file is automatically removed after the program has terminated.