Starting Eloquence Programs from your Windows desktop

The EqStart Utility

The EqStart utility makes it very convenient to start any Eloquence program from your Windows desktop. This document is separated into the following sections:

How to install the EqStart utility

The EqStart utility is installed with the Eloquence Setup program if the Eloquence Runtime installation category is checked.

The eqstart.exe executable file is installed in the bin subdirectory below the installation base directory. This is usually C:\Program Files\Eloquence\bin.


Creating a new Eloquence Program Start File

The EqStart utility uses start files which contain the settings used to start your programs. These are regular INI files which can be edit easily using any text editor.

However, there is a much more comfortable way to create these files:

  1. Click the right mouse button on the background of your Windows desktop. This opens the context menu.
  2. Select the New item from the context menu. This opens a second menu level with a list of file types.
  3. Select the Eloquence Start File from the list of file types. This creates a new icon on your desktop called New Eloquence Start File.eloq.
  4. Rename the icon to whatever you want (however, do NOT change the .eloq extension). The name should reflect the title of your Eloquence program.
The icon you have just created is actually an empty start file. You can create any number of start files in any location you want. The creation of start files is not limited to the Windows desktop. It works in any subdirectory which is displayed with the Windows Explorer (e.g. My Computer), too.

After you have created an empty start file, it should be configured. As long as the start file is empty, you can access the configuration dialog by just double-clicking the start file's icon.

If you double-click an already configured start icon, the associated program will be started. To access the configuration dialog, you open the icon's context menu and select the Configure item.

The configuration steps are described in the following section.


Configuring your Program Start Files

To access the configuration dialog, click the right mouse button on the desired start icon and select the Configure item from the context menu.

Any changes to the configuration will be saved to the start file when you select the OK button.

In the Connection dialog section, you can choose between local or remote program execution.

If you choose remote program execution, select the Server Name radio button. This enables the following fields:
Server Name
Please specify the hostname of the remote system where your program shall be executed. You can also specify an IP address (in the usual dot notation).
Please note: Unless you use DNS, the server name must have been defined in your hosts file.

Service
Please specify the service name that maps the eloqsd server on the remote system. The default service name is eloqsd. You can also specify a port number.
Please note: The service name must have been defined in your services file. The port number must be the same on the remote and the local system.

Login ID
This field is used to preset the login identifer. The ID will be used to login to the remote eloqsd server. This is normally NOT your UNIX or Windows NT login ID. Instead, it must have been configured in the remote eloqsd.user configuration file by the server administrator.
An entry in this field is just a preset, since you can always choose a different ID when you start the program.
Please note: If you leave this field empty, the name of the user who is currently logged-on to your local Windows system will be used instead.

Please refer to the installation documentation for further reference concerning the hosts and services files.

These are the fields in the Program dialog section:

Title
This is used in the title area of both the configuration and the login dialog (the login dialog will only show-up on remote program execution). By default, the name of the start file without the .eloq extension is taken.

Command
This is the command line which is passed to the local or remote eloqcore. Commandline arguments are separated by spaces. Arguments containing spaces can be enclosed in double quotes.

Environment
Here you can specify additional environment variables which will be passed to the local or remote eloqcore. Environment variable assignments must have the form of VAR=value and are separated by spaces. Values containing spaces can be enclosed in double quotes.

Start Directory
The Start Directory can be used to define an initial current directory when the eloqcore process is started. By default, eloqcore will inherit the current directory from eloqsd.

TTY Device
This does only affect a remote eloqcore running on an UNIX system. When set, this entry is used to assign stdin, stdout and stderr of the remote eloqcore process. It must be an absolute path to an existing file and probably makes only sense if this is a tty device file.

Output Window
When checked, an output window will open on program start. On remote execution, this will have no effect unless the Trace option will be additionally checked since remote programs will not write anything to the output window except trace messages.
However, on local execution the eloqcore's stdout and stderr will be connected to the output window so that you will see the usual eloqcore output, just as if you would start eloqcore in a command shell.
This is the only visible difference between local and remote program execution.

Trace
When checked, the program will send its trace messages to the output window (even if the Output Window option is not checked).
The Trace and Output Window options can help you to get rid of possible configuration problems. Under normal conditions, they should be unchecked since they heavily affect the program's performance.

To obtain the tty devicefile name to execute a character oriented Eloquence program, you could use one of the following:

When starting the remote eloqcore process, it should be connected to the specified device.

(Yes, I know - this is complicated. We are looking for a way to make this easier and even automatic.)


Starting your Program

To start your program, just double-click its start icon, just as if you would start any other Windows program.

When you double-click a start icon, Windows associates the .eloq extension of the start file with the EqStart utility. This way, Windows will execute EqStart and pass the name of the start file on the command line.

If the program is located on a remote system, the login dialog will appear where you must provide your password to the remote eloqsd. Optionally, you can change the login ID or even switch to the configuration dialog. Your program will be executed when you select the OK button.

If you wish to have different icons for your programs, you might consider to create shortcuts for your start files. Then select Properties from the shortcuts' context menu and change the icons. You could finally put these shortcuts on the desktop or in the Windows start menu.