The Eloquence Development Environment

Program Development

The new Eloquence development Environment makes developing with Eloquence even easier and more convenient. Major benefits are:

You can have any number of text or program files active at one time, resticted only by memory limitations.
The new Browse Toolwindow provides an entry for each editor window. For Eloquence programs it also provides the list of active segments. Double clicking on an entry brings the associated window on top and positions the cursor.
Splittable editor windows and additional views make it convinient to operate at several places of the same document at one time without having to scroll around.
Language sensitive editor.
Integrated context sensitive online help.
Includes its own client/server file sharing capabilities. This will make you independend of the availability of specific network file systems (NFS/SMB) and overcomes network topology and filesystem limitations.
Consistent authorization scheme in a heterogeneous environment
Supports the HP Roman-8 and ISO 8859-1 character sets.
The editor is sensitive about line termination sequences.
Integrated debugger

The Browser

All files loaded into an editor window have a corresponding entry in the Browse Toolwindow - it's symbolized by a folder symbol. When an editor window holds a Eloquence Program, you can open the folder (this is symbolized by the leading + symbol) and the list of program segments becomes visible.

Double clicking on the folder symbol will bring the associated client window on top. Double clicking on a segment name will additionally position the cursor at the beginning of that section. (This will even work if a program has been edited). Recompiling a program will re-create its section list.

This is a real live saver if you ever had to jump between different segments (in even different files) while editing a program.

Compiling a program

When a program is compiled, all lines are checked for syntax errors (which will be displayed in the Output Toolwindow) and translated to the internal Eloquence code. Additionally, the segment list in the Browser Toolwindow is updated. If you double click on the error message in the Output Window, the cursor is automatically positioned on the offensive line.

Please Note: The compiler will reject to compile a program containing references to line numbers. Since the Development Environment does not deal with line numbers those programs would become useless.

Storing and loading program files

When you store a program file, it is compiled automatically. Only programs with no syntax erros can be stored (as a binary program file). To store a program file as text, simply change the file type in the save dialog. (Please take care that the file extension is something different than .PROG).

Loading a text file and converting it into a program document is easy. Just load the text file, open the Document Properties dialog and change the file type.

Debugging

The Eloquence Development Environment contains a simple but powerful debugger you are probably already familiar with: The editor.
When debugging a program, an arrow will indicate the current line in the source window, which is about to be executed. When the source code is not already present in a window, it will be requested from the eloqsd or the eloqcore process as a last resort.

Eloquence makes it possible to debug your program in different environments:

Execute your program on your local system
Execute your program on a remote system

When initiating a local debugging session, Eloquence starts a local eloqcore process which is controlled and monitored by the Develop environment.

When initiating a remote debugging session, the Eloquence contacts the eloqsd server at the remote system. The remote eloqsd process will check your authorization, start the debug session and connect it to the Development Environment.

You normally don't want to execute the program in the editor window directly. It is usually part of a larger project and not self contained. Instead you create a Debug configuration which tells Eloquence how to invoke the start program of your project.

The system where the debug process should be executed on
The arguments to pass to eloqcore
The environment to provide to your program.

Please Note: You can only have one debugging session active at a time.
Starting a debug session requires configuration of the Debug settings in the Application Properties.

Initiating a debug session

The debug process is started by selecting the RUN/CONTINUE menu item from the Program menu pane, the associated accelerator key F5 or the button in the Program Toolbar window.

This way, the debug process will be executed. If any breakpoints are defined, it will be halted at the first breakpoint. If not, it will run until finished.

Alternatively, the debug process can be started by selecting one of the Step commands (Step into, Step over, Step out). In this case, execution of the debug process will be halted before executing the first line.

The "Run to cursor" command can also be used to start the debug process. In this case, a temporary breakpoint is set at the cursor location and then the debug process will be executed.

Whenever the debug process is suspended, the source file containing the next line to be executed will be automatically be loaded, unless it's already opened in a window. The current line is marked by a yellow arrow.

Stepping through a program

After the debug process has been suspended, you can continue it by one of the following actions:

Continue. This will continue execution until the program exists or is halted (e.g. if a breakpoint is reached).
Step into. This will continue the execution for one line. (This is similar to the former Halt key.)
Step over. This will continue the execution until the current line has been finished. (This is similar to the former Advanced Step.) Please note, that recursive calls are taken care of. Execution will not be suspended in a different recursion level.
Step out. This will continue execution until the end of the current segment has been reached.
Run to cursor. This will set a temporary breakpoint at the cursor location and continue execution until the program exits or is halted. If another breakpoint is reached before the cursor line is executed, the debug process will stop at that breakpoint and remove the temporary breakpoint from the cursor location.

You can use the Halt operation to suspend the execution of a running debug process after the end of the current line. When a Halt operation is pending, the corresonding button is displayed deperessed as a visible acknowledgement.

Breakpoints

A breakpoint causes the debug process to suspend execution, before the marked program line is executed. Breakpoints can be defined in any program file, at any time. They are even remembered, when you exit the Development Environment.

Breakpoints are associated with the relative line in a program segment (when the file is loaded or stored), so they may be garbaged, when you edit a particular program file outside the Development Environment. You cannot set a breakpoint unless the program has been previously compiled.

A breakpoint becomes submitted to the debug process, when the program execution has been suspended. If you add or delete a breakpoint, while the debug process is currently executing, you need to suspend execution (for example, by selecting Halt) to activate the changes.

The Breakpoints dialog (available in the Program menu pane or by pressing the accelerator key Shift-F9) can be used to review or remove breakpints without having the associated file in an editor window. When double-clicking the first column, the corresponding file is loaded automatically and the cursor is positioned in the corresponding line.

The Output Toolwindow

By checking the Trace menu item in the Program menu pane, the Trace mode is enabled, and each variable modification causes a trace message sent to the Debug area of the Output Window.

The Call Stack Toolwindow

The Call Stack Toolwindow visualizes the call chain, how the current line has been invoked. Double-clicking an entry positions the cursor on the corresponding source line.

The Variables Toolwindow

The Variables Toolwindow contains the active variables for this segment along with the current value. Array variables do not display the value of individual elements by default. They are marked by a leading + sign. To display array elements, you can expand the array by clicking on the leading + sign. Please note, that values are truncated at a certain length. This is indicated by a trailing "...". In order to change a variable value, just double-click it, type the new variable value in the edit box and press return.

Debugging a character oriented program

You can use the Eloquence Development Environement to debug a character oriented program (a program using FORMs and softkeys). This requires a UNIX server as character oriented programs are only supported in a UNIX environment.

In addition to a server, you need either a terminal or a terminal emulator (such as Reflection). After the debug process is started, the input and output is redirected to the terminal.

In order to debug a character oriented program, you must configure the TTY device in the Application Properties accordingly. To obtain the tty devicefile name, you should follow the procedure below:

If you use a terminal device connected to a serial device, simply enter the tty device file (for example /dev/tty0p1). You should not run a getty on this port and you must configure it properly before using it (setting baud rate, data format etc.).
- or -
1. Login to your server system
2. Obtain the tty device using the tty command. The device file is typically similar to /dev/ttyp4.
3. Disable the shell input (for example by executing a sleep 10000)
4. Enter the device file in the configuration.

Please be aware, that you must define a TERM environment variable, describing the type of terminal used. After that, start the debug process as usual.

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