Discards the query, but does not delete any of the data created by the
query. It just invalidates qid, allowing for a new call to
PL_open_query()
in this context. PL_cut_query()
may invoke cleanup handlers (see setup_call_cleanup/3)
and therefore may experience exceptions. If an exception occurs the
return value is FALSE and the exception is accessible
through PL_exception(0).
An example of a handler that can trigger an exception in
PL_cut_query()
is:
test_setup_call_cleanup(X) :-
setup_call_cleanup(
true,
between(1, 5, X),
throw(error)).
where PL_next_solution()
returns TRUE on the first result and the throw(error)
will only run when PL_cut_query()
or
PL_close_query()
is run. On the other hand, if the goal in
setup_call_cleanup/3
has completed (failure, exception, deterministic success), the cleanup
handler will have done its work before control gets back to Prolog and
therefore PL_next_solution()
will have generated the exception. The return value PL_S_NOT_INNER
is returned if qid is not the innermost query.
