• a web browser at the user's site which serves as the frontend to your application

• an Apache web server on one of your systems which processes the HTTP requests from the user's browser

• the mod_eloq Eloquence Apache module which becomes part of your Apache web server and is responsible for processing WEBDLG requests

• the eloqwebd Eloquence web daemon which serves as a proxy for any Eloquence program instance from mod_eloq's point of view and additionally acts as a DLG server

• the eloqsd Eloquence application server which is used to start your Eloquence programs either locally or on a remote system

• eloqcore which runs your Eloquence programs as if they were normal DLG applications

During program startup, these components interact according to the following schematic:

   ------------------            ---------------------
   | user's browser | ----//---> | Apache web server |
   ------------------            |- - - - - - - - - -|
                                 | mod_eloq          |
                                 ---------------------
                                    |
                                    v
   ------------------            ---------------------
   | eloqsd         | <---//---- | eloqwebd          |
   ------------------            ---------------------
      |                             ^
      v                             |
   ------------------               | (establish DLG connection)
   | eloqcore       | ----//--------/
   ------------------

In this schematic, possible machine boundaries are represented with --//-- :

The system where the user's browser runs is typically different from the system where the Apache web server with mod_eloq and the eloqwebd are installed. Furthermore, the system where your programs are run may be different from these two. This gives you a lot of flexibility. Especially the fact that the Apache web server and your programs may reside on different systems gives you a higher security level if these two systems are located in different network segments which are connected through a firewall.

This is how a WEBDLG program is started:

1. An incoming initial request for one of your WEBDLG programs coming from the user's browser is processed by the Apache web server which delegates it internally to mod_eloq.

2. mod_eloq starts a new instance of eloqwebd and passes it the configured program start options such as the command line, additional environment variables and an optional start directory.

3. eloqwebd contacts the configured eloqsd (probably on a remote system), logs-on to it and requests it to start a new eloqcore instance for the particular program.

As said, this DLG connection is established automatically. The program is not required to perform a DLG SET ".driver" statement. If it however does, it will simply be ignored and has no further effect.

Troubleshooting: During the program start phase, all relevant error messages are forwarded into your Apache web server's error log file, regardless if they originate from mod_eloq, eloqwebd or even eloqsd. The location of your Apache web server's error log file depends on the Apache installation on your system. If you are using a precompiled Apache version from either the Eloquence CD or the Eloquence ftp server in its default configuration, the location is /var/opt/apache/logs/error_log. Thus, if a particular program cannot be started the reason is probably pointed out with an error message in your Apache web server's error log file. During development, you should permanently watch your Apache web server's error log file's contents with the tail -f command, for example: tail -f /var/opt/apache/logs/error_log However, error messages originating from eloqcore are not forwarded into your Apache web server's error log file. Thus, if the program should seem to start successfully but nevertheless does not run correctly it might be helpful to create an eloqcore log file (using the -log command line option) to locate the cause of the problem eg. during the program's startup phase (see here for an example).

As long as the program is running, the following schematic applies:

   ------------------            ---------------------
   | user's browser | <---//---> | Apache web server |
   ------------------            |- - - - - - - - - -|
                                 | mod_eloq          |
                                 ---------------------
                                    ^
                                    | (temporary)
                                    v
   ------------------            ---------------------
   | eloqcore       | <---//---> | eloqwebd          |
   ------------------            ---------------------

The problem with HTTP transactions between the user's browser and the Apache web server is that they don't have any context. This means that there is no permanent connection between the user's browser and your program. Instead, a new connection is established each time the user submits a DLG request. Thus, the connection between mod_eloq and eloqwebd is temporary (as shown in the schematic).

For this reason, a session identifier is encoded into the request's URL after the program is started. This allows mod_eloq to locate the appropriate eloqwebd instance which is associated to the particular session.

The session identifier is composed of a MD5 hash value. This value cannot be guessed so a session's privacy is guaranteed. Once a session has finished or expired the same session identifier is never used anymore. For each existing session, a FIFO file (aka. named pipe) exists in the eloq.web directory which is automatically created in your system's temporary directory (usually /tmp or /var/tmp). These FIFO files serve as communication channels between mod_eloq and eloqwebd. They are automatically removed as soon as a session terminates or expires (see below) or whenever the Apache web server is restarted.

Another problem is related to the program session's lifetime. Your programs never know if the user is still on-line or if the user's browser was closed before the particular program had finished. Due to the fact that the connection between mod_eloq and eloqwebd is temporary, your program will simply wait for the next DLG request which will never arrive if for example the user is not on-line anymore.

To overcome this, a timeout value can be configured which is one hour by default. If your program waits for a DLG request and this timeout expires without activity, your program receives an error #684 (DLG driver process not found or connection is broken).

Important Note: Your program should be prepared that during any DLG DO or POPUP BOX statement, this timout can expire, causing an error #684. If the timeout has expired, the DLG connection to your program no longer exists, so your program should terminate immediately. Special care should be taken if your program uses ON ERROR to define a global error handler. Make sure this error handler does an OFF ERROR before it does anything else. For example, using POPUP BOX to display the error message would cause an endless loop in your program if the error was caused by the elapsed timeout and no OFF ERROR took place before POPUP BOX. In such a case, POPUP BOX would immediately cause the error handler to be invoked recursively because the DLG connection no longer exists. Your program would not terminate but consume CPU cycles infinitely.