3.3.3 Querying XSB

int xsb_query_string_string(th_context *th, char *query, VarString *buff, char *sep)

This function opens a query to the XSB thread designated by th (the first argument is not used in the single-threaded engine); it returns the first answer (if there is one) as a VarString. Any previous query to th must have already been closed. Any query may return multiple data answers. The first is found and made available to the caller as a result of this call. To get any subsequent answers, xsb_next_string() must be called. An example call is:

rc = xsb_query_string_string(th, "append(X,Y,[a,b,c]).",buff,";");

The second argument is the period-terminated query string. The third argument is a pointer to a variable string buffer in which the subroutine returns the answer (if any.) The variable string data type VarString is explained in Section 3.4. (Use xsb_query_string_string_b() if you cannot declare a parameter of this type in your programming language.) The last argument is a string provided by the caller, which is used to separate arguments in the returned answer. For the example query, buff would be set to the string:

        [];[a,b,c]

which is the first answer to the append query. There are two fields of this answer, corresponding to the two variables in the query, X and Y. The bindings of those variables make up the answer and the individual fields are separated by the sep string, here the semicolon (;). In the answer string, XSB atoms are printed without quotes. Complex terms are printed in a canonical form, with atoms quoted if necessary, and lists produced in the normal list notation.

When used in the multi-threaded engine, xsb_query_string_string protects the called thread from API calls from other pthreads until the entire query is finished.

Return Codes

• XSB_SUCCESS indicates that the query succeeded.
• XSB_FAILURE indicates that the query failed.
• XSB_ERROR
  • permission_error if xsb_query_string_string() is called while a query to th is open.
  • Otherwise, any errors thrown during execution of the query are accessable through xsb_get_error_type() and xsb_get_error_message().

int xsb_query_string_string_b(th_context *th,char *query,char *buff,int bufflen,int *anslen,char *sep)

This function provides a lower-level alternative to xsb_query_string_string (not using the VarString type), which makes it easier for non-C callers (such as Visual Basic or Delphi) to access XSB functionality. Any previous query to th must have already been closed. Any query may return possibly multiple data answers. The first is found and made available to the caller as a result of this call. To get any subsequent answers, xsb_next_string_b() or a similar function must be called. The first and last arguments are the same as in xsb_query_string_string(). The buff, bufflen, and anslen parameters are used to pass the answer (if any) back to the caller. buff is a character array provided by the caller in which the answer is returned. bufflen is the length of the buffer (buff) and is provided by the caller. anslen is returned by this routine and is the length of the computed answer. If that length is less than bufflen, then the answer is put in buff (and null-terminated). If the answer is longer than will fit in the buffer (including the null terminator), then the answer is not copied to the buffer and XSB_OVERFLOW is returned. In this case the caller can retrieve the answer by providing a bigger buffer (of size greater than the returned anslen) in a call to xsb_get_last_answer_string().

When used in the multi-threaded engine, xsb_query_string_string_b protects the called thread from API calls from other pthreads until the entire query is finished.

Return Codes

• XSB_SUCCESS indicates that the query succeeded.
• XSB_FAILURE indicates that the query failed.
• XSB_ERROR
  • permission_error if xsb_query_string_string_b() is called while a query to th is open.
  • Otherwise, any queries thrown during execution of the command are accessable through xsb_get_error_type() and xsb_get_error_message().

• XSB_OVERFLOW indicates that the query succeeded, but the answer was too long for the buffer.

int xsb_query(th_context *th)

This function passes a query to the XSB thread th. Any previous query to th must have already been closed. Any query may return possibly multiple data answers. The first is found and made available to the caller as a result of this call. To get any subsequent answers, xsb_next() or a similar function must be called. Before calling xsb_query() the caller must construct the term representing the query in the XSB thread's register 1 (using routines described in Section 2.2.3 below.) If the query has no answers (i.e., just fails), register 1 is set back to a free variable and xsb_query() returns XSB_FAILURE. If the query has at least one answer, the variables in the query term in register 1 are bound to those answers and xsb_query() returns XSB_SUCCESS. In addition, register 2 is bound to a term whose main functor symbol is ret/n, where n is the number of variables in the query. The main subfields of this term are set to the variable values for the first answer. (These fields can be accessed by the functions p2c_*, or the functions xsb_var_*, described in Section 2.2.3 below.) Thus there are two places the answers are returned. Register 2 is used to make it easier to access them. Register 2 may also be set before the call to xsb_query() (using xsb_make_vars(int) and xsb_set_var_*()) in which case any variables set to values in the ret/n term will be so bound in the call to the goal.

When used in the multi-threaded engine, xsb_query does not protect the called thread from API calls from other pthreads until the query is finished, or even when the registers are being accessed. It is the user's responsibility to protect the XSB thread, using a mutex or other concurrency control, from the time the goal begins to be constructed in the register 1 until the query is closed, failed, or exited upon error.

int xsb_get_last_answer_string(th_context *th, char *buff, int bufflen, int *anslen)

This function is used only when a call xsb_query_string_string_b() or xsb_next_string_b() to th returns XSB_OVERFLOW, indicating that the buffer provided was not big enough to contain the computed answer. In that case the user may allocate a larger buffer and then call this routine to retrieve the answer (that had been saved.) Only one answer is saved per thread, so this routine must called immediately after the failing call in order to get the right answer. The parameters are the same as the 2nd through 4th parameters of xsb_query_string_string_b().

Return Codes

• XSB_OVERFLOW indicates that the answer was still too long for the buffer.

int xsb_query_string(th_context *th,char *query)

This function passes a query to the XSB thread th. The query is a string consisting of a term that can be read by the XSB reader. The string must be terminated with a period (.). Any previous query must have already been closed. In all other respects, xsb_query_string() is similar to xsb_query(), except the only way to retrieve answers is through Register 2. The ability to create the return structure and bind variables in it is particularly useful in this function.

When used in the multi-threaded engine, xsb_query_string does not protect the called thread from API calls from other pthreads until the query is finished, or even when the registers are being accessed. It is the user's responsibility to protect the XSB thread, using a mutex or other concurrency control, from the time the goal begins to be constructed in the register 1 until the query is closed, failed, or exited upon error.

Return Codes

• XSB_SUCCESS indicates that the query succeeded.
• XSB_FAILURE indicates that the query failed.
• XSB_ERROR indicates that an error occurred while executing the query.

int xsb_next_string(th_context *th,VarString *buff,char *sep)

This routine is called after xsb_query_string() to retrieve a subsequent answer in buff. If a query is not open in th, an error is returned. This function treats answers just as xsb_query_string_string(). For example after the example call

rc = xsb_query_string_string(th,"append(X,Y,[a,b,c]).",buff,";");

which returns with buff set to

        [];[a,b,c]

Then a call:

rc = xsb_next_string(th,buff,";");

returns with buff set to

        [a];[b,c]

the second answer to the indicated query.

In the multi-threaded engine, xsb_next_string() protects the XSB thread from concurrent access by other threads as long as the query was invoked by xsb_query_string_string(_b).

Return Codes

• XSB_SUCCESS indicates that the query succeeded.
• XSB_FAILURE indicates that the query failed.
• XSB_ERROR indicates that an error occurred while executing the query.

int xsb_next_string_b(th_context *th, char *buff, int bufflen, int *anslen, char *sep)

This function is a variant of xsb_next_string() that does not use the VarString type. Its parameters are the same as the 3rd through 6th parameters of xsb_query_string_string_b(). The next answer to the current query is returned in buff, if there is enough space. If the buffer would overflow, this routine returns XSB_OVERFLOW, and the answer can be retrieved by providing a larger buffer in a call to xsb_get_last_answer_string_b(). In any case, the length of the answer is returned in anslen.

In the multi-threaded engine, xsb_next_string() protects the XSB thread from concurrent access by other threads as long as the query was invoked by xsb_query_string_string(_b).

Return Codes

• XSB_SUCCESS indicates that backtracking into the query succeeded.
• XSB_FAILURE indicates that backtracking into the query failed.
• XSB_ERROR indicates that an error occurred while further executing the query.

• XSB_OVERFLOW indicates that backtracking into the query succeeded, but the new answer was too long for the buffer.

int xsb_next(th_context *)

This function is called after xsb_query() (which must have returned XSB_SUCCESS) to retrieve more answers. It rebinds the query variables in the term in register 1 and rebinds the argument fields of the ret/n answer term in register 2 to reflect the next answer to the query. Its return codes are as with xsb_next_string().

When used in the multi-threaded engine, xsb_next does not protect the called thread from API calls from other pthreads until the query is finished, or even when the registers are being accessed. It is the user's responsibility to protect the XSB thread, using a mutex or other concurrency control, through the time that registers are accessed by the calling program.

int xsb_close_query(th_context *th)

This function allows a user to close a query to th before all its answers have been retrieved. Since XSB is (usually) a tuple-at-a-time system, answers that are not retrieved are not computed so that closing a query may save time. If a given query $Q$ is open, it is an error to open a new query without closing $Q$ either by retrieving all its answers or explicitly calling xsb_close_query() to close $Q$. Calling xsb_close_query() when no query is open gives an error message, but otherwise has no effect.

Return Codes

• XSB_SUCCESS indicates that the current query was closed.
• XSB_ERROR
  • permission_error if xsb_close_query() is called while no query is open.