The interface for calling a Prolog program from a C program is strictly
typed. In the Prolog servant program, the user must declare
which Prolog procedures can be called from the
C program, the types of the data elements to be passed between them, and the
direction the elements are to be sent. This is done in Prolog by defining
external/3
facts to provide this information. These facts are very
similar to those for foreign/3
and have the following form:
external(CommandName, Protocol, PredicateSpecification).
CommandName is the name by which the C program invokes this
predicate.
Protocol is the protocol to be used, which currently must
be xdr
.
PredicateSpecification is a term that describes the
Prolog predicate and the interface, and is of the form:
PredicateName(ArgSpec1, ArgSpec2, ...)
PredicateName is the name of the Prolog predicate (an atom). There is an ArgSpec for each argument of the predicate, and ArgSpec is one of:
+integer +float +atom +string -integer -float -atom -string
Examples:
external(add, xdr, addtwoints(+integer,+integer,-integer)). external(ancestor, xdr, ancestor(+string,-string)). /* Define addtwoints/3 for use by C caller. */ addtwoints(X, Y, Z) :- Z is X+Y. /* Define ancestor/2 for use by C caller */ ancestor(X, Y) :- parent(X, Y). ancestor(X, Y) :- parent(X, Z), ancestor(Z, Y).
The interface allows the simple Prolog data types (atoms, integers, and
floating-point numbers) to be passed to and from a calling C program. The
+
annotation on an argument specification means that the corresponding
value will be passed from the calling C program to the called Prolog
predicate. A -
annotation means that the value will be passed
from the
Prolog predicate back to the calling C program. The +
and -
annotations are always from the point of view of the master (or caller).
In this case the C program is the master.
The argument specifications have the same meanings as they do in
foreign/3
facts, but note the directions implied by +
and -
. Also note that the ...
specifications are
not allowed. The limitations on the sizes of integers, floats, and
strings in Prolog are the same as for the interface to foreign
routines.
The values passed as atom
arguments will be treated as unsigned
integers in the C program. Their uses
must be restricted to
the same invocation of the Prolog servant. These integers can be
converted to and from the associated strings by using the C functions
QP_ipc_atom_from_string()
and QP_ipc_string_from_atom()
below.