The function QP_next_solution() is used to return a solution from an
open nondeterminate Prolog query. Solutions are computed on demand, and
multiple solutions are returned in the normal Prolog order.
QP_next_solution() is passed the QP_qid returned by
QP_open_query() when the nondeterminate query was opened. No
additional input or output parameters are passed: after a call to
QP_open_query(), Prolog manages inputs itself, and has been told
where storage for outputs has been reserved. Each time
QP_next_solution() computes a new solution it writes it on the
output storage for the foreign function to use as it likes. Each new
solution overwrites the old memory, destroying the previous solution,
so it is important that the foreign function copies solutions
elsewhere if it wants to accumulate them.
Important restriction: only the innermost, i.e. the most recent, open query can be asked to compute a solution. A new query can be made at any point whether or not other nondeterminate queries are open; however, while the new query remains open only it will be able to return solutions.