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().