|
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.
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 texttext/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
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.3/lbin/eloq.cgi"
<Directory "/opt/eloquence/8.3/lbin">
Options +ExecCGI
AddHandler cgi-script .cgi
SetEnv LC_CTYPE "en_US.iso885915"
# 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.40 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.
The LC_CTYPE environment variable is set for Eloquence
eloqcore, to prevent an "unrecognized codeset" error message.
Since Eloquence B.08.40, eloqcore uses the
configured locale
to define the character set encoding. Please use the locale -a
command to find an appropriate locale providing the ISO-8859-15 or ISO-8859-1
character encoding.
On the Windows platform the equivalent configuration is:
Alias /eloqcgi "C:/Program Files (x86)/Eloquence/8.3/lbin/eloq.cgi"
<Directory "C:/Program Files (x86)/Eloquence/8.3/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.40 is installed
in the C:\Program Files (x86)\Eloquence\8.3 directory.
On Windows it is not necessary to set the LC_CTYPE environment
variable for Eloquence eloqcore.
Please note that forward slashes are used (C:/ instead of
C:\) because the Apache HTTP server may interpret the backslash as
escape character.
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.3/lbin">
Options +ExecCGI
AddHandler cgi-script .cgi
SetEnv LC_CTYPE "en_US.iso885915"
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.
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.3/lbin">
Options +ExecCGI
AddHandler cgi-script .cgi
SetEnv LC_CTYPE "en_US.iso885915"
SetEnv EQCGI_VOLUME "CGI"
...
</Directory>
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).
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.3/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.3/share/example/eloqcgi/htdocs"
<Directory "/opt/eloquence/8.3/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.3/share/example/eloqcgi/htdocs"
<Directory "C:/Program Files (x86)/Eloquence/8.3/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
|
