The Prolog Side

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.