Incompatible and obsolete commands

## 5.9 Incompatible and obsolete commands

Here is a list of commands in the embedding interface that are retained for compatibility purposes with previous versions. They have no equivalent in the Tcl remote interface, and their use for new code is discouraged.

ec_post_goal goal ?format?
  post a goal that will be executed when ECLiPSe is resumed. If no format argument is given, the goal is taken to be a string in ECLiPSe syntax. Note that (unlike with the C/C++ interface) it is not possible to retrieve any variable bindings from ECLiPSe after successful execution of the goal. To pass information from ECLiPSe to Tcl, use queue streams as described later on. Example:

       ec_post_goal {go("hello",27)}

  If a format argument is provided, the ECLiPSe goal is constructed from goal data and format, according to the conversion rules explained in section 5.8. Example:

       ec_post_goal {go hello 27} (SI)

  Posting several goals is the same as posting the conjunction of these goals. Note that simple, deterministic goals can be executed independently of the posted goals using the ec_rpc command (see below).
ec_post_event event_name
  Post an event to the ECLiPSe engine. This will lead to the execution of the corresponding event handler once the ECLiPSe execution is resumed. See also event/1 and the User Manual chapter on event handling for more information. This mechanism is mainly recommended for asynchronous posting of events, e.g. from within signal handlers or to abort execution. Otherwise it is more convenient to raise an event by writing into an event-raising queue stream (see section 5.6.2).
ec_handle_events
  resume execution of the ECLiPSe engine for the purpose of event handling only. All events that have been posted via ec_post_event or raised by writing into event-raising queues will be handled (in an unspecified order). The return value will always be "success", except when an asynchronous ECLiPSe thread is still running, in which case the return value is "running" and it is undefined whether the events may have been handled by that thread or not.
  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_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.