Embedding into Visual Basic

The EclipseThread Project

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.

Enum EC_ERROR

Symbolic names for error conditions in the interface.

The EclipseClass class

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

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

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.