Amzi! Runtime

The Amzi! runtime comes in many forms.

As a built-in component of the Amzi! tools, including A4LIS and IDE.
As a standalone executable runtime that can be executed from the command-line, A4RUN.
As Windows dynamic libraries, AMZI4.DLL or AMZI4C.DLL
As Unix libraries, AMZI4.A or LIBAMZI4.SO.

A4RUN, in whatever form, executes XPL files. This section discusses how to use A4RUN directly, and the operational parameters of the runtime system.

Understanding its behavior is key to using the listener and compiler successfully because they are also Amzi! applications (XPL files).

(The source code for A4RUN is included in the 'source' subdirectory. It is a relatively simple example of a C program with an embedded Prolog engine. It determines the name of a Prolog program to run, and fires up the engine and runs it.)

Running A4RUN from the Command-Line

A4RUN can be used in two ways. You can run it directly and specify the name of the XPL file to execute as a parameter:

c>  a4run wgene

You can also copy A4RUN to the same name as your application. In this case the XPL file with the same name as the EXE will be executed:

c>  copy a4run.exe wgene.exe
c>  wgene

Initialization Files

INI files give you the ability to customize your working environment on an application-by-application basis, most notably in deciding which runtime to use and what stacks to set. The INI files give you three layers of defaults.

The system as shipped has default values for stacks and the like that it uses if no INI files are found.
The system looks first for a file called AMZI4.INI. This is your tool for overriding the built-in system defaults.
When an application runs, it first looks for a INI file with the same name as the application (XPL file). If one exists, it is used to override the system defaults, either as set by you or built into the system.

A INI file is composed of lines of the form

parameter = value

Comment lines begin with either "%" or ";".

INI parameters can also be set from a host language program via arguments, rather than through a INI file. To do this, use the entry point lsInit2() rather than lsInit(), with the argument being the parameters in character string format.

INI Parameters

These parameters affect the various control stacks used during Prolog program execution.

heap -- The number of cells (4-bytes each) in the Prolog heap stack.

local -- The number of cells in the local stack.

control -- The number of cells in the control stack.

trail -- The number of cells in the trail stack.

heapbumper -- The percentage of the heap used as a garbage collection buffer.

These parameters affect the size of Prolog terms that can be read, by either the listener, compiler, or any other Prolog program.

readbuffer -- The maximum size in bytes of a term or a string.

readdepth -- The degree of complexity of a term.

maxvars -- The maximum number of variables in a term.

These parameters affect the maximum number of clauses allowed in a single predicate for compiled Prolog.

maxclauses -- The maximum number of compiled clauses that can be loaded as part of one predicate.

destbuf -- The size of the internal buffer used to hold the loaded version of a compiled predicate.

srcbuf -- The size of the internal buffer used to hold the preloaded version of a compiled predicate.

Other system paramters.

maxatoms -- The size of the atom table in 1K (1024 atoms) blocks; must be a power of 2 between 1 and 32.

maxmem -- If non-zero, this sets an upper bound on the amount of memory Prolog can allocate in 1K byte multiples. If Prolog tries to get more memory, it will garbage collect, hoping to free up some memory already allocated, and if it still can't find the memory it needs, it will abort. If zero, there is no limit, except available memory.

thingblksz -- The maximum size (in entries) of a block of memory that will be allocated for pointers to strings, floats, database objects, etc. Normally, the default should be sufficient, but if you have a large number of strings, you may want to increase this value to the maximum limit of 16,000 entries. The system will allocate up to 256 such blocks of thingblksz entries.

string_esc -- On or off, depending on whether or not you want to enable escape character processing in quoted atoms, character lists and strings.

verbose -- On or off, depending on whether or not you want verbose messages about garbage collection.

logfile -- Specifies the name of a log file and turns logging on. This parameter makes it possible to log a program's behavior without changing the program.

lsxload -- If you want to load .LSX files either in the IDE or your application, you use this parameter to list the names of the files to be loaded.

apitrace -- On or off, outputs the Logic Server API parameters and return values. You must specify a logfile for the trace to be written to..

If you specify apitrace in AMZI4.INI, then you'll catch errors in the lsInit() call if there are any. If you specify it in MYPROG.INI, where MYPROG is the name of your XPL file, you'll get trace information as long as the initialization competed OK.

Default INI Values

The system defaults differ for each of the runtimes

Parameter	Abbrev- iation	Default Value 32-bit	Default Value 64-bit
Stacks
heap =	h	100,000	100,000
control =	c	20,000	20,000
local =	l	20,000	20,000
trail =	t	10,000	10,000
heapbumper =	hb	10	10
Term Size
readbuffer =	rb	4,096	4,096
readdepth =	rd	256	256
maxclauses =	mc	500	500
maxvars =	mv	256	256
Load Limits
destbuf=	db	60,000	60,000
srcbuf=	sb	30,000	30,000
System Limits
maxatoms =	ma	4	8
maxmem =	mm	0	0
thingblksz =	tb	16,000	16,000
Modes
string_esc =	se	on	on
Miscellaneous
logfile =	lf	null	null
apitrace =	at	off	off
lsxload=	ll	null	null

Modes

A mode in Amzi! Prolog is a software switch whose setting influences the way a Prolog program will respond to conditions which arise during its execution. Modes are either on or off. Conditions which are handled include:

Error handling
Garbage collection
Lint checking
Compiled predicate protection
Escape character processing

Amzi! Prolog supports a number of modes which can be turned on or off. The behavior of Prolog is modified according to which modes are on or off. To turn a mode on:

set_mode(Mode, on | off)

To check the status of a mode:

get_mode(Mode, Var)

The modes supported by Prolog are as follows:

Mode	Function	Default
fatal_errors	selects reset or abort	off
file_errors	selects fail or error handler	on
protect_db	protects compiled clauses	off
string_esc	escape character processing	on
verbose	monitor garbage collection	off

fatal_errors

On: If a hard error occurs then the Prolog will be exited after a message is displayed.
Off: If a hard error occurs then the error message is displayed and, the system waits until you press the [Esc] key, and then a reset takes place.

file_errors

On: An error manipulating a file (fopen, fclose etc.) will cause the error to be raised and trapped by the handler.
Off: An error manipulating a file will simply cause the predicate to fail.

A useful application can be found in the following example (remember X -> Y ; Z means if X then Y else Z).

file_exists(F) :- 
  fileerrors(X),              % get old file error mode
  nofileerrors,               % file errors fail
  (see(F) ->                  % is it there ? 
    (seen, fileerrors(X)) ;   % yes succeed   
    (fileerrors(X), fail)     % no - fail
  ). 
% in both cases restore fileerrors to original mode

Note that if file_errors were on when see(F) was invoked then absence of file F would cause an error; here it just fails.

protect_db

On: If protect_db mode is active when compiled code is loaded then all the predicates in the compiled file will be protected. This means that they cannot be modified or abolished. Any attempt to modify protected compiled clauses will result in an error being raised.
Off: Compiled clauses are not protected when loaded.

All the predicates in the standard library are always protected, to prevent you from accidentally redefining a standard predicate.

string_esc

On: Enables the processing of escape characters (those following a backslash) in quoted atoms, character lists and strings.
Off: Disables escape character processing.

verbose

On: Turns the 25th line of the screen into a transient window which will pop up during garbage collection, indicate how much space was collected and then vanish.
Off: Garbage collections occur quietly.