.NET Wrapper Class

.NET is an emerging, machine-independent platform from Microsoft. It is similar in architecture to Amzi! Prolog and .NET in that it has its own virtual machine called the Common Language Runtime (CLR). The primary interface for the CLR is a managed wrapper class for amzi.dll, which is described here. As .NET continues to evolve, our interface(s) will meet Amzi!'s customer's needs. Please tell use about your needs by e-mailing us at www.amzi.com.

The .NET Class encapsulates the Amzi! Logic Server for use by .NET applications and applets. It includes:

A .NET Class Package the encapsulates a Logic Server Engine
Methods that correspond to the Logic Server API Functions
Use of .NET's exception handling for API errors, and
.NET-like method interfaces.

In addition, you can extend the .NET Class to allow Prolog to call methods in your .NET code.

The sections of this document are:

Where to Learn About .NET - Where to get .NET software, tutorials and information.
Installation - How to install the Logic Server as a .NET class.
Pets Callback Samples- Getting the Pets expert system with an extended predicate up and running from .NET.
Overview - Conceptual overview of the .NET version of the Logic Server.
Using the .NET Class - How to use the Logic Server from .NET.
Implementing Extended Predicates - How to add Prolog extended predicates written in .NET.
Examples

Where to Learn About .NET

Documentation about COM is plentiful. Microsoft's documentation can be found at msdn.microsoft.com.

Installation

To use the .NET Class, you must make the Amzi! dynamic library and .NET library files accessible to the calling environment: The Amzi! Logic Server, amzi.dll (any lsx's and amzi.cfg), and the Amzi! .NET interface, amzinet.dll, must be accessible to the calling environment. These files are in the amzi\bin directory. To do this:

Select 'Add Reference' to add amzinet.dll as a reference in your project.
Copy amzi.dll, amzi.cfg (optional) and any lsx files (optional) to your binary directory.
(If you are running the original 1.0 version of the .NET Framework, you may need to copy these files to your Windows\System32 or WINNT\System32 directory instead).

Pets Callback Samples

In amzi/samples/dotnet are various samples for using the Amzi! Logic Server from .NET. They are organized according to Visual Studio language, C++, C# and Visual Basic. The Pets Callback samples demonstrate the basic features of the .NET class, including calling extended predicates.

Overview

The .NET implementation of the Amzi! Logic Server adapts the LSAPI to the style of managed .NET wrapper classes. It implements the full LSAPI using managed types as return values and exceptions. All the methods are capable of throwing the managed LSException class.

All the Logic Server methods are documented in the LSAPI Reference with these changes:

GetType() is called GetExceptType() in LSException
The enumerated values have been renamed:
- pTYPE is pLSTYPE
- dTYPE is dLSTYPE
- exTYPE is exLSTYPE

Object Oriented

The Amzi! Logic Server is implemented as an object oriented program, so that each Logic Server is an object and the Logic Server API functions are methods of that object. It is natural, therefor, to provide object oriented interfaces to the Logic Server for object oriented languages such as .NET. (Amzi! is also available in a C++, Java and Delphi class.) The Logic Server class can then be used as any other class in an object oriented application, supporting, for example, subclassing, embedding and multiple instances. This makes for an elegant approach to encapsulating Prolog services in applications.

Representing Prolog Terms

A fundamental data type for the Prolog interface is a Prolog term. Internally, a Prolog term is a pointer, but, since that pointer is not manipulated by the application, it can be stored as an integer. For .NET, it is stored in a long integer.

Issuing Prolog Queries

The base LSAPI functions that issue Prolog queries return TRUE or FALSE, corresponding to Prolog success or failure, and use a pointer to the calling Prolog term to pass back the term resulting from the query. For example a function issuing the query 'available(com, Port)' will return true or false plus the term representing the query with the Port variable unified with the result.

For .NET, the query LSAPI functions (Exec, ExecStr, Call, CallStr) return the term (a long) directly, instead of a true false. If the query fails, that is indicated by a zero (0) value returned. (Errors are indicated by LSExceptions.)

String Conversion

The .NET Class uses multi-byte characters throughout.

Exceptions

Instead of returning error codes, all the LogicServer methods use .NET's exception mechanism. The LSException class is thrown when an error occurs. LSException contains a number of methods for learning details about the exceptions.

Multi-Threaded

.NET allows you to start multiple threads in the same program, and Amzi! supports multiple simultaneous Prolog engines. So each instance of the .NET Logic Server class will contain its own Prolog runtime environment.

Using the .NET Class

The .NET class is implemented in the 'amzinet' namespace and consists of the 'LogicServer' class and the 'LSException' class. To use the classes, in general, you need to add a reference to the amznet.dll in your project.

From there you can either instantiate a new LogicServer class and invoke its methods, or you can define a new class that extends the LogicServer class adding new methods and variables.

For Visual Basic, the LSException is wrapped inside an Exception and must be retrieved. See the pets_callback sample for details.

Implementing Extended Predicates

.NET, like C/C++, Delphi and VB 5.0 (and later), 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 .NET can access.

The .NET methods that implement extended predicates, must be declared as returning type boolean, and as public. They can be added one at a time using the API function AddPred, which adds a single predicate at a time.

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

Examples

Samples for .NET can be found in samples\dotnet and in samples\internet\asp.net.