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 ECLⁱPS^e is resumed. If no format argument is given, the goal is taken to be a string in ECLⁱPS^e syntax. Note that (unlike with the C/C++ interface) it is not possible to retrieve any variable bindings from ECLⁱPS^e after successful execution of the goal. To pass information from ECLⁱPS^e to Tcl, use queue streams as described later on. Example:

 ec_post_goal {go("hello",27)}
 

If a format argument is provided, the ECLⁱPS^e 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 ECLⁱPS^e engine. This will lead to the execution of the corresponding event handler once the ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e queue stream using ECLⁱPS^e’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 ECLⁱPS^e stream (eclipse_stream_name can be a symbolic name or the ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e side flushes the queue. The Tcl-handler is expected to read and empty the queue. For writable queues, the handler is invoked when the ECLⁱPS^e 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 ECLⁱPS^e stream number appended as an extra argument.