next up previous index
Next: Attaching Handlers to Queues Up: Embedding into Tcl/Tk Previous: Passing Goals and Control   Index

Subsections

Communication via Queues

The most flexible way of passing data between ECLiPSe and Tcl is via the I/O facilities of the two languages, ie. via ECLiPSe queue streams which can be connected to Tcl channels.

To create a communication channel between ECLiPSe and Tcl, first create an ECLiPSe queue stream using ECLiPSe's open/3 or open/4 predicate, then connect that stream to a Tcl channel by invoking the ec_queue_connect command from within Tcl code.

ec_queue_connect eclipse_stream_name mode ?command?

Creates a Tcl channel and connects it to the given ECLiPSe stream (eclipse_stream_name can be a symbolic name or the ECLiPSe stream number). The mode argument is either r or w, indicating a read or write channel. The procedure returns a channel identifier for use in commands like puts, read, ec_read_exdr, ec_write_exdr or close. The channel identifier is of the form ec_queueX, where X is the ECLiPSe stream number of the queue. This identifier can either be stored in a variable or reconstructed using the Tcl expression
        ec_queue[ec_stream_nr eclipse_stream_name]
If a command argument is provided, this command is set as the handler to be called when data needs to be flushed or read from the channel (see ec_set_queue_handler).

ec_stream_nr eclipse_stream_name

This command returns the ECLiPSe stream number given a symbolic stream name (this is the same operation that the ECLiPSe built-in get_stream/2 performs).

ec_set_queue_handler eclipse_stream_name mode command

Sets command as the Tcl-handler to be called when the specified queue needs to be serviced from the Tcl side. Unlike ec_queue_connect, this command does not create a Tcl channel. The mode argument is either r or w, indicating whether the Tcl end of the queue is readable or writable. For readable queues, the handler is invoked when the ECLiPSe side flushes the queue. The Tcl-handler is expected to read and empty the queue. For writable queues, the handler is invoked when the ECLiPSe side reads from the empty queue. The Tcl-handler is expected to write data into the queue. In any case, the handler command will be invoked with the ECLiPSe stream number appended as an extra argument.

From ECLiPSe to Tcl

To create a queue from ECLiPSe to Tcl, first create a write-queue in ECLiPSe, then use the queue name to open this queue as a Tcl channel in read mode, e.g.
ECLiPSe:        open(queue(""), write, my_out_queue).
Tcl:            set my_in_channel [ec_queue_connect my_out_queue r]
Now the queue can be used, e.g. by writing into it with ECLiPSe's write/2 builtin, and reading using Tcl's read command:
ECLiPSe:        write(my_out_queue, hello).
Tcl:            set result [read $my_in_channel 5]
The disadvantage of using these low-level primitives is that for reading one must know exactly how many bytes to read. It is therefore recommended to use the EXDR (ECLiPSe external data representation, see section 5.6) format for communication. This allows to send and receive structured and typed data. The primitives to do that are write_exdr/2 on the ECLiPSe side and ec_read_exdr (section 5.6) on the Tcl side:
ECLiPSe:        write_exdr(my_out_queue, foo(bar,3)).
Tcl:            set result [ec_read_exdr $my_in_channel]
In the example, the Tcl result will be the list {foo bar 3}. For details about the mapping see section 5.6.

From Tcl to ECLiPSe

To create a queue from Tcl to ECLiPSe, first create a read-queue in ECLiPSe, then use the queue name to open this queue as a Tcl channel in write mode:
ECLiPSe:        open(queue(""), read, my_in_queue)
Tcl:            set my_out_channel [ec_queue_connect my_in_queue w]
Now the queue can be used, e.g. by writing into it with Tcl's puts command and by reading using ECLiPSe's read_string/4 builtin:
Tcl:            puts $my_out_channel hello
ECLiPSe:        read_string(my_in_queue, "", 5, Result).
The disadvantage of using these low-level primitives is that for reading one must know exactly how many bytes to read, or define a delimiter character. It is therefore recommended to use the EXDR (ECLiPSe external data representation, see section 5.6) format for communication. This allows to send and receive structured and typed data. The primitives to do that are ec_read_exdr (section 5.6) on the Tcl side and read_exdr/2 on the ECLiPSe side:
Tcl:            ec_write_exdr $my_out_channel {foo bar 3} (SI)
ECLiPSe:        read_exdr(my_in_queue, Result).
In the example, the ECLiPSe result will be the term foo("bar",3). For details about the mapping see section 5.6.


next up previous index
Next: Attaching Handlers to Queues Up: Embedding into Tcl/Tk Previous: Passing Goals and Control   Index

1999-08-06