Embedding into Visual Basic

This is a set of Visual Basic classes built around the scripting language interface of ECLiPSe. They are provided in source form in directory doc/examples/vb within the installation. The interface is similar in spirit to the ECLiPSe embedding interfaces for other languages.

The EclipseThread Project

This contains the classes which form the interface to eclipse.
class EclipseClass
An object of this class is a thread running eclipse code. Only one such object may exist in a process.
class EclipseStreams
A collection of queue streams for communicating with ECLiPSe.
class EclipseStream
A stream of on which data can be sent to or from ECLiPSe.

Public Enumerations

Enum EC_Status
Symbolic names for the status values returned by goal execution.
Enum EclipseStreamMode
Symbolic names for the direction in which data flows within an EclipseStream.
Symbolic names for error conditions in the interface.

The EclipseClass class

An object of this class is an entity running eclipse code. Only one such object may exist in a process. The class provides methods to execute goals and to access queue streams to communicate with the running goal.
Function Init() As Long
Initialise the ECLiPSe engine. This is required before any other functions of this interface can be used.
Sub Send(EventName As String)
Post an event to the ECLiPSe engine. This will lead to the execution of the corresponding event handler See also event/1 and the User Manual chapter on event handling for more information. The event name is given as a string. Note that if ECLiPSe was not running, the event stays in its queue until it is resumed.
Function Post(Goal As String) As EC_Status
Post a goal (constraint) that will be executed whenECLiPSe is resumed. The goal is given as a string in ECLiPSe syntax.
Function ResumeAsync() As EC_Status
Resume execution of the ECLiPSe engine: All posted goals will be executed. The return value will be 'Success' if the goals succeed 'Fail' is returned if the goals fail, and 'Yield' if control was yielded because of a yield/2 predicate call in the ECLiPSe code. No parameters can be passed. The function returns when the posted goals have finished executing. Since a separate thread is actually executing the goals though, events may be received by the Visual Basic program during the execution of this function. It is an error to call this function recursively while handling one of these events.
Function HandleEvents() As EC_Status
Resume execution of the ECLiPSe engine, but do not let it execute any posted goals. Only ECLiPSe events will be handled. Sources of such events are the Post() Function or writing to an event-raising ECLiPSe queue stream. The function returns when the events have all been handled by ECLiPSe and the return value is 'Success'. It is an error to call this function while a ResumeAsync() is still active.
Sub RPC(Goal As Variant, Response As Variant)
ECLiPSe Remote Predicate Call. An ECLiPSe goal is constructed from Goal according to the conversion rules explained in chapter #. Goal is called in the default module. The Goal should be simple in the sense that it can only succeed, fail or throw. It must not call yield/2. Any choicepoints the goal leaves will be discarded. On success, the (possibly more instantiated) Goal is returned as Response, otherwise "fail" or "throw" respectively. Unlike ResumeAsync, calls to RPC can be nested and can be used from within VB Stream event handlers.
Property Let EclipseDir(Dir As String)
The directory where ECLiPSe is installed. See Chapter #.
Property Let Module(Mod As String)
The default module for calling goals. See Chapter #.
Property Let GlobalSize(Size As Long)
The maximum size of the ECLiPSe global/trail stack in bytes. See Chapter #.
Property Let LocalSize(Size As Long)
The maximum size of the ECLiPSe local/control stack in bytes. See Chapter #.
Property Let SharedSize(Size As Long)
The maximum size of the ECLiPSe shared heap. See Chapter #.
Property Let PrivateSize(Size As Long)
The maximum size of the ECLiPSe private heap. See Chapter #.
Property Get Streams
The EclipseStreams collection associated with this EclipseClass.

The EclipseStreams Collection Class

This is a collection of EclipseStream objects. The keys to this collection are the symbolic name of ECLiPSe streams. Initially it will contain the 'input' 'output' and 'error' streams.
Function Add(Key As String, Mode As EclipseStreamMode) As EclipseStream
Create a new EclipseStream. 'Key' must be the symbolic name of an existing ECLiPSe queue stream. These are created using the open/3 or open/4 built-in. If 'Mode' is 'FromEclipse' the ECLiPSe stream must have been opened in 'write' mode. If it is 'ToEclipse' theECLiPSe stream must have been opened in read mode.
Property Get Item(vntIndexKey As Variant) As EclipseStream
Used to retrieve streams from the collection. 'vntIndexKey' can be either the symbolic steam name or an integer index into the collection.
Property Get Count() As Long
The number of items in the collection
Sub Remove(vntIndexKey As Variant)
Remove an EclipseStream from the collection. (This does not close the corresponding ECLiPSe stream though).

The EclipseStream Class

This class allows exchanging data with an embedded ECLiPSe via queue streams created by the ECLiPSe code.
Event Flush
Raised whenever the ECLiPSe program flushes this stream.
Property Get Key() As String
The symbolic name of this stream
Property Get Mode() As EclipseStreamMode
The direction in which data is sent over this EclipseStream
Property Get/Let Prompt() As String
A prompt string. This appears in an input box that pops up when the ECLiPSe program attempts to read from a queue stream if no data is available.
Sub StreamWrite(Data As String)
Send 'Data' over this stream.
Function Read(l As Long) As String
Receives at most 'l' characters from the EclipseStream. No flushing is necessary.
Function NewData() As String
Receives all available characters from the EclipseStream that has been written on the stream since the last flush.
Sub WriteExdr(Data As Variant)
Writes the given data structure onto the stream in EXDR-encoded form. See chapter # for details about EXDR format.
Sub ReadExdr(Data As Variant)
Reads one EXDR-encoded term from the stream and returns its VB-representation in Data. See chapter # for details about EXDR format.