Node:Top, Next:, Previous:(dir), Up:(dir)

SICStus Prolog Release Notes

Release notes for SICStus Prolog release 3.10.0, December 2002. Copyright 2002 SICS, Sweden.

Permission is granted to make and distribute verbatim copies of these notes provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of these notes under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of these notes into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by SICS.


Node:Overview, Next:, Previous:Top, Up:Top

Overview

These notes summarize the changes in release 3 wrt. previous SICStus Prolog releases as well as changes introduced by minor releases and their patch releases. Platform specific information pertaining to certain parts of the system are also documented herein.


Node:Supported platforms, Next:, Previous:Overview, Up:Top

Supported platforms

Release 3.10 is actively being supported on the following platforms:

In addition, earlier versions of SICStus have been verified to run on a number of other platforms. Contact sicstus-support@sics.se if you have any questions about a particular platform (listed or not listed).


Node:Release notes and installation guide for UNIX, Next:, Previous:Supported platforms, Up:Top

Release notes and installation guide for UNIX

This chapter assumes that the environment variable PATH includes <prefix>/bin, where <prefix> points to the SICStus installation directory. The installation directory is specified during installation; see UNIX installation. For example:

csh,tcsh> setenv PATH "/usr/local/bin:$PATH"
sh,bash,ksh> export PATH="/usr/local/bin:$PATH"


Node:UNIX installation, Next:, Previous:Release notes and installation guide for UNIX, Up:Release notes and installation guide for UNIX

Installation

Installation of SICStus on UNIX is performed by an installation (Shell) script InstallSICStus which interacts with the user to obtain options such as where to install SICStus. As of SICStus 3.9.1, the Java based SICStus Installer Tool is a graphical front-end to the installation script which automates downloading and installation. The SICStus Installer Tool is available from the download page. Use of the SICStus Installer Tool is strictly optional but may be convenient, especially on platforms such as Mac OS X, that, by default, lack C compiler.


Node:UNIX Installation Prerequisites, Next:, Previous:UNIX installation, Up:UNIX installation

Prerequisites


Node:C compiler and linker, Up:UNIX Installation Prerequisites

C compiler and linker

A full SICStus installation requires a C compiler and a linker to perform final link steps on the installation machine.

If a C compiler is not available, it is possible to use a pre-built installation on some platforms (e.g. Mac OS X, 64bit SPARC Solaris).

Pre-built installation is only recommended as a last resort; it is available from the SICStus Installer Tool or by invoking InstallSICStus with the --all-questions argument.

A disadvantage with the pre-built installation is that SICStus libraries that interface to third-party products (Tcl/Tk, Berkeley DB, Java) may not work, or may require environment variables such as LD_LIBRARY_PATH to be set. Another disadvantage is that spld and splfr may not work unless you manually adjust the spld configure file. Of course, neither spld nor splfr will work anyway if you do not have a C compiler.


Node:The installation script, Previous:UNIX Installation Prerequisites, Up:UNIX installation

The installation script

Most users will install SICStus from a binary distribution. These are available for all supported platforms. Information on how to download and unpack the binary distribution is sent by email when ordering SICStus.

Binary distributions are installed by executing a interactive installation script called InstallSICStus. Type

% ./InstallSICStus

and follow the instructions on the screen. As an alternative, the SICStus Installer Tool can be used to download the SICStus files and invoke the installation script.

During installation, you will be required to enter your site-name and license code. These are included in the download instructions.

The installation program does not only copy files to their destination, it also performs final link steps for some of the executables and for the library modules requiring third-party software support (currently library(bdb), library(tcltk), and library(jasper)). This is done in order to adapt to local variations in installation paths and versions.

Invoke InstallSICStus with the --help argument to get a list of options.

Compiling SICStus from the sources requires a source code distribution, available on request for customers with maintenance contract. Contact sicstus-support@sics.se for more info.

Instructions for compiling and installing SICStus from the source code is available in the files README and INSTALL in the source code distribution.


Node:UNIX foreign language interface, Next:, Previous:UNIX installation, Up:Release notes and installation guide for UNIX

Foreign Language Interface


Node:How to customize splfr, Next:, Previous:UNIX foreign language interface, Up:UNIX foreign language interface

How to Customize splfr and spld

The utilities splfr and spld are implemented as Perl scripts and can be customized in order to adapt to local variations. Do not attempt this unless you know what you are doing. Customization is done by editing their common configuration file spconfig-version. Follow these instructions:

  1. Locate the configuration file spconfig-version. It should be located in the same directory as splfr and spld.
  2. Make a copy for spconfig-version; let's call it hacked_spld.config. Do not edit the original file.
  3. The configuration file contains lines on the form CFLAGS=-g -O2. Edit these according to your needs. Do not add or remove any flags.
  4. You may now use the modified spconfig-version together with spld or splfr like this:
    % spld [...] --config=/path/to/hacked_spld.config
    
    Replace /path/to with the actual path to the hacked configuration file.


Node:How to create dynamic linked foreign resources manually, Next:, Previous:How to customize splfr, Up:UNIX foreign language interface

How to Create Dynamic Linked Foreign Resources Manually

The only supported method for building foreign resources is by compiling and linking them with splfr. However, this is sometimes inconvenient, for instance when writing a Makefile for use with UNIX make. To figure out what needs to be done to build a foreign resource, you should build it once with splfr --verbose --keep ..., note what compiler and linker flags are used, and save away any generated files. You can then mimic the build commands used by splfr in your Makefile, or similar. You should repeat this process each time you upgrade SICStus, even if only the revision part of the SICStus version changes.


Node:Interfacing to Cplusplus, Next:, Previous:How to create dynamic linked foreign resources manually, Up:UNIX foreign language interface

Interfacing to C++

Functions in C++ files which should be called from Prolog must use C linkage, e.g.

extern "C" {
void myfun(long i)
{...};
};

To build a dynamic linked foreign resource with C++ code, you may (depending on platform) have to explicitly include certain libraries. E.g. on Sparc/SunOS 5.X using gcc:

% splfr .... -LD -L/usr/gnu/lib/gcc-lib/sparc-sun-solaris2.4/2.7.0 -lgcc

The library path is installation dependent, of course.


Node:UNIX Runtime Systems on Target Machines, Previous:Interfacing to Cplusplus, Up:UNIX foreign language interface

Runtime Systems on Target Machines

This section describes how to distribute runtime systems on target machines, i.e. machines which do not have SICStus installed. An alternative approach to what is presented here is to package the whole application as an all-in-one executable; see All-in-one Executables.

In order to build a runtime system for distribution on a target machine, the option --moveable must be passed to spld. This option prevents spld from hardcoding any (absolute) paths into the executable.

Next, in order for SICStus to be able to locate all relevant files, the following directory structure should be used.

myapp.exe
sp-3.10.0/
+--- libsprt310.so
+--- sicstus-3.10.0/
     +--- bin/
     |    +--- sprt.sav
     +--- library/
          +--- <files from $SP_PATH/library>

If support for multiple SICStus instances is needed, then the run-times named e.g. libsprt310_instance_01_.so, need to be available as well, in the same place as libsprt310.so.

If SICStus is installed on the target machine, a symbolic link named sp-3.10.0 can be used, in which case it should point at the directory of the SICStus installation that contains the libsprt310.so (or equivalent).

myapp.exe is typically created by a call to spld:

% spld --main=user --moveable [...] -o ./myapp.exe

On most platforms, the above directory layout will enable the executable to find the SICStus run-time (libsprt310.so) as well as the boot file sprt.sav (spre.sav). In addition, application specific files, e.g. a .sav file, can be found using the automatically set environment variables SP_APP_DIR or SP_RT_DIR. On some platforms a wrapper script, generated by spld, is needed to ensure that the files are found.

On some platforms, the executable will not be able to locate sprt.sav (spre.sav) unless the environment variable SP_PATH is set. If the example above is rooted in /home/joe, then SP_PATH should be set to /home/joe/lib/sicstus-3.10.0. This is not needed on platforms where SP_APP_DIR or SP_RT_DIR can be used, e.g. on Linux, Solaris or Win32 and most others.

Unless the --static option is passed to spld, it might also be necessary to set LD_LIBRARY_PATH (or equivalent) to /home/joe/lib (in the example above) in order for the dynamic linker to find libsprt310.so. If the --static option is used, this is not necessary. Setting LD_LIBRARY_PATH is not needed, nor recommended, on Linux and Solaris (and Win32).


Node:Platform specific UNIX notes, Next:, Previous:UNIX foreign language interface, Up:Release notes and installation guide for UNIX

Platform Specific Notes

This section contains some installation notes which are platform specific under UNIX.


Node:Redistributable files UNIX, Previous:Platform specific UNIX notes, Up:Release notes and installation guide for UNIX

Files that May Be Redistributed with Runtime Systems

When a runtime system is redistributed to third parties, only the following files may be included in the distribution. All filenames are relative to <prefix>/lib/sicstus-3.10.0:

../*.{a,so,sl,dylib}
bin/sprt.sav
bin/spre.sav
bin/jasper.jar
library/*.{tcl,po,pl}
Except license.pl!
library/*/*.{s.o,so,sl,dylib}
library/*/*.{po,pl}
sp_platform
(Located with InstallSICStus)


Node:Release notes and installation guide for Windows, Next:, Previous:Release notes and installation guide for UNIX, Up:Top

Release notes and installation guide for Windows

This chapter assumes that the environment variable PATH includes %SP_PATH%\bin, where SP_PATH points to the SICStus installation directory (typically C:\Program Files\SICStus Prolog 3.10.0. Here, %SP_PATH% is just a place-holder; you usually do not need to set the environment variable SP_PATH, but see Setting SP_PATH under Windows. For example:

C:\> set PATH=C:\Program Files\SICStus Prolog 3.10.0\bin;%PATH%

You may also want to include the paths to Tcl/Tk (see Tcl/Tk Notes), Java (see Getting Started), and Berkeley DB (see Berkeley DB notes).


Node:Windows Requirements, Next:, Previous:Release notes and installation guide for Windows, Up:Release notes and installation guide for Windows

Requirements


Node:Windows Installation, Next:, Previous:Windows Requirements, Up:Release notes and installation guide for Windows

Installation

The development system comes in two flavors:

  1. A console-based executable which is suitable to run from a DOS-prompt, from batch files, or under Emacs. See Command line editing.
  2. A windowed executable providing command line editing and menus.

The distribution consists of a single, self-installing executable (InstallSICStus.exe) containing development system, runtime support files, library sources, and manuals. Note that the installer itself asks for a password, when started. This is different from the license code.

Installed files on a shared drive can be reused for installation on other machines.

SICStus Prolog requires a license code to run. You should have received from SICS your site name, the expiration date and the code. This information is normally entered during installation:

Expiration date: ExpirationDate
Site: Site
License Code: Code

but it can also be entered later on by executing the following commands at a command prompt:

% splm -i Site
% splm -a sicstus3.10 ExpirationDate Code
on Windows NT/2000/XP splm must be run by a user with Administrative rights. As of SICStus 3.10, the windowed version of SICStus (spwin.exe) has a menu item for license entry, making splm unnecessary on Windows.


Node:Windows notes, Next:, Previous:Windows Installation, Up:Release notes and installation guide for Windows

Windows Notes


Node:Runtime Systems on Target Machines, Next:, Previous:Windows notes, Up:Windows notes

Runtime Systems on Target Machines

This section describes how to launch a runtime system on a so called target machine, i.e. a machine which does not have SICStus installed. An alternative approach to what is presented here is to package the whole application as an all-in-one executable; see All-in-one Executables.

In order to locate all relevant files, the following directory structure should be used.

myapp.exe
sprt310.dll
sp310\
+--- bin\
|    +--- sprt.sav
+--- library\
     +--- <files from %SP_PATH%\library>

if support for multiple SICStus instances is needed, then the run-times named e.g. sprt310_instance_01_.dll, need to be available as well, in the same place as sprt310.dll.

myapp.exe is typically created by a call to spld:

% spld --main=user [...] -o ./myapp.exe

If the directory containing sprt310.dll contains a directory called sp310, SICStus assumes that it is part of a Runtime System as described in the picture. The (extended) runtime library, sprt.sav (spre.sav), is then looked up in the directory (sp310/bin), as in the picture. Furthermore, the initial library_directory/1 fact will be set to the same directory with sp310/library appended.

The directory structure under library/ should look like in a regular installed SICStus, including the platform-specific subdirectory (x86-win32-nt-4 in this case). If your application needs to use library(system) and library(random), your directory structure may look like:

myapp.exe
sprt310.dll
sp310\
+--- bin\
|    +--- sprt.sav
+--- library\
     +--- random.po
     +--- system.po
     +--- x86-win32-nt-4 \
          +--- random.dll
          +--- system.dll

The sp* files can also be put somewhere else in order to be shared by several applications provided the sprt310.dll can be located by the DLL search.

The 310 in the file names above is derived from SICStus Prolog's major and minor version numbers, i.e. currently 3 and 10. Naming the files with version number enables applications using different SICStus versions to install the sp* files in the same directory.


Node:Generic Runtime Systems, Next:, Previous:Runtime Systems on Target Machines, Up:Windows notes

Generic Runtime Systems

There are three ready-made runtime systems provided with the distributions, %SP_PATH%\bin\sprt.exe, %SP_PATH%\bin\sprtw.exe, and %SP_PATH%\bin\sprti.exe. These have been created using spld:

% spld --main=restore '$SP_APP_DIR/main.sav' -o sprt.exe
% spld --main=restore '$SP_APP_DIR/main.sav' -i -o sprti.exe
% spld --main=restore '$SP_APP_DIR/main.sav' --window -o sprtw.exe

These are provided for users who do not have a C-compiler available. The programs launches a runtime system by restoring the saved state main.sav (located in the same folder as the program).

The saved state is created by save_program/[1,2]. If it was created by save_program/2, the given startup goal is run. Then, user:runtime_entry(start) is run. The program exits with 0 upon normal temination and with 1 on failure or exception.

The program sprti.exe assumes that the standard streams are connected to a terminal, even if they do not seem to be (useful under Emacs, for example). sprtw.exe is a windowed executable, corresponding to spwin.exe.

For more info on how spld works, see The spld tool.


Node:Setting SP_PATH under Windows, Previous:Generic Runtime Systems, Up:Windows notes

Setting SP_PATH under Windows

The use of the SP_PATH variable under Windows is discouraged, since Windows applications can find out for themselves where they were started from.

SP_PATH is only used if the directory where sprt<ver>.dll is loaded from does not contain sp<ver> (a directory), sprt.sav, or spre.sav (where <ver> is "310" for SICStus version 3.10(.x)). 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.


Node:Command line editing, Next:, Previous:Windows notes, Up:Release notes and installation guide for Windows

Command Line Editing

Command line editing supporting Emacs-like commands and IBM PC arrow keys is provided in the console-based executable. The following commands are available:

^h
erase previous char
^d
erase next char
^u
kill line
^f
forward char
^b
backward char
^a
begin of line
^e
end of line
^p
previous line
^n
next line
^i
insert space
^s
forward search
^r
reverse search
^v
view history
^q
input next char blindly
^k
kill to end of line

Options may be specified in the file %HOME%\spcmd.ini as:

Option Value

on separate lines. Recognized options are:

lines
Value is the number of lines in the history buffer. 1-100 is accepted; the default is 30.
save
Value is either 0 (don't save or restore history buffer) or 1 (save history buffer in %HOME%\spcmd.hst on exit, restore history from the same file on start up.

The command line editing is switched off by giving the option -nocmd when starting SICStus. Command line editing will be automatically turned off if SICStus is run with piped input (e.g. from Emacs).


Node:The console, Next:, Previous:Command line editing, Up:Release notes and installation guide for Windows

The Console Window

The console window used for the windowed executable is based on code written by Jan Wielemaker <jan@swi.psy.uva.nl>.

In SICStus 3.8 the console was enhanced with menu access to common Prolog flags and file operations. Most of these should be self explanatory. The Reconsult item in the File menu reconsults the last file consulted with use of the File menu. It will probably be replaced in the future with something more powerful.

Note that the menus work by simulating user input to the Prolog top level or debugger. For this reason, it is recommended that the menus are only used when SICStus is waiting for a goal at the top-level (or in a break level) or when the debugger is waiting for a command.


Node:Console Preferences, Previous:The console, Up:The console

Console Preferences

The stream-based console window is a completely separate library, using its own configuration info. It will look at the environment variable CONSOLE which should contain a string of the form name:value{,name:value} where name is one of:

sl
The number of lines you can scroll back. There is no limit, but the more you specify the more memory will be used. Memory is allocated when data becomes available. The default is 200.
rows
The initial number of lines. The default is 24.
cols
The initial number of columns. The default is 80.
x
The X coordinate of the top-left corner. The default is determined by the system.
y
The Y coordinate of the top-left corner. The default is determined by the system.

On Windows 95 or 98, you will normally specify this in your autoexec.bat file. Here is an example:

% set CONSOLE=sl:600,x:400,y:400

On Windows NT and Windows 2000 or newer, you would use the System Control Panel.

Many of these settings are also accessible from the menu Settings of the console.


Node:Windows limitations, Next:, Previous:The console, Up:Release notes and installation guide for Windows

Windows Limitations


Node:Redistributable files Windows, Previous:Windows limitations, Up:Release notes and installation guide for Windows

Files that May Be Redistributed with Runtime Systems

When a runtime system is redistributed to third parties, only the following files may be included in the distribution. All filenames are relative to %SP_PATH%:

bin\sprt.sav
bin\spre.sav
bin\jasper.jar
bin\*.dll
bin\*.po
library\*.{tcl,po,pl,bas}
Except license.pl!
library\*\*.dll
library\*\*.{po,pl}


Node:Tcl/Tk Notes, Next:, Previous:Release notes and installation guide for Windows, Up:Top

Tcl/Tk Notes

Tcl/Tk itself is not included in the SICStus distribution. It must be installed in order to use the interface. It can be downloaded from the Tcl/Tk primary website:

http://dev.scriptics.com

for MacOS X we installed Tcl/Tk (and the X windows system) using fink, available at:

http://fink.sourceforge.net

The Tcl/Tk interface module included in SICStus Prolog 3.10 (library(tcltk)) is verified to work with Tcl/Tk 8.3. The current version of the interface is expected to work with version 8.1 and newer.

Under UNIX, the installation program automatically detects the Tcl/Tk version (if the user does not specify it explicitly). The distributed files are compiled for Tcl/Tk 8.3.

Under Windows, the binary distribution is compiled against Tcl/Tk 8.3. If you need to use another version of Tcl/Tk, you have to recompile library(tcltk); see Configuring the Tcl/Tk library module under Windows. Please note: You need to have the Tcl/Tk binaries accessible from your PATH environment variable, e.g. C:\Program Files\Tcl\bin".

The GUI version of SICStus spwin, like all Windows non-console applications, lacks the C standard streams (stdin,stdout,stderr) and the Tcl command puts and others that use these streams will therefore give errors. The solution is to use sicstus.exe instead of spwin.exe if the standard streams are required.


Node:The TclTk Terminal, Previous:Tcl/Tk Notes, Up:Tcl/Tk Notes

The Tcl/Tk Terminal Window

The Tcl/Tk interface includes a experimental terminal window based on Tcl/Tk. It is opened by using the (undocumented) predicate:

tk_terminal(Interp, TextWidget, InStream, OutStream, ErrStream)
Given a TextWidget, e.g. .top.myterm, this predicate opens three Prolog streams for which the text widget acts as a terminal.

There is also a library(tkconsol), making use of tk_terminal/5, which switches the Prolog top level to a Tk window. This is done by simply loading the library module.


Node:Jasper Notes, Next:, Previous:Tcl/Tk Notes, Up:Top

Jasper Notes


Node:Supported Java Versions, Next:, Previous:Jasper Notes, Up:Jasper Notes

Supported Java Versions

Jasper requires at least Java 2 (a.k.a. JDK 1.2) to run. Except on Windows the full development kit, not just the JRE, is needed. Jasper does not work with Visual J++ or Visual Café. Unless indicated otherwise, you can download the JDK from <http://java.sun.com>.

Except where indicated, Jasper is built with JDK 1.3.1. On Linux, Solaris and Win32, Jasper is also tested with 1.2.2.

As of SICStus 3.9.1, it is possible to configure SICStus to use JDK 1.4. This has not been extensively tested. Please report any problems to SICStus support.

Jasper is only supported under the following configurations:


Solaris 2.x (SPARC and x86)
JDK 1.2
Verified using Sun's JDK 1.2.2_06, earlier versions of 1.2 are also expected to work.
JDK 1.3
JDK 1.3 is now supported with some limitations; see the Linux entry below.
JDK 1.3.1
JDK 1.3.1 is now supported; see the Linux entry below. See Known Bugs and Limitations in Jasper, for when JDK 1.2 or JDK 1.4 is preferred over JDK 1.3.
JDK 1.4.0
JDK 1.4.0 appears to work. This is the only version that works with 64 bit SPARC Solaris.

Linux (x86)
JDK 1.2
Verified using Blackdown's JDK (Version 1.2.2 FCS for Linux). Downloadable from http://www.blackdown.org/java-linux.html.

Sun's JDK 1.2.2 does not support native threads and therefore does not work.

JDK 1.3.0_02
Other versions of JDK 1.3 are also expected to work.

JDK 1.3 uses signals in a way that are incompatible with the way signals are used by the SICStus development system (sicstus). Most of the signal handlers used by (sicstus) are now turned off automatically before library(jasper) starts Java. This appears to make JDK 1.3 work with the SICStus development system. However, according to the JDK 1.3 documentation this may still cause problems. In JDK 1.3.1 the problem with conflicting uses of signals was recognized and a Java initialization option was added to reduce Java's use of signals; see the JDK 1.3.1 item below.

Note that this is a problem only with development systems. SICStus run-time systems do not use signals, and for this reason, JDK 1.3 works e.g. when embedding SICStus in Java using the Jasper package.

JDK 1.3.1
Tested with JDK 1.3.1. JDK 1.3.1 uses signals in the same way as JDK 1.3 resulting in the same conflicts with the SICStus development system as described above. However, JDK 1.3.1 supports the option -Xrs which makes JDK use signals in a way that is compatible with the SICStus development system.

There are several ways to pass this flag to Java. The recommended way is to pass it with jasper_initialize:

bash> sicstus -m
...
| ?- use_module(library(jasper)),
     jasper_initialize(['-Xrs', <other options here>], JVM).
Alternatively, you can pass it using the (not documented in the JDK documentation) environment variable _JAVA_OPTIONS:
bash> export _JAVA_OPTIONS='-Xrs'
bash> sicstus -m
Using _JAVA_OPTIONS is currently the only way to pass this flag if you rely on the automatic Java initialization done when invoking a Java foreign resource.

Note that, also for JDK 1.3.1, this is only a problem with the SICStus development system.

JDK 1.4.0
JDK 1.4.0 seems to work.

MacOS X 10.1
MacOS X 10.1 comes with JDK 1.3.1 pre-installed. This is the only version of JDK supported by SICStus. Also see the Linux entry above.
MacOS X 10.1
Using Jasper from Java may require that DYLD_LIBRARY_PATH be set-up so that Java can find the SICStus run-time library. That is, you may need to set DYLD_LIBRARY_PATH to the location of the SICStus run-time libsprt310.dylib.
Tru64 V5.1
Only the 64bit version (java -fast64) of JDK 1.3.1 is supported. Also see the Linux entry above.
Tru64 V5.1
When using Java to call SICStus, you will need to set LD_LIBRARY_PATH to the directory where the SICStus run-time library is located (e.g. /usr/local/lib).
Windows 95/98/NT/2000/XP
Verified using Sun's JDK 1.2.2, JDK 1.3.1 and JDK 1.4.0.
AIX
JDK 1.3.1 is supported.

The AIX version of JDK 1.3.1 requires some environment variables to be set before invoking an application that embeds the Java VM. For this reason, the following environment variables should be set before starting a SICStus executable that uses library(jasper):

bash$ export AIXTHREAD_SCOPE=S
bash$ export AIXTHREAD_MUTEX_DEBUG=OFF
bash$ export AIXTHREAD_RWLOCK_DEBUG=OFF
bash$ export AIXTHREAD_COND_DEBUG=OFF
bash$ export LDR_CNTRL=USERREGS
bash$ sicstus -m
...

See the AIX JDK 1.3.1 readme (/usr/java131/README.HTML) for futher details.

IRIX
JDK 1.3.1 is supported.
HP-UX
Java (JDK 1.3.1) is not currently supported. Please contact SICStus support if you need Jasper for this platform.
Other platforms
JDK 1.3.x appears to be mature enough and widespread enough to make it feasible to support on other SICStus platforms as well, if required. Your input on this issue is much appreciated, especially if you are familiar with linker issues and JDK installation on the platform in question.


Node:Getting Started, Next:, Previous:Supported Java Versions, Up:Jasper Notes

Getting Started

This section describes some tips and hints on how to get the interface started. This is actually where most problems occur.


Node:Windows, Next:, Previous:Getting Started, Up:Getting Started

Windows

Under Windows, you should add SICStus Prolog's and Java's DLL directories to your %PATH%. This will enable Windows library search method to locate all relevant DLLs. For SICStus, this is the same as where sicstus.exe is located, usually C:\Program Files\SICStus Prolog 3.10.0\bin. For Java, it is usually C:\jdk1.3.1\jre\bin\hotspot (for JDK 1.2.2 it would be C:\jdk1.2.2\jre\bin\classic).

For example (Windows NT/2000/XP):

set PATH=C:\jdk1.3.1\jre\bin\hotspot;%PATH%
set PATH=C:\Program Files\SICStus Prolog 3.10.0\bin;%PATH%


Node:UNIX, Next:, Previous:Windows, Up:Getting Started

UNIX

When library(jasper) is used to embed Java in a SICStus development system or run-time system, then the run-time linker needs to be told where to find the Java libraries (e.g. libjvm.so). During installation, InstallSICStus will build either the sicstus executable or the jasper foreign resource so that it contains the necessary information; the detail are platform dependent.

If you use spld to relink SICStus or to build a run-time system, you can use the command line option --resource=-jasper (note the minus sign). This tells spld to include the search path (rpath) in the executable needed to ensure that library(jasper) can find the Java libraries.

If you want to run sicstus with another Java than what was specified during installation, you can use spld without the --resources option to get a SICStus executable without any embedded Java paths. In this case, you need to set the environment variable LD_LIBRARY_PATH (or similar) appropriately. One example of this is to use the JDK 1.3 server version instead of the default (client) version.

Alternatively, you can use spld with the --resource=-jasper and --with-jdk=DIR options to generate a development system with embedded paths to another Java directory tree. This will only work if the alternative directory tree has the same structure as the JDK directory seen by InstallSICStus.


Node:Running Java from SICStus, Next:, Previous:UNIX, Up:Getting Started

Running Java from SICStus

If SICStus is used as parent application, things are usually really simple. Just execute the query | ?- use_module(library(jasper)).. After that, it is possible to perform meta-calls as described in Jasper Library Predicates.

On UNIX, you may encounter the following error message:

% sicstus
SICStus 3.8 (sparc-solaris-5.5.1): Wed Sep 22 08:42:14 MET DST 1999
Licensed to SICS
| ?- use_module(library(jasper)).
[...]
{SYSTEM ERROR: 'Attempted to load Java engine into sbrk\'d
SICStus system (try starting SICStus with -m option)'}
[...]

Since most platforms don't allow sbrk() and malloc() (or threads) to coexist peacefully, SICStus refuses to load the JVM if not the -m flag was given to SICStus. The message can, as the error message suggests, be avoided if SICStus is started with the -m flag:

% sicstus -m
The -m flag is not needed, and is ignored, on Windows.

When Jasper is used in run-time systems, additional constraints apply as described in Runtime Systems on Target Machines. The Java to SICStus interface relies on dynamically loading the SICStus run-time system. For this reason, it is not possible to use library(jasper) from an executable that links statically with the SICStus run-time.


Node:Running SICStus from Java, Previous:Running Java from SICStus, Up:Getting Started

Running SICStus from Java

If Java is used as parent application, things are a little more complicated. There are a couple of things which need to be taken care of. The first is to specify the correct class path so that Java can find the Jasper classes (SICStus, SPTerm, and so on). This is done by specifying the pathname of the file jasper.jar:

% java -classpath $SP_PATH/bin/jasper.jar ...

SP_PATH does not need to be set; it is only used here as a placeholder. See the documentation of the Java implementation for more info on how to set classpaths.

The second is to specify where Java should find the Jasper native library (libspnative.so or spnative.dll), which the SICStus class loads into the JVM by invoking the method System.loadLibrary("spnative"). The loadLibrary method uses a platform dependent search method to locate the Jasper native library, and quite often this method fails. A typical example of such a failure looks like:

% java -classpath [...]/jasper.jar se.sics.jasper.SICStus
Trying to load SICStus.
Exception in thread "main" java.lang.UnsatisfiedLinkError: no spnative
in java.library.path
	at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1133)
	at java.lang.Runtime.loadLibrary0(Runtime.java:470)
	at java.lang.System.loadLibrary(System.java:745)
	at se.sics.jasper.SICStus.loadNativeCode(SICStus.java:37)
	at se.sics.jasper.SICStus.initSICStus(SICStus.java:80)
	at se.sics.jasper.SICStus.<init>(SICStus.java:111)
	at se.sics.jasper.SICStus.main(SICStus.java:25)

On UNIX, this can be fixed by explicitly setting the Java property java.library.path to the location of libspnative.so, like this:

% java -Djava.library.path=/usr/local/lib [...]

On Windows, Java must be able to find spnative.dll through the PATH environment variables and setting -Djava.library.path can lead to problems if multiple versions of SICStus has been installed.

If this works properly, SICStus should have been loaded into the JVM address space. The only thing left is to tell SICStus where the (extended) runtime library, sprt.sav (spre.sav), is located. On those platforms where the SICStus run-time system can determine its own location, e.g. Windows, Solaris and Linux, the run-time system will find the runtime library automatically. Otherwise, you may choose to specify this explicitly by either giving a second argument when initializing the SICStus object or by specifying the property sicstus.path:

Example (UNIX):

% java -Dsicstus.path=/usr/local/lib/sicstus-3.10.0

If you do not specify any explicit path, SICStus will search for the runtime library itself.

If everything is set up correctly, you should be able to call main (which contains a short piece of test-code) in the SICStus root class, something like this:

% java -Djava.library.path="/usr/local/lib" \
       -Dsicstus.path="/usr/local/lib/sicstus-3.10.0" \
       -classpath "/usr/local/lib/sicstus-3.10.0/bin/jasper.jar" \
        se.sics.jasper.SICStus
Trying to load SICStus.
If you see this message, you have successfully
initialized the SICStus Prolog engine.

On Windows, it would look something like this, depending on the shell used:

% java -classpath "C:/Program Files/SICStus Prolog 3.10.0/bin/jasper.jar" se.sics.jasper.SICStus
Trying to load SICStus.
If you see this message, you have successfully
initialized the SICStus Prolog engine.

If more than one se.sics.jasper.SICStus instance will be created, then the SICStus run-times named e.g. libsprt310_instance_01_.so, need to be available as well. See Runtime Systems on Target Machines.


Node:Jasper Package Options, Next:, Previous:Getting Started, Up:Jasper Notes

Jasper Package Options

The following Java system properties can be set to control some features of the Jasper package:

se.sics.jasper.SICStus.checkSPTermAge
This flag is unsupported.

A boolean, true by default. If true, then run-time checks are performed that attempt to detect potentially dangerous use of the SPTerm.putXXX family of functions. The value of this flag can be set and read with SICStus.setShouldCheckAge() and SICStus.shouldCheckAge(). This flag was false by default in SICStus 3.8.

The run-time checks throws an IllegalTermException when there is risk that a SPTerm is set to point to a Prolog term strictly newer than the SPTerm. In this context strictly newer means that there exists an open query that was opened after the SPTerm object was created but before the Prolog term. See SPTerm and Memory, for more information.

java -Dse.sics.jasper.SICStus.checkSPTermAge=true ...
or, from Prolog:
jasper_initialize(
   ['-Dse.sics.jasper.SICStus.checkSPTermAge=true'],
   JVM)

se.sics.jasper.SICStus.reuseTermRefs
This flag is unsupported.

A boolean, on by default. If false, then SPTerm.delete() will only invalidate the SPTerm object, it will not make the Prolog side term-ref available for re-use. The value of this flag can be set and read with SICStus.setReuseTermRefs() and SICStus.reuseTermRefs(). There should be no reason to turn it off.

To set this flag do:

java -Dse.sics.jasper.SICStus.reuseTermRefs=true ...
or, from Prolog:
jasper_initialize(
   ['-Dse.sics.jasper.SICStus.reuseTermRefs=true'],
   JVM)

se.sics.jasper.SICStus.debugLevel
This flag is unsupported.

You probably should not use it in production code. It may be removed or change meaning in future releases.

An integer, zero by default. If larger than zero, then some debug info is output to System.out. Larger values produce more info. The value of this flag can be set and read with SICStus.setDebugLevel() and SICStus.debugLevel().

java -Dse.sics.jasper.SICStus.debugLevel=1 ...
or, from Prolog:
jasper_initialize(
   ['-Dse.sics.jasper.SICStus.debugLevel=1'],
   JVM)


Node:Multi threading, Next:, Previous:Jasper Package Options, Up:Jasper Notes

Multi threading

Some exceptions thrown in multi threaded mode may be removed in the future. The user should never catch specific exceptions, but instead catch instances of PrologException.

See Known Bugs and Limitations in Jasper, for details on the limitations of multi threaded Jasper.


Node:Known Bugs and Limitations in Jasper, Next:, Previous:Multi threading, Up:Jasper Notes

Known Bugs and Limitations in Jasper


Node:Java Examples Directory, Next:, Previous:Known Bugs and Limitations in Jasper, Up:Jasper Notes

Java Examples Directory

There is an examples directory available in $SP_PATH/library/jasper/examples. See the file README for more info.


Node:Java Resources Online, Previous:Java Examples Directory, Up:Jasper Notes

Resources

There are almost infinitely many Java resources on the Internet. Here is a list of a few which are related to Jasper and JNI.


Node:Visual Basic notes, Next:, Previous:Jasper Notes, Up:Top

Visual Basic notes

The Visual Basic - SICStus Prolog interface consists of the following files:

In order to use the interface, perform the following steps:


Node:Berkeley DB notes, Next:, Previous:Visual Basic notes, Up:Top

Berkeley DB notes

As of SICStus 3.8, the library module library(db) has been replaced by library(bdb). The functionality is similar, but library(bdb) is built on top of Berkeley DB. Berkeley DB can be downloaded from:

http://www.sleepycat.com

library(bdb) has been verified to work using Berkeley DB version 4.1.24. It does not work with earlier versions.

When using Berkeley DB on Windows, you should set the PATH environment variable to contain the path to libdb40.dll. Consult the Berkeley DB documentation for further info.


Node:The Emacs Interface, Next:, Previous:Berkeley DB notes, Up:Top

The Emacs Interface

The Emacs Interface was originally developed for GNU Emacs 19.34 and is presently being maintained using XEmacs 21.1 and tested with GNU Emacs 19.34.1. For best performance and compatibility and to enable all features we recommend that the latest versions of GNU Emacs or XEmacs are used. For information on obtaining GNU Emacs or XEmacs; see http://www.gnu.org and http://www.xemacs.org, respectively.


Node:Installing the Emacs Interface, Previous:The Emacs Interface, Up:The Emacs Interface

Installation

Starting with SICStus 3.8, the Emacs interface is distributed with SICStus and installed by default. The default installation location for the emacs files is <prefix>/lib/sicstus-3.10.0/emacs/ on UNIX platforms and C:\Program Files\SICStus Prolog 3.10.0\emacs\ on Windows.

For maximum performance the Emacs Lisp files (extension .el) should be compiled. This can be done from within Emacs with the command M-x byte-compile-file. See Installation, for further details.


Node:Installing On-Line Documentation, Previous:Installing the Emacs Interface, Up:Installing the Emacs Interface

Installing On-Line Documentation

It is possible to look up the documentation for any built in or library predicate from within Emacs (using C-c ? or the menu). For this to work Emacs must be told about the location of the info-files that make up the documentation. This can be done for the entire emacs installation or on a per user basis; see Installation, for further details.

The default location for the info-files are <prefix>/lib/sicstus-3.10.0/doc/info/ on UNIX platforms and C:\Program Files\SICStus Prolog 3.10.0\doc\info\ on Windows.

More recent versions of GNU Emacs and XEmacs should be able to automatically incorporate info files from a subdirectory into the main Info documentation tree. It is therefore recommended that the SICStus Info files are kept together in their own directory.


Node:Revision history, Next:, Previous:The Emacs Interface, Up:Top

Revision history

This chapter summarizes the changes in release 3 wrt. previous SICStus Prolog releases as well as changes introduced by patch releases.


Node:Changes in release 3, Next:, Previous:Revision history, Up:Revision history

Changes in Release 3


Node:Changes introduced in 3#4, Next:, Previous:Changes in release 3, Up:Revision history

Changes Introduced in 3#4


Node:Changes introduced in 3#5, Next:, Previous:Changes introduced in 3#4, Up:Revision history

Changes Introduced in 3#5


Node:Changes introduced in 3#6, Next:, Previous:Changes introduced in 3#5, Up:Revision history

Changes Introduced in 3#6


Node:Changes introduced in version 3.7, Next:, Previous:Changes introduced in 3#6, Up:Revision history

Changes Introduced in Version 3.7


Node:Changes introduced in version 3.7.1, Next:, Previous:Changes introduced in version 3.7, Up:Revision history

Changes Introduced in Version 3.7.1


Node:Changes introduced in version 3.8, Next:, Previous:Changes introduced in version 3.7.1, Up:Revision history

Changes Introduced in Version 3.8


Node:3.8 WCX, Next:, Previous:Changes introduced in version 3.8, Up:Changes introduced in version 3.8

Wide Character Support

Wide character handling is introduced, with the following highlights:

For programs using the default ISO_8859_1 character set, the introduction of wide characters is transparent, except for the string format change in the foreign interface; see below.

In programs using the EUC character set, the multibyte EUC characters are now input as a single, up to 23 bit wide, character code. This character code can be easily decomposed into its constituent bytes, if needed. The encoding function is described in detail in the SICStus manual.

To support wide characters, the foreign interfaces now use UTF-8 encoding for strings containing non-ASCII characters (codes >= 128). This affects programs with strings that contain e.g. accented characters and which transfer such strings between Prolog and C. If such a string is created on the C side, it should be converted to UTF-8, before passing it to Prolog. Similarly for a string passed from Prolog to C, if it is to be decomposed into characters on the C side, the inverse transformation has to be applied.

Utility functions SP_code_wci and SP_wci_code are provided to support the conversion of strings between the WCI (Wide Character Internal encoding, i.e. UTF-8) format and wide character codes.


Node:3.8 Debugger, Next:, Previous:3.8 WCX, Up:Changes introduced in version 3.8

Breakpointing Debugger

A new general debugger is introduced, with advanced debugging features and an advice facility. It generalizes the notion of spypoint to that of the breakpoint. Breakpoints make it possible to e.g. stop the program at a specified line, or in a specified line range, or to call arbitrary Prolog goals at specified ports, etc. Highlights:


Node:3.8 ISO, Next:, Previous:3.8 Debugger, Up:Changes introduced in version 3.8

ISO Compliance

SICStus 3.8 supports standard Prolog, adhering to the International Standard ISO/IEC 13211-1 (PROLOG: Part 1--General Core). At the same time it also supports programs written in earlier versions of SICStus. This is achieved by introducing two execution modes iso and sicstus. Users can change between the modes using the Prolog flag language. Main issues:


Node:3.8 Generic, Next:, Previous:3.8 ISO, Up:Changes introduced in version 3.8

Generic New Features


Node:3.8 Jasper, Next:, Previous:3.8 Generic, Up:Changes introduced in version 3.8

New Features in library(jasper)


Node:3.8 CLPFD, Next:, Previous:3.8 Jasper, Up:Changes introduced in version 3.8

New Features in library(clpfd)


Node:3.8 Bugs, Previous:3.8 CLPFD, Up:Changes introduced in version 3.8

Bugs Fixed in Version 3.8


Node:Changes introduced in version 3.8.1, Next:, Previous:Changes introduced in version 3.8, Up:Revision history

Changes Introduced in Version 3.8.1

Version 3.8.1 is a bugfix release only, no new features has been added.


Node:Changes introduced in version 3.8.2, Next:, Previous:Changes introduced in version 3.8.1, Up:Revision history

Changes Introduced in Version 3.8.2

Version 3.8.2 is a bugfix release only, no new features has been added.


Node:Changes introduced in version 3.8.3, Next:, Previous:Changes introduced in version 3.8.2, Up:Revision history

Changes Introduced in Version 3.8.3

Version 3.8.3 is mainly a bugfix release. New features:

Bug fixes:


Node:Changes introduced in version 3.8.4, Next:, Previous:Changes introduced in version 3.8.3, Up:Revision history

Changes Introduced in Version 3.8.4

Version 3.8.4 is mainly a bugfix release. New features:

Bug fixes:


Node:Changes introduced in version 3.8.5, Next:, Previous:Changes introduced in version 3.8.4, Up:Revision history

Changes Introduced in Version 3.8.5

Version 3.8.5 is mainly a bugfix release. New features:

Bug fixes:


Node:Changes introduced in version 3.8.6, Next:, Previous:Changes introduced in version 3.8.5, Up:Revision history

Changes introduced in version 3.8.6

Version 3.8.6 is mainly a bugfix release. New features:

Bug fixes:


Node:Changes introduced in version 3.8.7, Next:, Previous:Changes introduced in version 3.8.6, Up:Revision history

Changes introduced in version 3.8.7

Version 3.8.7 is mainly a bugfix release. New features:

Bugs fixed:


Node:Changes Introduced in Version 3.9, Next:, Previous:Changes introduced in version 3.8.7, Up:Revision history

Changes Introduced in Version 3.9


Node:3.9 Message and Query System, Next:, Previous:Changes Introduced in Version 3.9, Up:Changes Introduced in Version 3.9

Message and Query System

Every message issued by the Prolog system is displayed using the built-in predicate print_message/2. Similarly, all user input is handled by the new built-in predicate ask_query/4. The behavior of these predicates can be customized by a number of new hooks. For example, all I/O can be redirected from the standard streams to Tcl/Tk or similar windows. The default appearance of system messages has also changed.

The mapping from Prolog terms representing messages to printed messages is now completely transparent and customizable. The new library('SU_messages') file defines the mapping rules. Runtime systems can display system messages in standard format by loading this file.

A number of new hooks have been added for the message and query system: generate_message_hook/3, generate_message/3, message_hook/3, print_message_lines/3, query_hook/6, query_class_hook/5, query_input_hook/3, query_map_hook/4.

See Messages and Queries.


Node:3.9 Determinacy Checker, Next:, Previous:3.9 Message and Query System, Up:Changes Introduced in Version 3.9

Determinacy Checker

The determinacy checker, spdet, is a new, powerful tool originally written by Dave Bowen and Peter Schachte.

The determinacy checker can help you spot unwanted nondeterminacy in your programs. This tool examines your program source code and points out places where unintended nondeterminacy may arise. Unintended nondeterminacy should be eradicated because

  1. it may give you wrong answers on backtracking
  2. it may cause a lot of memory to be wasted

See The Determinacy Checker.


Node:3.9 Cross-Referencer, Next:, Previous:3.9 Determinacy Checker, Up:Changes Introduced in Version 3.9

Cross-Referencer

library(xref) of previous releases has been replaced by a much more powerful tool, spxref, originally written by Tom Howland.

The main purpose of the cross-referencer is to find unreachable code. To this end, it begins by looking for a definition for user:runtime_entry/1 and also looks for initializations, hooks, module export lists and public directives to start tracing the reachable code from.

A second function is to aid in the formation of module statements. It can list all of the required module/2 and use_module/2 statements by file.

See The Cross-Referencer.


Node:3.9 Microsoft COM Client, Next:, Previous:3.9 Cross-Referencer, Up:Changes Introduced in Version 3.9

Common Object Model Client

On Windows, library(comclient) makes it possible to control COM Automation objects. See COM Client.


Node:3.9 PiLLoW Web Programming Library, Next:, Previous:3.9 Microsoft COM Client, Up:Changes Introduced in Version 3.9

The PiLLoW Web Programming Library

The PiLLoW library is a free Internet/WWW programming library which simplifies the process of writing applications for such environment. The library provides facilities for generating HTML or XML structured documents by handling them as Prolog terms, producing HTML forms, writing form handlers, processing HTML templates, accessing and parsing WWW documents (either HTML or XML), accessing code posted at HTTP addresses, etc. See PiLLoW.


Node:3.9 New CLPFD Features, Next:, Previous:3.9 PiLLoW Web Programming Library, Up:Changes Introduced in Version 3.9

New CLPFD Features

Generally, performance has been improved, in terms of CPU time as well as memory. Specific new features:


Node:3.9 All-in-one Executables, Next:, Previous:3.9 New CLPFD Features, Up:Changes Introduced in Version 3.9

All-in-one Executables

It is now possible to embed saved states into an executable. Together with static linking, this gives an executable which does not depend on external SICStus files. See All-in-one Executables.


Node:3.9 Multiple SICStus in a Process, Next:, Previous:3.9 All-in-one Executables, Up:Changes Introduced in Version 3.9

Multiple SICStus Run-Times in a Process

It is now possible to have more than one SICStus run-time in a single process. See Multiple SICStus Run-Times, for details.


Node:3.9 Miscellaneous, Next:, Previous:3.9 Multiple SICStus in a Process, Up:Changes Introduced in Version 3.9

Miscellaneous


Node:3.9 Incompatibilities, Next:, Previous:3.9 Miscellaneous, Up:Changes Introduced in Version 3.9

Incompatibilities with Previous Versions


Node:3.9 Bugs Fixed, Next:, Previous:3.9 Incompatibilities, Up:Changes Introduced in Version 3.9

Bugs Fixed in 3.9.0


Node:3.9 Known Problems, Previous:3.9 Bugs Fixed, Up:Changes Introduced in Version 3.9

Known Problems with This Release


Node:Changes Introduced in Version 3.9.1, Next:, Previous:Changes Introduced in Version 3.9, Up:Revision history

Changes Introduced in Version 3.9.1

Version 3.9.1 is mainly a bugfix release. New features:

Other changes:

Bugs fixed:


Node:Changes Introduced in Version 3.10.0, Previous:Changes Introduced in Version 3.9.1, Up:Revision history

Changes Introduced in Version 3.10.0


Node:New Features 3.10.0, Next:, Up:Changes Introduced in Version 3.10.0

New Features


Node:Bugs Fixed 3.10.0, Next:, Previous:New Features 3.10.0, Up:Changes Introduced in Version 3.10.0

Bugs Fixed


Node:Other Changes 3.10.0, Previous:Bugs Fixed 3.10.0, Up:Changes Introduced in Version 3.10.0

Other Changes


Node:Generic limitations, Next:, Previous:Revision history, Up:Top

Generic limitations

On 32-bit architectures, the total size of the Prolog stacks cannot exceed 256 MB. Under Linux, the default placement of the TEXT segment constrains the Prolog stack address range, so in practice the limit there is 128 MB unless the spld option --more-memory is used.

The number of arguments of a compound term may not exceed 255.

The number of atoms created may not exceed 262143 (33554431) on 32-bit (64-bit) architectures.

The number of characters of an atom may not exceed 65535.

NUL is not a legal character in atoms.

There are 256 "temporary" and 256 "permanent" variables available for compiled clauses.

Saved states are not portable between 32-bit and 64-bit architectures, or from a system built with native code support to a system without native code support for the same architecture.

Indexing on big integers or floats is coarse.


Node:Questions and answers, Previous:Generic limitations, Up:Top

Questions and answers

Current support status for the various platforms can be found at the SICStus Homepage:

http://www.sics.se/sicstus/

Information about and fixes for bugs which have shown up since the latest release can be found there as well.

Send requests for ordering information to

sicstus-request@sics.se

Report bugs through the web interface

http://www.sics.se/sicstus/bugreport/bugreport.html.
or to
sicstus-support@sics.se

Bugs tend actually to be fixed if they can be isolated, so it is in your interest to report them in such a way that they can be easily reproduced.

The mailing list sicstus-users@sics.se is a mailing list for communication among users and implementors. To subscribe, write a message to majordomo@sics.se with the following line in the message body:

subscribe sicstus-users

Table of Contents