Making a Determinate Prolog Query

A determinate query can be made in a single C function call using QP_query. The first argument passed to QP_query() is a QP_pred_ref for the predicate to be called. Any arguments after the first represent parameters to be passed to and from the Prolog predicate.

The foreign language interface will interpret arguments passed to the Prolog predicate according to the call specification given when the predicate was made callable. Hence, it is important that the arguments to be passed to and from the Prolog predicate should correspond to that call specification. For certain parameter types (passing Prolog atoms in canonical form) it is possible to detect inconsistencies between data supplied to QP_query() and the call specification, but for the most part this is impossible. Calls that are inconsistent with their call specifications will produce undefined results.

QP_query() returns one of three values: QP_SUCCESS, indicating that the query was made and a solution to the query was computed; QP_FAILURE, meaning that the query was made but no solution could be found; and QP_ERROR, which says that either the query could not be made, or that an exception was signaled from Prolog but not caught. In this case, see the reference page for QP_exception_term(). Only when the return value is QP_SUCCESS should the values in variables passed as outputs from Prolog be considered valid. Otherwise, their contents are undefined.

It is important that a valid QP_pred_ref is passed to QP_query(); in particular, it is advisable to check for an error return from QP_predicate() or QP_pred() before calling QP_query().