6.8  Example

---

% Tcl side will create the from-ECLiPSe queue gui_output, which will also
% automatically flush at the end of every line (and so transfer the data
% to the Tcl side)


disconnect_handler :-  % just terminate ECLiPSe execution
        writeln("Terminating...."),
        halt.


:-      remote_connect(localhost/5000, control, 
        set_event_handler(control, disconnect_handler/0)),
        % for simplicity, the host and port are fixed.
        % Name for control connection is also fixed.
        % when remote_connect returns, the gui_output queue will be
        % connected to Tcl side already.
        % eclipse side initialisation follows is just to set up the 
        % handler for disconnection....
        writeln(gui_output, "Connected...").

% this is for yielding control to Tcl. No need to specify Control explicitly
tclyield :-
        remote_yield(control).

Figure 6.1: Example use of interface: ECLiPSe code

---

---

# ECLIPSEDIR has to be set to where your ECLiPSe is at
lappend auto_path [file join $ECLIPSEDIR) lib_tcl]

package require remote_eclipse 

proc terminate {} {
    destroy .
}

# disable the terminate button when control is transferred to ECLiPSe
proc disable_button {} {
    .b configure -state disabled
}

# enable the terminate button when control is transferred back to Tcl
proc enable_button {} {
    .b configure -state normal
}

# the initialisation procedure, called when the remote side is attached. 
# this creates the gui_output from-ECLiPSe queue, and then uses an
# ec_rpc to cause the queue to flush at every newline
proc initialise {} {
 ec_queue_create gui_output fromec
 ec_rpc "set_stream_property(gui_output, flush, end_of_line)"
}

# this button initiates disconnection and terminates the Tcl program
pack [button .b -text "Terminate" -command "ec_disconnect; terminate"] 
# only start and end commands given; the others default to no commands
ec_running_set_commands disable_button enable_button

# disable button initially as ECLiPSe side has initial control
disable_button  

# the attachment to ECLiPSe includes the initialisation ec_init, which
# creates the gui_output queue. The connection is at the fixed port address
ec_remote_init localhost 5000 initialise
# Tcl side initially has control, hand it over to ECLiPSe...
ec_resume resume

Figure 6.2: Example use of interface: Tcl code

---

Figures 6.1 and 6.2 shows a simple example of the use of the interface. To try this program, the user should start an ECLⁱPS^e, compile the ECLⁱPS^e program. This will suspend on the remote_connect/3, waiting for the Tcl program to attach. The Tcl program should then be started on the same machine, and the attachment will be connected using the fixed host and port address. During the initialisation when attaching, a from-ECLⁱPS^e queue is created, which is set to flush at every newline. This is done by an ec_rpc goal after the queue is created. As no Tcl data consumer handler is specified, the default Tcl data consumer handler ec_stream_output_popup handles and display the data on the Tcl side on a pop-up window. The Tcl side GUI has just one button which allows the application to terminate. This button is disabled when ECLⁱPS^e side has control, and this is done by setting up the appropriate call-backs to disable and enable the button in ec_running_set_commands on the Tcl side.

On disconnection, which can be initiated either by pressing the button on the Tcl side, or by quitting from ECLⁱPS^e, the handlers for disconnection ensures that both the ECLⁱPS^e and Tcl program terminates.