3.3.2 Passing Commands to XSB

int xsb_command_string(th_context *th, char *cmd)

This function passes a command to the XSB thread designated by th (the first argument is not used in the single-threaded engine). No query can be active in th when the command is called. The command is a string consisting of a Prolog (or HiLog) term terminated by a period (.).

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

Return Codes

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

int xsb_command(th_context *th)

This function passes a command to the XSB thread designated by th (the first argument is not used in the single-threaded engine). Any previous query must have already been closed. Before calling xsb_command(), the calling program must construct the term representing the command in register 1 in the XSB thread's space. This can be done by using the c2p_* (and p2p_*) routines, which are described in Section 2.2.3 below. 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 command goal. xsb_command invokes the command represented in register 1 and returns XSB_SUCCESS if the command succeeds, XSB_FAILURE if it fails, and XSB_ERROR if an error is thrown while executing the command.

When used in the multi-threaded engine, xsb_command_string does not protect the called thread from API calls from other pthreads until the command is finished. 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 command has completed.

Apart from the steps necessary to formulate the query and the lack of protection of the XSB thread, the behavior of xsb_command() is similar to that of xsb_command_string(), including its return codes.