Visual Basic Module

This documents the Amzi! Logic Server Visual Basic VB Module before .NET. VB.NET users are advised to use the .NET Class instead. This module provides a wrapper on the Logic Server DLL that presents the Logic Server in a manner more consistent with VB use. It includes:

A VB Module that encapsulates a Logic Server Engine,
Automatic mapping from C-strings to VB strings, and
Automatic error handling via a common routine.

The documentation is organized as follows:

Hello Prolog - Getting the Hello Prolog up and running from Visual Basic.

Overview - Overview of the Visual Basic cover functions for the Logic Server.

Using the Module - How to call the Logic Server from Visual Basic.

Implementing Extended Predicates - How to add Prolog extended predicates written in VB 5.0 or later.

Reference - Complete listing of all of the Visual Basic Logic Server functions.

Example - A more complete Visual Basic example illustrating a variety of Logic Server functions.

Hello Prolog

The hello.vbp Visual Basic Hello Prolog project is in the directory samples\vb\hello. It consists of a form, hello.frm (Hello VB Source Code), and a Logic Server Definitions file, amzi.bas.

The form has a single button to which all the code is attached. The code initializes the Prolog environment and calls the hello/2 predicate. It checks for error conditions, and if all is well prints in message boxes two status messages then the returned greeting from hello.pro.

To run, open the project in Visual Basic and select Run/Start. Press the 'Greet Me!' button, then press [Enter] or click the mouse on each of the three OK message boxes.

The Logic Server VB Module is implemented in the file amzi.bas in the top-level INCLUDE subdirectory. You use it by simply adding that file to to your project.

Overview

The Amzi! Logic Server VB Module is designed to give the VB programmer easy access to the services provided by the Logic Server DLL.

The Logic Server is an engine, similar to a database engine. When you include the Logic Server in your application, you are really including a Logic Server Engine. This engine knows how to access compiled and dynamic Prolog predicates in the Prolog logicbase. The API to the Logic Server provides functions that let you:

Initialize and close the engine, as well as load and run Prolog code,
Assert and retract logic terms dynamically,
Pose logical queries, retrieve all answers,
Use an intuitive string interface for communication,
Use detailed term manipulation functions for communication,
Process errors.

The Logic Server VB Module is distributed in source form in the file amzi.bas. You can build your own VB functions on top of it, or modify the cover functions themselves. (If you have ideas for improving the interface, please let us know and we'll include them in the VB Module in a later release.)

When you compare the functions in the VB Module, you'll find they extend, and in some cases, modify, the API functions as described in the manual. The differences are:

Function names end with an 'LS' as opposed to starting with 'ls' (the latter is reserved for direct DLL calls).
The functions do not take an engine ID as an argument, that is handled within the VB Module and with SetCurrentEngineLS.
All functions take Basic strings as arguments rather than C strings. The maximum string length returned by Prolog to Basic is controlled by calling SetMaxStrLenLS.
The functions do not return error codes. Errors are handled within the VB Module using the ErrorHandler routine. The operation of this routine is controlled by calling SetErrorHandlerLS. Depending upon the setting, this routine either: [1] signals error 31300 or [2] displays an error message, and optionally closes the Logic Server, then ends the program.
Functions that succeed or fail return the VB values 'true' and 'false'.
Many functions are now procedures because they do not have to return error codes.
There are numerous new functions with types indicated in their names, that augment the more general dynamic typing and pointer API calls. For example, lsGetArg takes as arguments the target type and a pointer to that type. The VB Module has functions such as GetStrArgLS, which simply returns the value of the string.

Philosophically, the VB Module preserves as much of the flavor of the pure API as possible, and augments it to provide a more VB-like interface.

Using the Module

To include the Logic Server in an application, simply add the Logic Server VB Module, amzi.bas, to your project.

To call the Logic Server, simply embed the API calls in the functions of your application. You will need to open and close the Logic Server as well. The following code opens the Logic Server, loads a compiled Prolog file, executes a simple query, and closes the Logic Server.

Dim s as String, term as long
Call InitLS("")
Call LoadLS ("hello")
tf = CallStrLS(term, "hello(vb, X)")
Call GetArgLS(term, 2, bSTR, s)
Call CloseLS

This code assumes the Prolog program, hello.pro, has a fact in it of the form hello(vb, prolog). It also assumes hello.pro has been compiled and linked to create hello.xpl, and that file is in the current directory or your PATH. See the Amzi! Prolog + Logic Server manual for more information on compiling and linking Prolog code.

Implementing Extended Predicates

Visual Basic 5.0 (and later), like C/C++, Java and Delphi, can be used to implement custom extended predicates to the Prolog language. These custom extensions give the Prolog code the ability to directly access anything Visual Basic can access.

The VB functions that implement extended predicates must be in their own module, declared as returning type long, and public. For example:

Public Function PMsgBox(ByVal EngineID As Long) As Long

The extended predicate function returns 1 for success (true) and 0 for failure (false).

The predicates are added one at a time by using the VB module function AddPredLS.

Note: Extended predicate definitions must always be added after calling InitLS and before calling LoadLS.

The sample in directory samples\vb\extpred includes a simple example of adding a msgbox predicate to Prolog.

Reference

This section contains the interface portion of the unit amzi.bas, which defines the Logic Server VB Module. It generally conforms to the ls procedures and functions in the LSAPI Reference. You can browse the source code for more details.

Logic Server Constants

Functions to Set Up Logic Server

Functions for Extended Predicates

Functions for Calling Prolog

Functions for Dynamic Clauses in Logicbase

Functions for String/Term Conversions

Functions for Making/Getting Prolog Types

Functions for Manipulating Structures

Functions for Manipulating Lists

Miscellaneous Functions

Logic Server Constants

These are the simple constants used by the Logic Server. They are used to map values to the API data types.

' For unicode systems, set unicode to True
#Const unicode = False

' Last Error Message and Code
Global ErrorLS As String
Global ErrLS As Integer

' The current engine id
Dim EngineID As Long

' The type of error handling to perform, 
' 0=message boxes, 1=generate errors
Dim ErrorMethod As Variant

' The maximum size of strings returned from Prolog
Dim MaxStrLen As Variant

' Prolog Types
Global Const pATOM = 0
Global Const pINT = 1
Global Const pSTR = 2
Global Const pFLOAT = 3
Global Const pSTRUCT = 4
Global Const pLIST = 5
Global Const pTERM = 6
Global Const pADDR = 7
Global Const pVAR = 8
Global Const pWSTR = 9
Global Const pWATOM = 10

' Basic Types
Global Const bATOM = 0
Global Const bSTR = 1
Global Const bINT = 2
Global Const bLONG = 3
Global Const bSHORT = 4
Global Const bFLOAT = 5
Global Const bDOUBLE = 6
Global Const bADDR = 7
Global Const bTERM = 8
Global Const bWSTR = 9
Global Const bWATOM = 10

Logic Server Set-Up

These functions provide the basic API services. They are used to initialize and close down the Prolog environment. The function, Main, runs the main/0 predicate of a load Prolog file.

Sub InitLS (ByVal INIFile As String)
Sub InitLSX ()
Sub AddLSX (ByVal LSXFile As String)
Sub AddPredLS(ByVal Predname As String, ByVal Arity As Integer, ByVal pfunc As Long)
Sub LoadLS (ByVal XPLFile As String)
Function MainLS () as Integer
Sub ResetLS ()
Sub CloseLS ()

They are based on the API functions lsInit, lsInitLSX, lsAddLSX, lsLoad, lsMain, lsReset, and lsClose.

The following functions control parameters within the VB Module. SetMaxStrLenLS sets the maximum length for all strings returned from Prolog to Basic .

SetErrorHandlerLS chooses whether error messages are displayed in message boxes ("MessageBox") or signalled via error #31300 ("ErrorCode"). When an error is signalled, ErrorLS is set to the error message and ErrLS is set to the Amzi! Logic Server error code. The routine that performs these operations is called ErrorHandle.

Sub SetMaxStrLenLS (ByVal num As Integer)
Sub SetErrorHandlerLS (ByVal ErrMethod As String)

Extended Predicates

When you write an extended predicate, you can directly manipulate the Prolog parameters to that function. These predicates provide that service. The Get family retrieves the nth parameter that was used in the call, and the Unify family unifies some computed result with the nth parameter.

The VB module contains a number of type-specific additions to the basic API. Functions such as GetLongParmLS and UnifyStrParmLS.

Sub GetParmLS(ByVal Param As Integer, ByVal BType As Integer, Ptr As Variant)
Function GetStrParmLS(ByVal Param As Integer) As String
Function GetIntParmLS(ByVal Param As Integer) As Integer
Function GetLongParmLS(ByVal Param As Integer) As Long
Function GetFloatParmLS(ByVal Param As Integer) As Single
Function GetParmTypeLS(ByVal Term As Long, ByVal ParmNum As Integer) As Integer
Function StrParmLenLS(ByVal ParmNum As Integer) As Integer
Function UnifyParmLS(ByVal Param As Integer, ByVal BType As Integer, ByVal Ptr As Variant) As Boolean
Function UnifyStrParmLS(ByVal Param As Integer, ByVal Str As String) As Boolean
Function UnifyAtomParmLS(ByVal Param As Integer, ByVal Str As String) As Boolean
Function UnifyIntParmLS(ByVal Param As Integer, ByVal IntVal As Integer) As Boolean
Function UnifyLongParmLS(ByVal Param As Integer, ByVal LongVal As Long) As Boolean
Function UnifyFloatParmLS(ByVal Param As Integer, ByVal FloatVal As Single) As Boolean

These functions are based on the API functions lsGetParm, lsGetParmType, lsUnifyParm, and lsStrParmLen.

Calling Prolog

These are the functions that actually call predicates in a Prolog logicbase/program. They query term can be represented as a string or a Prolog term. The first argument, a term, is always unified with the result of the call. The Redo function initiates backtracking, which reunifies the term with the next result.

ClearCall is only useful if you start a Redo loop and don't finish. It clears the stack.

Function ExecLS (TermPtr As Long) as Boolean
Function ExecStrLS (TermPtr As Long, ByVal StrPtr) as Boolean
Function CallLS (TermPtr As Long) as Boolean
Function CallStrLS (TermPtr As Long, ByVal StrPtr As String) as Boolean
Function RedoLS () as Boolean
Sub ClearCallLS ()
Function GetCurrentEngineLS () as Long
Sub SetCurrentEngineLS (NewEngID as Long)

These functions are based on the API functions lsExec, lsExecStr, lsCall, lsCallStr, lsRedo, and lsClearCall.

Get and SetCurrentEngineLS let you switch between multiple invocations of the Logic Server. To use them, call InitLS then use GetCurrentEngineLS to get the ID. Save that value. Call InitLS again and use GetCurrentEngineLS to get the new ID. Save that value as well. Then use SetCurrentEngineLS to switch between the active Prolog engines.

Dynamic Clauses in the Logicbase

These functions make it easy to assert and retract dynamic terms to and from Prolog's logicbase.

Sub AssertaLS (ByVal Term As Long)
Sub AssertzLS (ByVal Term As Long)
Function RetractLS (ByVal Term As Long) as Boolean
Sub AssertaStrLS (ByVal StrPtr As String)
Sub AssertzStrLS (ByVal StrPtr As String)
Function RetractStrLS (ByVal StrPtr As String) as Boolean

These functions are based on the API functions lsAsserta, lsAssertaStr, lsAssertz, lsAssertzStr, and lsRetract.

Converting Strings/Terms

These functions convert strings to terms and terms to strings. The 'Q' versions create quoted strings, when necessary for atoms and strings that require delimiter symbols. The 'Q' versions are necessary for those cases where you want to use the resulting string in another query.

Sub TermToStrLS (ByVal Term As Long, StrPtr As String, ByVal StrLen As Integer)
Sub TermToStrQLS (ByVal Term As Long, StrPtr As String, ByVal StrLen As Integer)
Sub StrToTermLS (TermPtr As Long, ByVal StrPtr As String)

These functions are based on the API functions lsTermToStr, lsTermToStrQ, and lsStrToTerm.

Making/Getting Prolog Types

These functions map Prolog types to and from VB types, and retrieve VB types from Prolog terms. The type-specific Get functions are VB additions.

Sub MakeAtomLS (TermPtr As Long, ByVal StrPtr As String)
Sub MakeStrLS (TermPtr As Long, ByVal StrPtr As String)
Sub MakeIntLS (TermPtr As Long, ByVal IntVal As Integer)
Sub MakeLongLS (TermPtr As Long, ByVal IntVal As Integer)
Sub MakeFloatLS (TermPtr As Long, ByVal FloatVal As Double)
Sub MakeAddrLS (TermPtr As Long, Ptr As Variant)
Function GetTermTypeLS (ByVal Term As Long) as Integer
Sub GetTermLS (ByVal Term As Long, ByVal BType As Integer, Ptr As Variant)
Function GetStrTermLS (ByVal Term As Long) As String
Function GetIntTermLS (ByVal Term As Long) As Integer
Function GetLongTermLS (ByVal Term As Long) As Long
Function GetFloatTermLS (ByVal Term As Long) As Double

These functions are based on the API functions lsMakeAtom, lsMakeStr, lsMakeInt, lsMakeFloat, lsMakeAddr, lsGetTermType, and lsGetTerm.

Manipulating Structures

These Prolog structure-manipulating functions let you create structures, and take apart terms that represent structures. This is especially useful for getting at various arguments in a query. For example, in the query 'sibling(mary, X)', the GetStrArgLS function can be used to get the second argument of this structure, after a CallStrLS has caused the variable to be bound.

Sub GetFALS (ByVal Term As Long, StrPtr As String, IntPtr As Integer)
Function GetFunctorLS (ByVal Term As Long) As String
Function GetArityLS (ByVal Term As Long) As Integer
Sub MakeFALS (Term As Long, ByVal Functor As String, ByVal Arity As Integer)
Function UnifyArgLS (TermPtr As Long, ByVal ArgNum As Integer, ByVal PType As Integer, ByVal Ptr As Variant) As Boolean
Function UnifyStrArgLS (TermPtr As Long, ByVal ArgNum As Integer, ByVal StrPtr As String) As Boolean
Function UnifyAtomArgLS (TermPtr As Long, ByVal ArgNum As Integer, ByVal StrPtr As String) As Boolean
Function UnifyIntArgLS (TermPtr As Long, ByVal ArgNum As Integer, ByVal IntVal As Integer) As Boolean
Function UnifyLongArgLS (TermPtr As Long, ByVal ArgNum As Integer, ByVal LongVal As Long) As Boolean
Function UnifyFloatArgLS (TermPtr As Long, ByVal ArgNum As Integer, ByVal FloatVal As Double) As Boolean
Sub GetArgLS (ByVal Term As Long, ByVal ArgNum As Integer, ByVal BType As Integer, Ptr As Variant)
Function GetStrArgLS (ByVal Term As Long, ByVal ArgNum As Integer) As String
Function GetIntArgLS (ByVal Term As Long, ByVal ArgNum As Integer) As Integer
Function GetLongArgLS (ByVal Term As Long, ByVal ArgNum As Integer) As Long
Function GetFloatArgLS (ByVal Term As Long, ByVal ArgNum As Integer) As Double
Function GetArgTypeLS (ByVal Term As Long, ByVal ArgNum As Integer) As Integer
Function StrArgLenLS (ByVal Term As Long, ByVal ArgNum As Integer) As Integer
Function UnifyLS (ByVal Term1 As Long, ByVal Term2 As Long) as Integer

These functions are based on the API functions lsGetFA, lsMakeFA, lsUnifyArg , lsGetArg, lsGetArgType, lsStrArgLen, and lsUnify.

Manipulating Lists

These list manipulation functions let you create Prolog lists, add items to lists, and retrieve items from lists. The GetHead family of functions can be used in loops to get all the items in a list. Note that, because GetHead doesn't invoke the Prolog engine or unification, it does not return a Boolean. It returns a normal function return code, in which 0 means success and anything else indicates the end of the list has been reached.

Sub MakeListLS (TermPtr As Long)
Sub PushListLS (TermPtr As Long, ByVal Term As Long)
Function GetHeadLS (TermPtr As Long, ByVal BType As Integer, Ptr As Variant) as Integer
Function GetStrHeadLS (TermPtr As Long, StrPtr As String) As Integer
Function GetIntHeadLS (TermPtr As Long, IntVal As Integer) As Integer
Function GetLongHeadLS (TermPtr As Long, LongVal As Long) As Integer
Function GetFloatHeadLS (TermPtr As Long, FloatVal As Double) As Integer
Function GetTailLS (TermPtr As Long) As Long

These functions are based on the API functions lsMakeList, lsPushList, lsGetHead and lsGetTail.

Miscellaneous Functions

These miscellaneous functions are used to change the Prolog streams, get the version number, and work with Prolog error codes.

Sub SetStreamLS (ByVal Stream As Integer, ByVal Handle As Integer)
Function GetStreamLS (ByVal Stream As Integer) As Integer
Function GetVersionLS () As String
Function GetExceptMsgLS () As String
Function GetExceptReadBufferLS () As String

These functions are based on the API functions lsSetStream, lsGetStream, lsGetVersion, lsGetExceptMsg, and lsGetExceptReadBuffer.

Examples

A number of examples can be found in the samples\vb subdirectory.