The program's DLG output is then merged with both a page header and a page trailer which can be user-defined. Additionally, a redirection to user-defined URLs can take place if a session has terminated or expired.

Therefore, the mod_eloq has many configuration options, but appropriate default settings have been chosen to provide an easy starting point.

Contents:

• Introduction
• Configuration options
  • Eloquence Program Options
  • EloqSD Options
  • Page Layout Options
  • Miscellaneous Options

Introduction

The location of your Apache web server's httpd.conf configuration file depends on the Apache installation on your system. For example: /opt/apache/conf/httpd.conf (HP-UX, Apache 1.3) /opt/hpws/apache/conf/httpd.conf (HP-UX, Apache 2.0) /etc/httpd/httpd.conf (SuSE Linux) /etc/httpd/conf/httpd.conf (Red Hat Linux) With the precompiled Apache version from either the Eloquence CD or the Eloquence ftp server, the location is /etc/opt/apache/httpd.conf.

First of all, a LoadModule directive is necessary to make mod_eloq known to Apache. You can either place it where other LoadModule directives are placed or create a new section anywhere in httpd.conf dedicated to Eloquence:

  # Eloquence Module
  LoadModule eloq_module /opt/eloquence6/lib/mod_eloq.so

This requests Apache to load mod_eloq from the specified location (/opt/eloquence6/lib/) and to associate the name eloq_module with it (the name does not have any further meaning).

Notes: If you are using an Apache 2.0 web server, load the mod_eloq2 module instead: LoadModule eloq_module /opt/eloquence6/lib/mod_eloq2.so If your Apache 1.3 web server was compiled with the mod_ssl functionality you should load the mod_eloq_eapi module instead: LoadModule eloq_module /opt/eloquence6/lib/mod_eloq_eapi.so You should use mod_eloq_eapi if your Apache web server displays the following message during startup: Loaded DSO /opt/eloquence6/lib/mod_eloq.so uses plain Apache 1.3 API, this module might crash under EAPI! (please recompile it with -DEAPI) On HP-UX, the mod_eloq, mod_eloq_eapi and mod_eloq2 module files are contained in subdirectories below /opt/eloquence6/lib/ which reflect the various architectures. The following conventions apply: pa11_32 PA-RISC 1.1 compatible modules (32 bit) pa20_32 PA-RISC 2.0 modules (32 bit) pa20_64 PA-RISC 2.0 modules (64 bit) hpux32 IA64 32 bit modules (Itanium) hpux64 IA64 64 bit modules (Itanium) Please note that not all of these module variants may be available, depending on the installed Eloquence version.

After that, one or more locations should be configured, one for each of your Eloquence programs. A location is a virtual URL which does not correspond with a file or a directory in your file system.

Example:

• Assumed your web server's hostname is www.yourhost.com,
• further assumed your program's starting point shall be http://www.yourhost.com/your/prog,

It is convenient to make the definition of all mod_eloq locations dependend on whether the module was loaded or not. This is accomplished with the <IfModule> directive.

In the following example, a location for mod_eloq is defined which is configured to start the TEST program in the WWW volume:

  <IfModule mod_eloq.c>

    <Location /eloq/test>
      SetHandler eq-web-dlg
      EloqCommand TEST,WWW
    </Location>

  </IfModule>

Explanation:

• The <IfModule> directive encloses the whole definitions related to mod_eloq.
  If you ever wish to start your Apache web server without mod_eloq to be activated, you could simply do this just by commenting the LoadModule directive above (by placing a # character in front of it), the <IfModule> directive would then cause all the lines related to mod_eloq to be skipped when Apache reads the httpd.conf file.

• The <Location /eloq/test> directive defines a virtual URL.

• The SetHandler eq-web-dlg directive associates this location with the WEBDLG handler which is built into mod_eloq. This makes the /eloq/test location sensitive for Eloquence WEBDLG.

• The EloqCommand TEST,WWW is the command line passed to Eloquence (a detailled description of the various configuration options follows in the next section).

If you have more than one starting point for your application, i.e. if you want to create a menu from where different modules of your application can be invoked, it might be convenient to place the configuration options which are common to all modules into a common parent location.

For example, if all modules share the same environment variables, a configuration could be laid-out similar to this:

  <IfModule mod_eloq.c>

    # Common parent location
    <Location /eloq>
      EloqEnvironment HOME /home/whoever
    </Location>

    # Sub-location for program M1
    <Location /eloq/m1>
      SetHandler eq-web-dlg
      EloqCommand M1,WWW
    </Location>

    # Sub-location for program M2
    <Location /eloq/m2>
      SetHandler eq-web-dlg
      EloqCommand M2,WWW
    </Location>

  </IfModule>

Explanation:

• The sub-locations /eloq/m1 and /eloq/m2 inherit all configuration options from their parent location /eloq. Thus, the HOME=/home/whoever needs to be defined only once for all sub-locations.

• Since the /eloq parent location does not have a SetHandler directive it does not really exist in your web server's document hierarchy. This means that any request to http://www.yourhost.com/eloq will return a HTTP status 404 ("not found").

• Therefore, both sub-locations /eloq/m1 and /eloq/m2 define the SetHandler eq-web-dlg directive separately. By means of the EloqCommand directives, the /eloq/m1 sub-location is associated with the M1,WWW program, while the /eloq/m2 sub-location is associated with the M2,WWW program.

Configuration options

Sub-locations inherit the configuration options from their respective parent locations (see the EloqInheritParentDirConf directive below for details).

All arguments must be enclosed in double quotes if they contain space characters.

The first group of configuration options defines which Eloquence program shall be started and which environment shall be used. The EloqCommand directive is required as soon as SetHandler eq-web-dlg is specified, all other directives are optional.

Eloquence Program Options
EloqCommand
Command line to be passed to Eloquence. The -b command line option (force background processing) is always passed implicitely. Example: EloqCommand "TEST,WWW" EloqCommand "-t -log /tmp/eq.log TEST,WWW"
EloqStartDirectory
Optional start directory. Example: EloqStartDirectory /opt/your_app
EloqEnvironment
Name and value of an optional environment variable to be passed to Eloquence. Specify one EloqEnvironment directive for each environment variable which shall be passed to Eloquence. Example: EloqEnvironment HOME /home/whoever Additional environment variables can be dynamically passed in the program's URL. Please refer to the Getting started document for details.

The second group of configuration options covers the eloqsd protocol which is used to start your Eloquence programs. If the eloqsd settings are the same for all or most of your programs you will probably define them in the /etc/opt/eloquence6/eloqwebd.cfg configuration file, but if you need different settings per program you can specify them for each location individually.

EloqSD Options
EloqSDHostname
Host name or IP address of the Eloquence application server where your programs are about to be executed. This must have an eloqsd configured and running. Example: EloqSDHostname localhost
EloqSDService
Service name or port number of the eloqsd to be contacted. Example: EloqSDService eloqsd
EloqSDUser
User name which is used to log-on to the eloqsd. Example: EloqSDUser eloqwww
EloqSDPassword
Password which is used to authenticate to the eloqsd. Example: EloqSDPassword secret

The third group of configuration options deals with the overall HTML page layout. All of these directives are optional.

Page Layout Options
EloqPageHeader
A standard page header is generated by default which can be overridden with a file specified by the EloqPageHeader directive. This file should contain a complete HTML page header including the <body> tag. It can optionally contain CSS style definitions which define the presentation of the dialog controls and/or additional JavaScript functions to enhance the functionality of your dialogs. The file name can either be absolute or relative to Apache's ServerRoot directory. Example: EloqPageHeader /opt/eloquence6/share/example/webdlg/page_header.tmpl Use the following token to insert the WEBDLG page title (which is the title of the currently displayed dialog or POPUP BOX) into your page header template: <!--eloq: PageTitle--> At runtime, this token is dynamically replaced by the real page title (see EloqPageTitle below for details). Please refer to /opt/eloquence6/share/example/webdlg/page_header.tmpl for an example of a page header file.
EloqPageTrailer
A standard page trailer is generated by default which can be overridden with a file specified by the EloqPageTrailer directive. This file should contain a complete HTML page trailer including the </body> tag up to the final </html> tag. The file name can either be absolute or relative to Apache's ServerRoot directory. Example: EloqPageTrailer /opt/eloquence6/share/example/webdlg/page_trailer.tmpl Use the following token to insert the WEBDLG page title (which is the title of the currently displayed dialog or POPUP BOX) into your page header template: <!--eloq: PageTitle--> At runtime, this token is dynamically replaced by the real page title (see EloqPageTitle below for details). Please refer to /opt/eloquence6/share/example/webdlg/page_trailer.tmpl for an example of a page trailer file.
EloqPageTitle
This directive specifies the standard page title. Normally, the page title is the title of the currently displayed dialog or POPUP BOX. If however this title is empty or the program has terminated or expired, the title specified here is displayed. Example: EloqPageTitle "My Eloquence Application" If not specified, the standard page title is "Eloquence".
EloqPageCSSHeader
If you do not define an EloqPageHeader as explained above, this directive allows you to specify a file containing additional CSS style definitions which define the presentation of the dialog controls and/or additional JavaScript functions to enhance the functionality of your dialogs. This file will be merged into the standard page header. The file name can either be absolute or relative to Apache's ServerRoot directory. Example: EloqPageCSSHeader /opt/eloquence6/share/example/webdlg/page_css_header.tmpl Please refer to /opt/eloquence6/share/example/webdlg/page_css_header.tmpl for an example of a page CSS header file.
EloqSessionFinishedText
A standard "session finished" page is displayed by default whenever your program terminates. This page is composed using the EloqPage... directives explained above. The "session finished" text on this page can be customized. Example: EloqSessionFinishedText "Programm ist beendet." If not specified, the standard "session finished" text is "Eloquence program terminated".
EloqSessionFinishedDocument
A standard "session finished" page is displayed by default whenever your program terminates. This page is composed using the EloqPage... directives explained above. However, the EloqSessionFinishedDocument directive allows you to redirect to a different URL as soon as the program has terminated. This could be your main menu as well as the program's location itself in which case the program would be automatically re-started. Example: # Automatically re-start the M1 program EloqSessionFinishedDocument /eloq/m1
EloqSessionExpiredText
After a configurable timeout period has expired without activity, your program will be terminated automatically. In this case, a standard "session expired" page is displayed by default. This page is composed using the EloqPage... directives explained above. The "session expired" text on this page can be customized. Example: EloqSessionExpiredText "Session ist abgelaufen." If not specified, the standard "session expired" text is "Eloquence session has expired".
EloqSessionExpiredDocument
After a configurable timeout period has expired without activity, your program will be terminated automatically. In this case, a standard "session expired" page is displayed by default. This page is composed using the EloqPage... directives explained above. However, the EloqSessionExpiredDocument directive allows you to redirect to a different URL whenever the session has expired. This could be your main menu as well as the program's location itself in which case the program would be automatically re-started. Example: # Automatically re-start the M1 program EloqSessionExpiredDocument /eloq/m1 The timeout period is specified in the /etc/opt/eloquence6/eloqwebd.cfg configuration file.
EloqSessionRestartText
On the standard "session finished" and "session expired" pages, a link is displayed which allows to restart the program. This link's text can be customized. Example: EloqSessionRestartText "Programm neu starten" If not specified, the standard text is "restart program".

The last group of configuration options is related to various runtime settings. All of these directives are optional.

Miscellaneous Options
EloqWebD
Location of the eloqwebd executable if it is not located in the /opt/eloquence6/bin/ directory. Example: EloqWebD /tmp/eloqwebd
EloqInheritParentDirConf
Set this directive to Off if for any reason the configuration options of a parent location shall not be inherited by a sub-location. Example: # This sub-location does not inherit from its parent EloqInheritParentDirConf Off