Index of /eloq/eloqcgi

Icon  Name                       Last modified      Size  
[PARENTDIR] Parent Directory - [   ] eloqcgi-hpux.tar.gz 2000-06-28 19:51 19K [   ] eloqcgi-linux-libc5.tar.gz 2000-06-28 19:51 15K [   ] eloqcgi-linux-libc6.tar.gz 2000-06-28 19:52 16K [   ] sampledb.tar.gz 2000-06-28 19:31 71K
----------------------------------------------------------------------

HP ELOQUENCE A.06.30 - Web Integration via CGI - 2000-06-28

----------------------------------------------------------------------

This package contains the eloqcgi web integration utility along with
two sample applications. It is intended to be used on either the
HP-UX or Linux platforms along with the Apache web server.

HP Eloquence A.06.20 or A.06.30 is required in order to use the
eloqcgi utility.
Please note that with A.06.20 one of the following eloqcore patches
is required:
   for the HP-UX platform: PE62-9911290
   for the Linux platform: PE62-0002171 (beta)


Installation
------------

UNIX:

In order to install this patch, you need to unpack it with gzip.
Gzip is included with HP-UX 10.x and Linux.
Installation requires root privileges.

cd /opt/eloquence6
gzip -dc /path/to/eloqcgi-<platform>.tar.gz | tar xf -

(where <platform> is either hpux, linux-libc5 or linux-libc6)

Files:

   share/example/eloqcgi/htdocs/eloq.cgi
   share/example/eloqcgi/htdocs/sample1.html
   share/example/eloqcgi/htdocs/sample2.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/README


Web Server Configuration
------------------------

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.

This is accomplished by the following configuration lines. You should
add them at the end of  your web server's http.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
       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. You should see a directory listing containing the eloq.cgi
binary along with the sample1.html and sample2.html examples and other
auxiliary files. 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.

If you have the SQL/R example database installed on your system you
can also try the sample2.html example which uses the WEBQUERY.PROG
program to access the named database.


Using eloqcgi
-------------

The eloqcgi utility serves as a bridge between the web server and
your HP Eloquence programs. This enables you to use HP Eloquence to
dynamically create e.g. web pages out of your database content.

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/eloqcgi/eloq.cgi/TEST?id=12&no=34
          ^                   ^       ^        ^    ^     ^
          |                   |       |        |    |     |
          |                   |       |        |    |   param #2
          |                   |       |        |    |
          |                   |       |        |  param #1
          |                   |       |        |
          |                   |       |  TEST.PROG,WWW
          |                   |       |
          |                   |  eloqcgi utility
          |                   |
          |        virtual eloqcgi 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/eloqcgi/eloq.cgi/home/prog/TEST

In this case the program located at /home/prog/TEST is run. It is
also possible to specify a different volume, as with

   http://www.your-domain.com/eloqcgi/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 before you start you web server. For example, you could put
the following lines at the beginning of your web server's start script:

   EQCGI_VOLUME="WWW"
   export EQCGI_VOLUME

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/eloqcgi/eloq.cgi/home/prog/TEST
or http://www.your-domain.com/eloqcgi/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/eloqcgi/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 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 '&'. 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.


Writing CGI Programs with HP Eloquence
--------------------------------------

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://www.hp-eloquence.com"

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

Enjoy!
Your HP Eloquence Team