If you are interested in more than one solution a more complicated scheme is used. You find the predicate definition as above, but you don't call the predicate directly.
SP_open_query()
SP_next_solution() to find a solution. Call this
predicate again to find more solutions if there are any.
SP_close_query() or SP_cut_query()
The function SP_open_query() will return an identifier of type
SP_qid that you use in successive calls. Note that if a new query is
opened while another is already open, the new query must be
terminated before exploring the solutions of the old one. That is,
queries must be strictly nested.
The function SP_next_solution() will cause the Prolog engine to
backtrack over any current solution of an open query and
look for a new one.
A query must be terminated in either of two ways. The function
SP_cut_query() will discard the choices created since the
corresponding SP_open_query(), like the goal !. The
current solution is retained in the arguments until
backtracking into any enclosing query.
Alternatively, the function SP_close_query() will discard the
choices created since the corresponding SP_open_query(), and then
backtrack into the query, throwing away any current
solution, like the goal !, fail.
A simple way to call arbitrary Prolog code is to use
SP_read_from_string() (see Creating Prolog Terms) to create
an argument to call/1. It is a good idea to always
explicitly specify the module context when using call/1 or
other meta-predicates from C.