Notes

ANSI Conformance

Only C compilers that support ANSI C (or similar) are supported.

The SP_PATH variable

It is normally not necessary to set this environment variable, but its value will be used, as a fall-back, at runtime if no explicit boot path is given when initializing a runtime or development system. In this chapter, the environment variable SP_PATH is used as a shorthand for the SICStus Prolog installation directory, whose default location for SICStus 3.11.0 is /usr/local/lib/sicstus-3.11.0) for UNIX and C:\Program Files\SICStus Prolog 3.11.0 for Windows. See Environment Variables.

Windows note: Explicit use of the SP_PATH variable is discouraged, since Windows applications can find out for themselves where they were started from. SP_PATH is only used if the directory where sprt311.dll is loaded from does not contain sp-3.11.0 (a directory), sprt.sav, or spre.sav. If SP_PATH is used, SICStus expects it to be set such that %SP_PATH%\bin contains sprt.sav or spre.sav. See Runtime Systems on Target Machines.

Definitions and declarations

Type definitions and function declarations for the interface are found in the header file <sicstus/sicstus.h>.

Error Codes

The value of many support functions is a return code, which is one of SP_SUCCESS for success, SP_FAILURE for failure, SP_ERROR if an error condition occurred, or if an uncaught exception was raised during a call from C to Prolog. If the value is SP_ERROR, the macro SP_errno will return a value describing the error condition:

          int SP_errno
          

The function SP_error_message() returns a pointer to the diagnostic message corresponding to a specified error number:

          char *SP_error_message(int errno)
          

Wide Characters

The foreign interface supports wide characters. Whenever a sequence of possibly wide character codes is to be passed to or from a C function it is encoded as a sequence of bytes, using the so called internal encoding of SICStus Prolog, the UTF-8 encoding; see WCX Concepts. Unless noted otherwise the encoded form is terminated by a NUL byte. This sequence of bytes will be called an encoded string, representing the given sequence of character codes. Note that it is a property of the UTF-8 encoding that it does not change ASCII character code sequences.

If a foreign function is specified to return an encoded string, an exception will be raised if, on return to Prolog, the actual string is malformed (is not a valid sequence of UTF-8 encoded characters). The exception raised is representation_error(...,...,mis_encoded_string).