Opens a query and returns an identifier for it. 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 meta-predicates. See meta_predicate/1,
context_module/1
and module_transparent/1.
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_refs(n).
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.196Do
not pass the integer 0 for normal operation, as this is interpreted as
PL_Q_NODEBUG
for backward compatibility reasons. 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 print/1 calling portray/1 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. PL_Q_ALLOW_YIELD
- Support the
I_YIELD
instruction for engine-based coroutining. See $engine_yield/2 inboot/init.pl
for details. PL_Q_EXT_STATUS
- Make PL_next_solution()
return extended status. Instead of only
TRUE
orFALSE
extended status as illustrated in the following table:Extended Normal PL_S_EXCEPTION FALSE Exception available through PL_exception() PL_S_FALSE FALSE Query failed PL_S_TRUE TRUE Query succeeded with choicepoint PL_S_LAST TRUE Query succeeded without choicepoint
PL_open_query() can return the query identifier‘0' if there is not enough space on the environment stack. This function succeeds, even if the referenced predicate is not defined. In this case, running the query using PL_next_solution() will return an existence_error. See PL_exception().
The example below opens a query to the predicate is_a/2
to find the ancestor of‘me'. The reference to the predicate is
valid for the duration of the process and may be cached by the client.
char * ancestor(const char *me) { term_t a0 = PL_new_term_refs(2); static predicate_t p; if ( !p ) p = PL_predicate("is_a", 2, "database"); PL_put_atom_chars(a0, me); PL_open_query(NULL, PL_Q_NORMAL, p, a0); ... }