A.06.31 Release Notes
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:
The following eloqcgi Files are installed with 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.
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.
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.
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
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.
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.
-
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/
-
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.
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.
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.
|
