• Application configuration file format
• Token resolving
• Resolving java properties or environment variables
• Application attributes
• Obsolete application attributes

The JDLG console window may provide a list of programs or applications. Each listed application specifies a (remote) program which may be started by double-clicking it in the application list.

Programs are started through a configured and running eloqsd server process, possibly located on a remote system, which in turn starts an eloqcore process using the command line specified in the application entry.

A JDLG application list is configured using an application configuration file. The configured applications are displayed in the order they appear in the configuration file, unless they are configured invisible.

The JDLG eloquence.config.sessions configuration property is used to specify an URL referring this configuration file.

Using the INI file format, each application starts with the application identifier in square brackets, followed by a list of application attributes. Lines beginning with the # hash character are ignored (comment lines).

The identifier must be unique. It is not visible in the JDLG application list but may be used with the System.start attribute to programmatically start an application.

For example:

# The first application
[APP1]
name     = Application 1
server   = 192.168.77.88
protocol = rdlg
command  = APP1,APPS

# The second application
[APP2]
name     = Application 2
server   = 192.168.77.88
protocol = rdlg
command  = APP2,APPS

Using the Java property syntax, each application attribute is prefixed with the unique application identifier, for example:

# The first application
APP1.name     = Application 1
APP1.server   = 192.168.77.88
APP1.protocol = rdlg
APP1.command  = APP1,APPS

# The second application
APP2.name     = Application 2
APP2.server   = 192.168.77.88
APP2.protocol = rdlg
APP2.command  = APP2,APPS

The application identifier is not case-sensitive.

An application configuration file must use either the INI file format or the Java property syntax. Specifying some of the listed applications in INI format and others using the Java property syntax is not supported.

$host

Evaluates to the IP address of the local host, viewed from the peer host's perspective (i.e., if the program is started on a remote host, the program can use this address to connect to the host where JDLG is executed).

Note: An IPv6 address is enclosed in square brackets.

$port

Evaluates to the TCP port number JDLG uses to listen for incoming DLG connections. By default this is 8011 but may be altered using the eloquence.config.dlg.port configuration property.

$login

Evaluates to the user name used to login to the eloqsd server. This is either the name entered in the login dialog or the name specified with the login application attribute.

Usage example:

# The first application
[APP1]
name        = Application 1
server      = 192.168.77.88
command     = -dlg $host:$port APP1,APPS
environment = HOME=/home/$login
environment = DRIVER=$host:$port

In this example, a program is started using the -dlg command line option. This causes eloqcore to open a DLG connection on the invoking JDLG.

In addition, two environment variables are defined: HOME with the value of the user's home directory, derived from the login name, and DRIVER specifying the JDLG connection properties, which for example would allow the program to start additional DLG programs that connect to the invoking JDLG.

Usage example:

# The first application
[APP1]
name        = Application 1
server      = 192.168.77.88
protocol    = rdlg
command     = APP1,APPS
environment = LOGNAME=$(LOGNAME)

In this example, the LOGNAME environment variable is passed to the program, mirroring the value of the LOGNAME environment variable on the system where JDLG is executed.

Equivalent on Windows, using the USERNAME environment variable:

environment = LOGNAME=$(USERNAME)

name

Specifies the application name to be displayed in the application list.

Using HTML is supported, for example:

name = <html><b>Application <font color=red>1</font></b>

Specifying the application name is required.

icon

May optionally be used to specify an URL referring to an icon image to be displayed at the left of the application name in the list.

If the icon image should be read from the local file system, a file: URL should be used. For details, please refer to the file: URL notes in the eloquence.config.url configuration section.

Specifying an application icon is optional.

Note on using Java Webstart (JNLP): JDLG version 1.7.0 or newer allows to specify a relative URL in a Java Webstart JNLP file, resolved relative to the JNLP codebase directory.

server

Defines the host name or IP address of the system where the program should be executed. This system must have an eloqsd server process configured and running.

Specifying the eloqsd server host name or IP address is required.

Note: An IPv6 address must be specified in square brackets.

serverport

May optionally be used to specify the TCP port number of the eloqsd server process on the system where the program should be executed.

Specifying an eloqsd port number is optional. If omitted, the default eloqsd port number 8100 is used.

login
password

May optionally be used to define the login credentials necessary to start the program through the (remote) eloqsd server process.

If omitted, a login dialog is displayed where the credentials must be entered. If the program was successfully started, these credentials may be cached for the next time the program is invoked, depending on the eloquence.config.sessionlogincache configuration property. In addition, the cached credentials are used with other applications having the same server and serverport configuration.

If both login and password are specified, no login dialog is shown, and the program is started immediately through the (remote) eloqsd server process.

command

Defines the command line used to start the program. This may include eloqcore command line options, for example:

command = -t -log /tmp/eq.log -dlg $host:$port APP1,APPS

Command line arguments are separated with spaces. If an argument contains space characters it should be enclosed in single or double quotes, for example:

command = -t -log "C:\Temporary Files\eq.log" ...

Please note that any file location specified on the command line is used by the eloqcore process that possibly runs on a remote system (i.e., not necessarily on the system where JDLG is executed).

It is possible to divide a command line into multiple command attribute entries, for example:

command = -t -log "C:\Temporary Files\eq.log"
command = -dlg $host:$port APP1,APPS

The command line used to start the program is formed by concatenating all command attribute values in the order they appear.

In the example above, this may be convenient if the trace option is only temporarily used. To deactivate the trace option it could then simply be commented out, such as:

#command = -t -log "C:\Temporary Files\eq.log"
command = -dlg $host:$port APP1,APPS

Specifying the command line is required.

startdir

May optionally be used to specify the program's current directory. This is set (on the remote system) before the program is started.

Specifying a start directory is optional. If omitted, the program's current directory is unknown (usually dependent on the invoking eloqsd server process).

environment

May optionally be used to define an environment variable to be passed to the program. An environment variable uses the NAME=VALUE syntax. Multiple environment attribute entries may be specified to define multiple environment variables.

For example:

environment = HOME=/home/$login
environment = DRIVER=$host:$port

protocol

Specifies the DLG protocol to be used. Possible values are:

• dlg

  This requires that the -dlg $host:$port command line option is used, or alternatively that the program issues a DLG SET ".driver" instruction to connect to the invoking JDLG, using the $host:$port connection properties.

  Using this protocol mode, JDLG just instructs the (remote) eloqsd server process to start the specified program. The program (or the eloqcore process using the -dlg command line option) then connects to the TCP port the invoking JDLG listens to. This establishes the DLG connection between JDLG and the program.

• rdlg

  If this option is used, it is not necessary to use the -dlg command line option or issue a DLG SET ".driver" instruction in the program.

  In rdlg protocol mode, JDLG connects to the (remote) eloqsd server process to start the specified program. The eloqcore process then takes the already established connection between JDLG and eloqsd and uses it as DLG connection.

  Other than the dlg protocol, the rdlg protocol works even if the system where JDLG is executed is behind a NAT firewall, i.e., when the program is started on a remote system beyond the local network: Only one single network connection is established, which originates from JDLG, which therefore can pass a NAT firewall. On the other hand, the dlg protocol uses a second DLG connection originating from the remote program, which therefore cannot pass a NAT firewall.

Specifying a protocol is optional. If omitted, the dlg protocol is used.

tls

If set to yes (or true or on or 1), secure TLS-encrypted communication is used to execute the program.

In addition, if the rdlg protocol is configured, the DLG communication between JDLG and the program is TLS-encrypted as well.

Notes:

• Requires JDLG version 2.0.0 or newer.
• Supported eloqsd server version: Eloquence B.08.30 or newer.

visible

If not specified or set to yes (or true or on or 1), the application is visible in the JDLG application list.

If set to no (or false or off or 0), the application entry is not displayed in the application list, i.e., the user cannot start the application but the System.start attribute may be used to programmatically start it.

autostart

If set to yes (or true or on or 1), the application is auto-started when JDLG is started.

If not specified or set to no (or false or off or 0), the application entry must be double-clicked to start the application.

parameter.N

In previous JDLG versions, a command line had to be defined using a single parameter.N attribute for each command line argument.

For example:

APP1.parameter.0 = -t
APP1.parameter.1 = -log
APP1.parameter.2 = /tmp/eq.log
APP1.parameter.3 = -dlg
APP1.parameter.4 = $host:$port
APP1.parameter.5 = APP1,APPS

This syntax is still available for compatibility reasons but has some disadvantages:

• The command line must be manually split into its components.
• Inserting or deleting an argument requires to renumber the remaining entries.

As a simplification, the new application configuration parser now allows to omit the parameter numbers, such as:

APP1.parameter = -t
APP1.parameter = -log
APP1.parameter = /tmp/eq.log
APP1.parameter = -dlg
APP1.parameter = $host:$port
APP1.parameter = APP1,APPS

The command line used to start the program is formed by concatenating all parameter attribute values in the order they appear.

Furthermore, when the parameter numbers are omitted it is possible to define more than one argument in a parameter definition, such as:

APP1.parameter = -t -log "C:\Temporary Files\eq.log"
APP1.parameter = -dlg $host:$port
APP1.parameter = APP1,APPS

As shown in the example above, single or double quotes should be used if an argument contains space characters.

Instead of using the parameter attribute, we recommend to use the new command attribute because it is more intuitive. The command attribute is actually a synonym for "parameter" and may be used the same way.

For example, this:

APP1.parameter = -dlg $host:$port
APP1.parameter = APP1,APPS

is equivalent to:

APP1.command = -dlg $host:$port
APP1.command = APP1,APPS

which in turn is equivalent to:

APP1.command = -dlg $host:$port APP1,APPS

environment.N

In previous JDLG versions, environment variables had to be defined using ordered environment.N attributes.

For example:

APP1.environment.0 = HOME=/home/$login
APP1.environment.1 = DRIVER=$host:$port
APP1.environment.2 = LOGNAME=$(LOGNAME)

This syntax is still available for compatibility reasons but has the disadvantage that inserting or deleting an environment variable requires to renumber the remaining entries.

As a simplification, the new application configuration parser now allows to omit the environment variable numbers, such as:

APP1.environment = HOME=/home/$login
APP1.environment = DRIVER=$host:$port
APP1.environment = LOGNAME=$(LOGNAME)

debugmode

The debugmode attribute is still supported for compatibility reasons but considered obsolete and should no longer be used. It activates the eloqsd debug protocol which does not have any benefit over using the standard dlg or rdlg protocols.