• You have a ASCII DLG compatible program which already runs with the GUI frontend (using dlgsrv or JDLG).

• This program is started on a remote system using an Eloquence start file and the Eloquence eloqsd application server.

• You already have an Apache web server running (can be on a different system than where the eloqsd is running).

• it does not run with the GUI frontend but requires a terminal window because it outputs to the screen buffer with DISP, PRINT etc. or uses INPUT etc. In this case the programm may need considerable modifications to become "pure ASCII DLG".

• it relies on ASCII DLG functionality which is not portable to a client-server environment, such as the .kbcode or .kbind attributes (which assume that DLG is run within the screen buffer).

• it depends on specific features of the IDM based dlgsrv implementation and/or the RUN server, such as IDM files, the EqHelpPath variable or DDE communications. In such a case, the DLG SET ".driver" setting is often queried to find out if the program runs with the GUI frontend or not. These dependencies must be modified so that the program becomes compatible to "pure ASCII DLG" (independendly if the .driver is set).

Contents:

• Installation
• Configuration
• Test your first WEBDLG program
• Providing dynamic startup parameters
• More example programs

Installation

Apache on HP-UX:

• For HP-UX 11.0 and HP-UX 11i, compiled (and hp supported) versions of the Apache web server is available for download from hp. For more information please refer to the hp.com website. For download please refer to the HP software download web site www.software.hp.com (search for Apache).

The Eloquence programs may run on a different system than the web server. In this case, it is sufficient to install the Eloquence WEBDLG software standalone on the system running the Apache web server.

However, the system where you want to run your programs needs a full Eloquence installation and an appropriately configured and running eloqsd application server. In particular, a user must be configured in the /etc/opt/eloquence6/eloqsd.user file which has the necessary privileges to run your programs (see below for an example).

The installed files are placed into the following directories:

  /opt/eloquence6/bin/

- the eloqwebd executable

  /opt/eloquence6/lib/

- the mod_eloq, mod_eloq_eapi and mod_eloq2 Apache web server module files

  /opt/eloquence6/newconfig/config/

- the eloqwebd template configuration file (see below)

  /opt/eloquence6/share/example/webdlg/

- example programs, dialogs and HTML template files (see below)

  /opt/eloquence6/share/doc/webdlg/

- this documentation

If you don't have any ASCII DLG programs, the following test program could serve as a starting point. It is a very simple "hello world" example program which would run from the command line as well as with WEBDLG: 10 POPUP BOX "[Hello World][This is a POPUP BOX|from Eloquence][Dismiss]" 20 STOP

If you didn't ever use the eloqsd server to start your programs, the following lines could be added to your /etc/opt/eloquence6/eloqsd.user configuration file to give you a starting point: [webdlg] Name = Eloquence WEBDLG example user Password = webdlg Uid = <your HP-UX/Linux user name> Gid = <the HP-UX/Linux group name you belong to> Having this configured, you would log on to eloqsd with user name "webdlg" and password "webdlg" and your programs would run with your regular HP-UX/Linux user/group permissions due to the Uid/Gid settings. This is OK for testing purposes. However, for security reasons you should later create a separate HP-UX/Linux user/group with restricted permissions to be used with WEBDLG if possible.

Configuration

1. the host name or IP address of the system where the eloqsd is running (if different from the system where you installed the WEBDLG software)

2. the service name or port number the eloqsd listens to (if different from the "eloqsd" default service name)

3. the user name and password used to log-on to the eloqsd

4. the command line used to start your program

5. any additional environment variables

6. the start directory for your program if necessary

The first three configuration settings take place in the eloqwebd configuration file /etc/opt/eloquence6/eloqwebd.cfg in the [Eloqsd] section.

During installation, an eloqwebd.cfg template configuration file has been installed into the /opt/eloquence6/newconfig/config/ directory. If you configure WEBDLG for the first time please copy this template file into the /etc/opt/eloquence6/ directory. If you, however, already have a working eloqwebd.cfg configuration please compare it with the new template file since it is likely that new configuration items have been added.

### EloqSD protocol

[EloqSD]

# Hostname      The host name or IP address of the system where the
#               Eloquence programs are started by default.
#               The default value is 'localhost' (aka. 127.0.0.1).

#Hostname = 127.0.0.1

# Service       The default eloqsd service name (as defined in /etc/services)
#               or the port number.
#               The default value is 'eloqsd'.

#Service = eloqsd

# User          The default user name which is used to log on to eloqsd.

#User =

# Password      The default password which is used to log on to eloqsd.

#Password =

The User and Password settings are required. However, the Hostname and Service settings are not required if the eloqsd runs on the same system where the WEBDLG software has been installed and it listens to the "eloqsd" default service.

Additionally, we recommend to lower the session timeout to 5 minutes (default is 1 hour). This will avoid too much pending sessions during development. The relevant setting is in the [Session] section:

[Session]

# Expires       Number of seconds until DLG session expires. During a DLG DO
#               or POPUP BOX command, this is the maximum idle time until an
#               error #684 is returned.
#               The default value is 3600 seconds (1 hour).

Expires = 300

The last three configurations take place in the mod_eloq Apache web server module's configuration because they relate to the particular program you want to start and you could have more than one program start configuration.

The location of your Apache web server's httpd.conf configuration 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, the location is /etc/opt/apache/httpd.conf.

Add the following lines to the end of your Apache web server's httpd.conf configuration file:

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

  <IfModule mod_eloq.c>

    <Location /eloq/test>
      SetHandler eq-web-dlg
      EloqPageCSSHeader "/opt/eloquence6/share/example/webdlg/page_css_header.tmpl"
      EloqCommand "<your program's command line>"
    </Location>

  </IfModule>

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.

Instead of "<your program's command line>" of course the particular command line must be specified, e.g. "TEST,WWW" to start the TEST program in the WWW volume.

For each additional environment variable, add an EloqEnvironment directive below the EloqCommand setting.

For example, your program might require the HOME environment variable to be set because it refers to volume definitions in an .eloqrc file which otherwise would not be loaded:

      EloqEnvironment "HOME" "/home/whoever"

If your program requires a start directory to be configured because it accesses files in the current directory, specify:

      EloqStartDirectory "/start/directory/for/your/program"

To summarize this, here is a complete httpd.conf configuration block which configures the TEST,WWW program to be run in the specified start directory with an additional HOME environment variable:

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

  <IfModule mod_eloq.c>

    <Location /eloq/test>
      SetHandler eq-web-dlg
      EloqPageCSSHeader "/opt/eloquence6/share/example/webdlg/page_css_header.tmpl"
      EloqCommand "TEST,WWW"
      EloqEnvironment "HOME" "/home/whoever"
      EloqStartDirectory "/start/directory/for/your/program"
    </Location>

  </IfModule>

For details about the available configuration directives, please refer to the mod_eloq and eloqwebd configuration chapters.

Test your first WEBDLG program

First, re-start your Apache web server or reload its configuration so your modifications to the httpd.conf file are activated.

It is possible that you receive a message like this while your Apache web server starts: 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) In this case you should use the mod_eloq_eapi module instead of mod_eloq (see above).

Now open a browser window and enter the URL http://www.yourhost.com/eloq/test (replace www.yourhost.com with the host name of your system running the Apache web server).

This should bring up your program's first dialog or POPUP BOX in your browser window. If this has worked, then:

   Congratulations!

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).

Providing dynamic startup parameters

http://www.yourhost.com/eloq/test?id=12&no=34

WEBDLG decodes these parameters and passes them to your program as environment variables, where the variable names are prefixed with WWW_. This way you can simply access these two parameters in your Eloquence program as follows:

   Id$=GETENV$("WWW_id")
   No$=GETENV$("WWW_no")

Simply append the required parameters to the URL. Use ? before the first and & before each following parameter. If the parameters' names and/or values contain spaces, replace them with + characters. Additionally, any non-ASCII characters (e.g. national characters) must be URL-encoded, that is, replace them with % followed by its hexadecimal character code. Examples: YOUR NAME must be passed as YOUR+NAME. The HP Roman 8 code for Ä is 216 which is D8 hexadecimal, so it must be encoded as %D8 (you must always provide two hexadecimal digits).

More example programs