6.9  Differences From the Tcl Embedding Interface

The remote Tcl interface is designed to be largely compatible with the embedded Tcl interface, so that a user GUI can be written that allows either interfaces to be used, while sharing most of the code in both ECLⁱPS^e and Tcl. An example of this is the Tkeclipse development tools.

Some remote specific code would need to be written. This includes code to handle the connection and disconnection of the Tcl and ECLⁱPS^e sides: there is no equivalent to ec_cleanup in the embedded Tcl interface, as the termination of the ECLⁱPS^e side should be handled in ECLⁱPS^e. In addition, the user may need to provide code to restrict the interaction within the Tcl/Tk GUI when control is transferred to ECLⁱPS^e. Aside from this, the rest of the code should be reusable, if the user exercises some care.

The supported compatible methods of communicating between Tcl and ECLⁱPS^e in the two interfaces is via the ec_rpc calls and the use of the I/O queues. The ec_rpc mechanism should behave the same in both interfaces. For the queues, there are some differences because the queues are in-memory queues in the embedded interface, but are socket channels in the remote interface. This leads to the following differences:

• Data will not appear on the other side until the queue is flushed on the side that is generating the output. To make code compatible, output queues should be always flushed.
• In general, reading data via a blocking socket requires the size of the data to be explicitly specified, except when I/O is done via the EXDR primitives, where size is implicitly specified. Only EXDR format is supported when data is sent from Tcl to ECLⁱPS^e. That is, a write handler for a Tcl write channel must write the data in EXDR format. For output from the ECLⁱPS^e side, the Tcl read handler would be supplied with the length of the output when it is invoked, and this information must be used if the Tcl read is not done via an EXDR primitive. However, in general it is strongly suggested that only EXDR formatted data should be sent via the queues in both direction.
• An I/O operation on the stream may block if there is no handler to consume/produce the data on the other side. If a handler is specified via the command argument, then a corresponding handler in the Tcl side will be invoked at the correct place when the ECLⁱPS^e side produces output or request input.
• The channel identifier is not of the form ec_queueX. To make code portable, the name of the channel should be obtained from the ECLⁱPS^e stream symbolic name or number via the commands ec_streamname_to_channel or ec_streamnum_to_channel.
• Asynchronous queues are bi-directional. In the embedding interface, there are no asynchronous queues, and ec_async_queue_create is aliased to ec_queue_create, and a uni-directional queue is created. Thus for compatibility, these queues should only be used in one direction.

In summary, to write code that will work for both the remote and embedded interfaces, the data should be sent using EXDR format, flush always performed, and a handler (command argument) provided. The Tcl channel identifier should not be constructed explicitly.

However, there may be cases where the two interfaces need to be distinguished. For example, if the Tcl side is to perform some operations on the file system for the ECLⁱPS^e side (e.g. selecting a file via a GUI), then with the remote interface, the two sides might not have access to the same file systems, and being able to distinguish whether the interface is remote or embedded allows the user to provide code to handle this.

To obtain information on which interface is being used, use the command:

ec_interface_type

returns remote for the remote interface, and embedded for the embedding interface.