1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22% 23% $Id: embvb.tex,v 1.1 2006/09/23 01:49:04 snovello Exp $ 24% 25 26\chapter{Embedding into Visual Basic} 27\label{chapvb} 28 29This is a set of Visual Basic classes built around the scripting 30language interface of {\eclipse}. They are provided in source form 31in directory doc/examples/vb within the installation. 32The interface is similar in spirit to the {\eclipse} embedding 33interfaces for other languages. 34 35 36\section{The EclipseThread Project} 37\index{EclipseThread} 38This contains the classes which form the interface to eclipse. 39\begin{description} 40\item[class EclipseClass]\ \\ 41 An object of this class is a thread running eclipse code. Only 42 one such object may exist in a process. 43 44\item[class EclipseStreams]\ \\ 45 A collection of queue streams for communicating with {\eclipse}. 46 47\item[class EclipseStream]\ \\ 48 A stream of on which data can be sent to or from {\eclipse}. 49 50\end{description} 51 52\section{Public Enumerations} 53\begin{description} 54 55\item[Enum EC_Status]\ \\ 56 Symbolic names for the status values returned by goal execution. 57 58\item[Enum EclipseStreamMode]\ \\ 59 Symbolic names for the direction in which data flows within 60 an EclipseStream. 61 62\item[Enum EC_ERROR]\ \\ 63 Symbolic names for error conditions in the interface. 64 65\end{description} 66 67\section{The EclipseClass class} 68\index{EclipseClass} 69An object of this class is an entity running eclipse code. Only 70one such object may exist in a process. 71 72The class provides methods to execute goals and to access queue streams 73to communicate with the running goal. 74 75\begin{description} 76\item[Function Init() As Long]\ \\ 77 Initialise the {\eclipse} engine. This is required before any other 78 functions of this interface can be used. 79 80\item[Sub Send(EventName As String)]\ \\ 81 Post an event to the {\eclipse} engine. This will lead to the 82 execution of the corresponding event handler 83 See also \bipref{event/1}{../bips/kernel/event/event-1.html} and the User Manual 84 chapter on event handling for more information. The event name 85 is given as a string. Note that if {\eclipse} was not running, 86 the event stays in its queue until it is resumed. 87 88\item[Function Post(Goal As String) As EC_Status]\ \\ 89 Post a goal (constraint) that will be executed when \eclipse 90 is resumed. The goal is given as a string in {\eclipse} syntax. 91 92\item[Function ResumeAsync() As EC_Status]\ \\ 93 Resume execution of the {\eclipse} engine: All posted goals will 94 be executed. The return value will be 'Success' if the goals succeed 95 'Fail' is returned if the goals fail, and 'Yield' if control was 96 yielded because of a 97 \bipref{yield/2}{../bips/kernel/externals/yield-2.html} 98 predicate call in the {\eclipse} code. 99 No parameters can be passed. 100 101 The function returns when the posted goals have finished executing. 102 Since a separate thread is actually executing the goals though, 103 events may be received by the Visual Basic program during the 104 execution of this function. It is an error to call this function 105 recursively while handling one of these events. 106 107\item[Function HandleEvents() As EC_Status]\ \\ 108 Resume execution of the {\eclipse} engine, but do not let it execute 109 any posted goals. Only {\eclipse} events will be handled. Sources 110 of such events are the Post() Function or writing to an event-raising 111 {\eclipse} queue stream. 112 The function returns when the events have all been handled by 113 {\eclipse} and the return value is 'Success'. 114 It is an error to call this function while a ResumeAsync() 115 is still active. 116 117\item[Sub RPC(Goal As Variant, Response As Variant)]\ \\ 118 {\eclipse} Remote Predicate Call. 119 An {\eclipse} goal is constructed from {\it Goal} 120 according to the conversion rules explained in chapter \ref{chapexdr}. 121 Goal is called in the default module. The Goal should be 122 simple in the sense that it can only succeed, fail or throw. 123 It must not call 124 \bipref{yield/2}{../bips/kernel/externals/yield-2.html}. Any 125 choicepoints the goal leaves will be discarded. On success, 126 the (possibly more instantiated) Goal is returned as Response, 127 otherwise "fail" or "throw" respectively. 128 129 Unlike {\bf ResumeAsync}, calls to {\bf RPC} can be nested 130 and can be used from within VB Stream event handlers. 131 132\item[Property Let EclipseDir(Dir As String)]\ \\ 133 The directory where {\eclipse} is installed. 134 See Chapter \ref{chapecoptions}. 135 136\item[Property Let Module(Mod As String)]\ \\ 137 The default module for calling goals. 138 See Chapter \ref{chapecoptions}. 139 140\item[Property Let GlobalSize(Size As Long)]\ \\ 141 The maximum size of the {\eclipse} global/trail stack in bytes. 142 See Chapter \ref{chapecoptions}. 143 144\item[Property Let LocalSize(Size As Long)]\ \\ 145 The maximum size of the {\eclipse} local/control stack in bytes. 146 See Chapter \ref{chapecoptions}. 147 148\item[Property Let SharedSize(Size As Long)]\ \\ 149 The maximum size of the {\eclipse} shared heap. 150 See Chapter \ref{chapecoptions}. 151 152\item[Property Let PrivateSize(Size As Long)]\ \\ 153 The maximum size of the {\eclipse} private heap. 154 See Chapter \ref{chapecoptions}. 155 156\item[Property Get Streams]\ \\ 157 The EclipseStreams collection associated with this EclipseClass. 158\end{description} 159 160 161\section{The EclipseStreams Collection Class} 162\index{EclipseStreams} 163This is a collection of EclipseStream objects. The keys to this collection 164are the symbolic name of {\eclipse} streams. Initially it 165will contain the 'input' 'output' and 'error' streams. 166 167\begin{description} 168\item[Function Add(Key As String, Mode As EclipseStreamMode) As EclipseStream]\ \\ 169 Create a new EclipseStream. 'Key' must be the symbolic name of an 170 existing {\eclipse} queue stream. These are created using the 171 \bipref{open/3}{../bips/kernel/iostream/open-3.html} or 172 \bipref{open/4}{../bips/kernel/iostream/open-4.html} 173 built-in. If 'Mode' is 'FromEclipse' the {\eclipse} stream must 174 have been opened in 'write' mode. If it is 'ToEclipse' the \eclipse 175 stream must have been opened in read mode. 176 177\item[Property Get Item(vntIndexKey As Variant) As EclipseStream]\ \\ 178 Used to retrieve streams from the collection. 'vntIndexKey' can 179 be either the symbolic steam name or an integer index into the 180 collection. 181 182\item[Property Get Count() As Long]\ \\ 183 The number of items in the collection 184 185\item[Sub Remove(vntIndexKey As Variant)]\ \\ 186 Remove an EclipseStream from the collection. (This does not 187 close the corresponding {\eclipse} stream though). 188 189\end{description} 190 191 192\section{The EclipseStream Class} 193\index{EclipseStream} 194This class allows exchanging data with an embedded {\eclipse} via 195queue streams created by the {\eclipse} code. 196\begin{description} 197\item[Event Flush]\ \\ 198 Raised whenever the {\eclipse} program flushes this stream. 199 200\item[Property Get Key() As String]\ \\ 201 The symbolic name of this stream 202 203\item[Property Get Mode() As EclipseStreamMode]\ \\ 204 The direction in which data is sent over this EclipseStream 205 206\item[Property Get/Let Prompt() As String]\ \\ 207 A prompt string. This appears in an input box that pops up 208 when the {\eclipse} program attempts to read from a queue 209 stream if no data is available. 210 211\item[Sub StreamWrite(Data As String)]\ \\ 212 Send 'Data' over this stream. 213 214\item[Function Read(l As Long) As String]\ \\ 215 Receives at most 'l' characters from the EclipseStream. 216 No flushing is necessary. 217 218\item[Function NewData() As String]\ \\ 219 Receives all available characters from the EclipseStream 220 that has been written on the stream since the last flush. 221 222\item[Sub WriteExdr(Data As Variant)]\ \\ 223 Writes the given data structure onto the stream in EXDR-encoded form. 224 See chapter \ref{chapexdr} for details about EXDR format. 225 226\item[Sub ReadExdr(Data As Variant)]\ \\ 227 Reads one EXDR-encoded term from the stream and returns its 228 VB-representation in Data. 229 See chapter \ref{chapexdr} for details about EXDR format. 230\end{description} 231 232