Initiating a query from C

This section discusses the functions for creating and manipulating queries from C. Note that a foreign context can have at most one active query. This implies it is allowed to make strictly nested calls between C and Prolog (Prolog calls C, calls Prolog, calls C, etc., but it is not allowed to open multiple queries and start generating solutions for each of them by calling PL_next_solution. Be sure to call PL_cut_query or PL_close_query on any query you opened before opening the next or returning control back to Prolog.

qid_tPL_open_querymodule_t ctx, int flags, predicate_t p, term_t +t0

Opens a query and returns an identifier for it. This function always succeeds, regardless whether the predicate is defined or not. ctx is the context module of the goal. When NULL, the context module of the calling context will be used, or user if there is no calling context (as may happen in embedded systems). Note that the context module only matters for module_transparent predicates. See context_module1 and module_transparent1. The p argument specifies the predicate, and should be the result of a call to PL_pred or PL_predicate. Note that it is allowed to store this handle as global data and reuse it for future queries. The term-reference t0 is the first of a vector of term-references as returned by PL_new_term_refsn.

The flags arguments provides some additional options concerning debugging and exception handling. It is a bitwise or of the following values:

PL_Q_NORMAL Normal operation. The debugger inherits its settings from the environment. If an exception occurs that is not handled in Prolog, a message is printed and the tracer is started to debug the error.^3.3 PL_Q_NODEBUG Switch off the debugger while executing the goal. This option is used by many calls to hook-predicates to avoid tracing the hooks. An example is print1 calling portray1 from foreign code. PL_Q_CATCH_EXCEPTION If an exception is raised while executing the goal, do not report it, but make it available for PL_exception. PL_Q_PASS_EXCEPTION As PL_Q_CATCH_EXCEPTION, but do not invalidate the exception-term while calling PL_close_query. This option is experimental.

The example below opens a query to the predicate is_a/2 to find the ancestor of for some name.

intPL_next_solutionqid_t qid Generate the first (next) solution for the given query. The return value is TRUE if a solution was found, or FALSE to indicate the query could not be proven. This function may be called repeatedly until it fails to generate all solutions to the query. voidPL_cut_queryqid Discards the query, but does not delete any of the data created by the query. It just invalidate qid, allowing for a new call to PL_open_query in this context. voidPL_close_queryqid As PL_cut_query, but all data and bindings created by the query are destroyed. intPL_call_predicatemodule_t m, int flags, predicate_t pred, term_t +t0 Shorthand for PL_open_query, PL_next_solution, PL_cut_query, generating a single solution. The arguments are the same as for PL_open_query, the return value is the same as PL_next_solution. intPL_callterm_t, module_t Call term just like the Prolog predicate once1. Term is called in the specified module, or in the context module if module_t = NULL. Returns TRUE if the call succeeds, FALSE otherwise. calling shows an example to obtain the number of defined atoms. All checks are omitted to improve readability.