3.1 Calling XSB from C

XSB provides several C functions (declared in $XSBDIR/emu/cinterf.h and defined in
$XSBDIR/emu/cinterf.c), which can be called from C to interact with XSB as a subroutine. These functions allow a C program to interact with XSB in a number of ways.

• XSB may be initialized, using most of the parameters available from the command-line.
• XSB may then execute a series of commands or queries. A command is a deterministic query which simply succeeds or fails without performing any unification on the query term. On the other hand, a non-deterministic query can be evaluated so that its answer substitutions are retrieved one at a time, as they are produced, just as if XSB were called on a command line. Alternately a non-deterministic query can be closed in the case where not every answer to the query is needed. Only one query per thread can be active at a time. I.e., an application must completely finish processing one query to a given thread $T$ (either by retrieving all the answers for it, or by issuing a call to xsb_close_query(), before trying to evaluate another using $T$.
• Finally, XSB can be closed, so that no more queries can be made to any XSB threads.

In general, while any functions in the C API to XSB can be intermixed, the functions can be classified as belonging to three different levels.

• A VarString level which uses an XSB-specific C-type definition for variable-length strings (Section 3.4), to return answers.
• A fixed-string level provides routines that return answers in fixed-length strings.
• A register-oriented level that requires users to set up queries by setting registers for XSB which are made globally available to calling functions. The mechanisms for this resemble the lower-level C interface discussed in Chapter 2. This level of interface should only be used for the single-threaded applications, as it is difficult to prevent race-conditions at this level of interface when multiple C threads are used to call XSB.

The appropriate level to use depends on the nature of the calling program, the speed desired, and the expertise of the programmer. By and large, functions in the VarString level are the the easiest and safest to use, but they depend on a C type definition that may not be available to all calling programs (e.g. it may be difficult to use if the calling program is not directly based on C, such as Visual Basic or Delphi). For such applications functions from the fixed-string level would need to be used instead. In general, most applications should use either functions from the VarString or the fixed-string level, rather than the register-oriented level. This latter level should only be used by programmers who are willing to work at a low interface level, when the utmost speed is needed by an application, and when multiple threads do not need to interact with XSB.