Initiating a Nondeterminate Prolog Query

For a nondeterminate query, multiple solutions to the query may be successively returned to the calling foreign function. Nondeterminate queries are made in three steps: the query is first initiated, or "opened", using QP_open_query(). Solutions are then requested using QP_next_solution(). When all desired solutions have been returned, or there are no more solutions, the query must be terminated by calling QP_cut_query() or QP_close_query().

The C function QP_open_query() is used to initiate a nondeterminate Prolog query. The arguments passed to QP_open_query() are identical to those that would be passed to QP_query(); however, QP_open_query() does not compute a solution to the query. Its effect is to prepare Prolog for the computation of solutions to the query, which are requested by calls to the function QP_next_solution(). For consistency checking, QP_open_query() returns a QP_qid, which represents the Prolog query. The type definition for QP_qid is found in <quintus/quintus.h>. The QP_qid returned by a call to QP_open_query() must be passed to each call to QP_next_solution() for that query, as well as to QP_cut_query() or QP_close_query() when terminating the query. If an invalid QP_qid is passed to one of these functions, the function has no effect except to return QP_ERROR.

When requesting solutions from an open nondeterminate query, input and output parameters are not passed. The effect of QP_open_query() is to pass inputs to Prolog, which subsequently maintains them. It also tells Prolog where storage for outputs has been reserved. This storage will be written later, when solutions are returned.

If an error occurs when attempting to open a query, QP_ERROR is returned and the query is automatically terminated.

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