.
Eloquence B.08.20 contact contact

Documentation / Eloquence CGI Web Integration

Eloquence CGI Web Integration

 
.
 

Contents


Overview

Eloquence CGI enables Eloquence programs to implement dynamic web pages and services.

CGI (Common Gateway Interface) is a specification for web servers to execute programs which dynamically generate a HTTP response upon request.

CGI programs generating dynamic web pages are typically invoked from a web browser which displays the HTTP response content.

On the other hand, CGI programs implementing web services typically deliver machine readable data, for example, product information, weather data, stock prices. The data is returned as HTTP response content and typically processed in a web application.

A client (web browser, web application) submits an URL to invoke a CGI program. Optionally, arguments may be passed, for example, an authorization token, a customer number, a product code.

Eloquence CGI decodes any arguments and stores them as environment variables. It then invokes the specified Eloquence program which generates the HTTP response, using GETENV$ to obtain any arguments.


Writing Eloquence CGI programs

An Eloquence CGI program prints to the standard output to generate an HTTP response. The eloq.cgi program intercepts the program's standard output, optionally applies a character set conversion, then passes it to the web server process which sends it to the client (web browser, web application).

First, an HTTP header must be printed. It consists of one or more text lines and ends with an empty line. The first line must define the content type, optionally followed by a character set attribute.

For example:

PRINTER IS STDOUT
PRINT "Content-Type: text/html; charset=ISO-8859-15"
PRINT ""

This outputs a minimal HTTP header. It specifies that the content is HTML. The client should use the ISO-8859-15 character encoding.

Supported encodings are ISO-8859-1 and ISO-8859-15. Eloquence programs use the HP-ROMAN8 encoding. The eloq.cgi program decodes the charset attribute to perform a character set conversion.

If ISO-8859-15 is specified, the program is assumed to generate HP-ROMAN9 output. HP-ROMAN9 is a modification of HP-ROMAN8 where the Euro currency symbol (€) has been added at CHR$(186).

Examples for other content types are:

  • text/plain : plain text
  • text/richtext : text in Rich Text Format (RTF)
  • application/octet-stream : binary data

If the charset attribute is not specified the default encoding is ISO-8859-1 for content types text/html and text/plain. For other content types no character set conversion is applied unless the charset attribute is specified.


The content must immediately follow the HTTP header. If content of a specific size is output, for example to transmit binary file content, the Content-Length header should be added to tell the client how much data follows the HTTP header.

For example:

PRINTER IS STDOUT
PRINT "Content-Type: application/octet-stream"
PRINT "Content-Length: 1000"
PRINT "Content-Disposition: attachment; filename="&CHR$(34)&"test.bin"&CHR$(34)
PRINT ""

Following this HTTP header, the program outputs 1000 bytes. The eloq.cgi program does not apply a character set conversion because no content type charset attribute is specified.

The Content-Disposition header provides additional information about how the client should handle the content:

  • attachment : The content should be saved to a file. A web browser might open a download dialog. As an alternative, inline would tell a web browser to display the content.

  • filename : The client should use this name to save the file.


If the content is HTML it should consist of a <head> section followed by a <body> section.

For example:

PRINTER IS STDOUT
PRINT "Content-Type: text/html; charset=ISO-8859-15"
PRINT ""
!
PRINT "<head>"
PRINT "<title>Hello Eloquence CGI</title>"
PRINT "</head>"
!
PRINT "<body>"
PRINT "<h1>Eloquence CGI says hello :)</h1>"
PRINT "</body>"
STOP

Another example demonstrating the use of an optional argument:

Name$=GETENV$("WWW_name")
IF NOT LEN(Name$) THEN Name$="stranger"
!
PRINTER IS STDOUT
PRINT "Content-Type: text/html; charset=ISO-8859-15"
PRINT ""
!
PRINT "<head>"
PRINT "<title>Hello Eloquence CGI</title>"
PRINT "</head>"
!
PRINT "<body>"
PRINT "<h1>Hello "&Name$&" :)</h1>"
PRINT "</body>"
STOP

This program detects whether or not a name argument is specified, to output an appropriate message. For example, it could be invoked with an URL like:

http://www.your-domain.com/eloqcgi/HELLO?name=Joe


Web server configuration

Eloquence CGI requires a web server configured to allow execution of the eloq.cgi program.

The example below configures the Apache HTTP server (version 2.2 or 2.4) for Eloquence CGI.

Alias /eloqcgi "/opt/eloquence/8.2/lbin/eloq.cgi"

<Directory "/opt/eloquence/8.2/lbin">

  Options +ExecCGI
  AddHandler cgi-script .cgi

  # Apache 2.2
  <ifModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
  </ifModule>

  # Apache 2.4
  <ifModule mod_authz_core.c>
    Require all granted
  </ifModule>

</Directory>

Typical Apache HTTP server installations provide a conf.d configuration subdirectory where individual configuration files should be located. The above configuration could be stored in a file named conf.d/eloqcgi.conf.

The eloq.cgi program is located in the Eloquence lbin installation directory. In the example above, the Eloquence B.08.20 eloq.cgi program is configured.

The /eloqcgi alias URI is configured so that Eloquence CGI requests can be addressed like: http://www.your-domain.com/eloqcgi

The lbin directory is configured to allow execution of CGI programs having a .cgi file name extension. Access to this directory is granted to everybody, which is configured for both Apache HTTP server versions 2.2 and 2.4.

On the Windows platform the equivalent configuration is:

Alias /eloqcgi "C:/Program Files (x86)/Eloquence/8.2/lbin/eloq.cgi"

<Directory "C:/Program Files (x86)/Eloquence/8.2/lbin/eloq.cgi">

  Options +ExecCGI
  AddHandler cgi-script .cgi

  # Apache 2.2
  <ifModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
  </ifModule>

  # Apache 2.4
  <ifModule mod_authz_core.c>
    Require all granted
  </ifModule>

</Directory>

The above configuration assumes that Eloquence B.08.20 is installed in the C:\Program Files (x86)\Eloquence\8.2 directory.

Please note that forward slashes are used (C:/ instead of C:\) because the Apache HTTP server may interpret the backslash as escape character.


eloq.cgi configuration

The eloq.cgi program is configured with environment variables set in the web server configuration.

For example, the configuration below sets the EQCGI_VOLUME configuration variable:

<Directory "/opt/eloquence/8.2/lbin">

  Options +ExecCGI
  AddHandler cgi-script .cgi

  SetEnv EQCGI_VOLUME "CGI"

  ...

</Directory>

Configuration variables:

EQCGI_VOLUME
Enforces that Eloquence CGI programs are located in the configured Eloquence volume regardless whether a different volume or an absolute path is specified in the request URL.

Please note: For security reasons this should be configured.

EQCGI_MAXPOST
Maximum number of bytes accepted in a single HTTP POST request. Default is 1M (1 MB, megabyte), 0 = unlimited.

For example:

  • 256000 : 250 KB (kilobytes, 250 * 1024 bytes)
  • 250k : 250 KB (also 250K)
  • 10M : 10 MB (10 * 1024 * 1024 bytes, also 10m)

EQCGI_MAXUPLOAD
Maximum size accepted for a single uploaded file. Default is 1M (1 megabyte), 0 = unlimited.

EQCGI_TMPDIR
Directory used to temporarily store uploaded files. If not set the system-defined default directory is used.

EQCGI_LOGFILE
If set, the eloq.cgi program writes the specified log file. The log file directory must allow create/write access to the user and/or group running the web server process.

If not set, eloq.cgi log messages are output to the web server error log.

EQCGI_LOGLEVEL
Specifies which eloq.cgi events are logged:
  • 0 or not set: Error conditions are logged.
  • 1: Informational messages are logged in addition.
  • 2: Debug messages are logged in addition. Logs details about request type and decoded arguments.
  • 3: More verbose debug messages are logged in addition.

EQCGI_ARGS
Additional arguments to be passed to Eloquence eloqcore which runs the CGI program.

For example, to create a trace file:

SetEnv EQCGI_ARGS "-t3 -log /tmp/eloqcgi.log"
Please note that the options -n -b are always passed.

EQCGI_BIN
Location of Eloquence eloqcore. Setting this might be useful for debugging purposes.


Invocation URL format

Given the above configuration, an Eloquence CGI program would be invoked with an URL like:

http://www.your-domain.com/eloqcgi/TEST?id=12&code=34
       ^                   ^       ^    ^     ^
       |                   |       |    |     |
       |                   |       |    |     |
       |                   |       |    |   argument #2
       |                   |       |    |
       |                   |       |    |
       |                   |       |   argument #1
       |                   |       |
       |                   |       |
       |                   |   TEST.PROG,WWW
       |                   |
       |                   |
       |   /eloqcgi alias referring to the eloq.cgi program
       |
       |
   your web server's host name
The part after http://www.your-domain.com/eloqcgi/ and before the query string (starting with ?) is the Eloquence CGI progam name.

Here, this is TEST which expands to TEST.PROG,WWW, thus the TEST.PROG program located in the configured Eloquence volume WWW is run.

The Eloquence CGI default volume is WWW which can be overridden by providing a different volume or by specifying an absolute path, like:

http://www.your-domain.com/eloqcgi/TEST,EXAMPLE?id=12&code=34
http://www.your-domain.com/eloqcgi/opt/prog/TEST?id=12&code=34

For security reasons, the Eloquence CGI volume should be enforced by setting the EQCGI_VOLUME environment variable. This way, Eloquence CGI programs are located in the configured volume regardless whether a different volume or an absolute path is specified in the URL.

For example, the configuration below enforces volume CGI for all Eloquence CGI programs:

<Directory "/opt/eloquence/8.2/lbin">

  Options +ExecCGI
  AddHandler cgi-script .cgi

  SetEnv EQCGI_VOLUME "CGI"

  ...

</Directory>


Decoding of arguments

The URL may optionally contain a query string to pass arguments to an Eloquence CGI program, for example:

http://www.your-domain.com/eloqcgi/TEST?id=12&code=34

Here, the arguments id (value "12") and code (value "34") are passed.

The eloq.cgi program decodes these arguments, prefixes the argument identifiers with WWW_, then stores them as environment variables. Values are converted to the HP-ROMAN8 character encoding.

The CGI program uses GETENV$ to obtain the arguments, for example:

Id$=GETENV$("WWW_id")
Code$=GETENV$("WWW_code")


The eloq.cgi program also decodes HTTP POST request arguments, for example when a web browser submits a web form.

Consider the web form below:

<form action="/eloqcgi/HELLO">

  <p>Please enter your name:
  <input type="text" name="name" /></p>

  <p><input type="submit" /></p>

</form>

This form submits an HTTP POST request to the HELLO.PROG Eloquence CGI program. The form encoding is application/x-www-form-urlencoded because the form's enctype attribute is not set otherwise.

The HELLO program then obtains the user input with:

Name$=GETENV$("WWW_name")

Please note: The total size of the HTTP POST request content is limited to EQCGI_MAXPOST (default: 1 MB).


The eloq.cgi program also recognizes the more advanced multipart/form-data form encoding which supports HTTP file uploads.

Consider the web form below:

<form action="/eloqcgi/UPLOAD"
      enctype="multipart/form-data">

  <p>Login: <input type="text" name="login" /></p>

  <p>Password: <input type="password" name="password" /></p>

  <p>Document: <input type="file" name="document" /></p>

  <p><input type="submit" value="Upload" /></p>

</form>

This creates a web form with two text input fields (Login, Password) and a file upload field (Document). The file upload field will have an additional browse button which allows the user to select a local file. The field values along with the file contents will be submitted when the user clicks the Upload button. The submitted data is sent to the UPLOAD.PROG Eloquence CGI program.

The eloq.cgi program stores the uploaded file's binary content to a temporary file, and the environment variables below are set for the Eloquence CGI program:

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 binary data of the file which was entered into the Document field.

The temporary file is deleted after the Eloquence CGI program has finished unless it is renamed and/or moved to a different directory.

WWW_document_NAME
Original file name of the uploaded file.

WWW_document_TYPE
Mime type of the uploaded file. For example: text/plain, application/octet-stream, application/msword

WWW_document_SIZE
Size of the uploaded data in bytes, equivalent to the temporary file size.

Please note:

  • An uploaded file has 4 environment variables associated with it to specify the temporary and original file names, and the mime type, and the file size.

  • It is possible to upload multiple files in a single POST request by specifying multiple <input type="file" ... /> form fields. This would create multiple temporary files, one for each file upload.

  • The total size of the HTTP POST request content is limited to EQCGI_MAXPOST (default: 1 MB).

  • The size of a single uploaded file is limited to EQCGI_MAXUPLOAD (default: 1 MB).


For both the application/x-www-form-urlencoded and multipart/form-data form encodings, the eloq.cgi program uses the content type character set of the HTTP POST request to convert field values to the HP-ROMAN8 character encoding. The recognized character sets are: ISO-8859-1, ISO-8859-15, UTF-8.


If the POST request encoding is neither application/x-www-form-urlencoded nor multipart/form-data, the binary request data is stored to a temporary file, and the environment variables below are set for the Eloquence CGI program:

POSTDATA_TYPE
Contains the content type. If the request is not a POST request or the content type is not specified, this variable is not set.
For example: text/plain

POSTDATA_CHARSET
Contains the character set. If no character set is specified, this variable is not set.
For example: ISO-8859-1

POSTDATA_NAME
Contains the temporary file name. If no temporary file is created, this variable is not set.

The temporary file is deleted after the Eloquence CGI program has finished unless it is renamed and/or moved to a different directory.

POSTDATA_SIZE
Contains the request data size in bytes. If a temporary file is created, this is equivalent to the temporary file size.

In addition, if the POST request encoding is text/xml, the environment variables below are set for backward compatibility:

XML_TEMPFILE
Same as POSTDATA_NAME (see above).

XML_TEMPFILE_SIZE
Same as POSTDATA_SIZE (see above).

Please note: The total size of the HTTP POST request content is limited to EQCGI_MAXPOST (default: 1 MB).


Example programs

Eloquence CGI example programs are available for download:
eloqcgi.tgz (compressed tar archive)

The contents of this archive should be extracted to the Eloquence share/example directory.

Please note: These examples have been updated as of April, 2020. An existing share/example/eloqcgi directory should be deleted, then the updated examples should be installed.

For example:

cd /opt/eloquence/8.2/share/example
rm -rf eloqcgi
tar xzf /path/to/eloqcgi.tgz

The example programs require a web server configuration like below, to define the /ex.eloqcgi alias URI, and to grant access to the Eloquence CGI example directory to everybody:

Alias /ex.eloqcgi "/opt/eloquence/8.2/share/example/eloqcgi/htdocs"

<Directory "/opt/eloquence/8.2/share/example/eloqcgi/htdocs">

  # Apache 2.2
  <ifModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
  </ifModule>

  # Apache 2.4
  <ifModule mod_authz_core.c>
    Require all granted
  </ifModule>

</Directory>

On the Windows platform the equivalent configuration is:

Alias /ex.eloqcgi "C:/Program Files (x86)/Eloquence/8.2/share/example/eloqcgi/htdocs"

<Directory "C:/Program Files (x86)/Eloquence/8.2/share/example/eloqcgi/htdocs">

  # Apache 2.2
  <ifModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
  </ifModule>

  # Apache 2.4
  <ifModule mod_authz_core.c>
    Require all granted
  </ifModule>

</Directory>


HELLO example:

This example demonstates responding to a web form submission.

Invoke it using an URL like below:

http://www.your-domain.com/ex.eloqcgi/sample1.html


Customer query example:

This example demonstates accessing and displaying customer data. As a prerequisite, the eloqdb database server must be locally accessible, and the Eloquence example database must be present (database name: localhost:eloqdb/SAMPLE).

Invoke it using an URL like below:

http://www.your-domain.com/ex.eloqcgi/sample2.html


File upload/download example:

This example demonstates uploading and downloading files. The upload example uses the multipart/form-data web form encoding.

Please note: The uploaded file is stored as /tmp/demo.doc, its meta data (file information) is stored as /tmp/demo.meta. To use this example on the Windows platform the UPLOAD.PROG and DOWNLOAD.PROG and DOWNLOADFILE.PROG programs must be modified to use a different directory.

Invoke the file upload example using an URL like below:

http://www.your-domain.com/ex.eloqcgi/upload.html

After a file has been uploaded, invoking an URL like below allows to display the file information and to download the file:

http://www.your-domain.com/ex.eloqcgi/download.html


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2020-05-04  
  Copyright © 2006-2020 Marxmeier Software AG