C++ Class

The Amzi! engine is implemented using C++. Internally, a Prolog engine is a C++ object with member functions that provide the services of the Logic Server API. There are two interfaces on that engine object.

One is the standard Logic Server API calls, as documented in the LSAPI section of this manual. The other is a C++ class, LogicServer, that provides an external interface to the internal engine object. C++ programmers can use either interface, but LogicServer is preferred for the obvious reasons.

The C++ interface also includes class LSException. Instances of this class are thrown when Logic Server exceptions are encountered. C++ programmers should use try/catch blocks around Logic Server calls in order to catch Logic Server exceptions. (This is in contrast to the functional LSAPI that uses return codes for exception handling.)

To use the Logic Server from C++, an application must include the header file logicserver.h and link with the appropriate library:

amzi.lib for Microsoft Visual C++ applications,
amzib.lib for Borland C++ applications, and
libamzi.so for Unix C++ applications.

Hello Prolog

There are a number of versions of the Hello Prolog sample in the subdirectory samples/cpp/hello. As of this writing they are:

console - A Microsoft VC++ console implementation.
dialog - A Microsoft VC++ MFC implementation.

Encapsulating Prolog Services

The Logic Server class can be easily used to encapsulate application-specific Prolog services. Simply derive a class from the Logic Server class and define member functions that make the calls to the Logic Server.

You can use the constructor and destructor member functions for initialization and closing of the Logic Server, and you can implement your own error handler within your class.

Multiple LogicServers

Each time you create a new instance of LogicServer, you create a new instance of the the Amzi! Prolog engine. You can run as many simultaneous Logic Servers as your machine can handle.

Implementing Extended Predicates

Extended predicates (Prolog predicates you implement in C/C++) are implemented as callback functions. That is, you pass a function pointer to the Logic Server and associate that pointer with a Prolog predicate name. When the Prolog engine encounters that predicate, it calls the function you provided.

Ideally, in a C++ application you would like to implement extended predicates as member functions in the classes you derive from LogicServer. Because you can't get access to a member function pointer in C++, this is not easy.

The Logic Server API supports the next best solution. It allows you to create extended predicate definitions that include the predicate name, the function pointer and an argument to be passed by the Logic Server to the function. This argument can be anything, but if its the 'this' pointer of the object creating the function, then the function can use that pointer to dispatch the call to the appropriate member function of your C++ object.

The sample in samples/cpp/petscb illustrates this technique.

Unicode Support

There are wide versions of all the LSAPI calls that use strings as arguments or returns values. The wide version method names all end in 'W'. You use the Standard Template Library class string for ANSI strings and wstring for Unicode ones.

The functions mbstowcs() and wcstombs() are used to convert between wide and multibyte (ANSI) strings, so multibyte character sets can also be used with the Logic Server.