Amzi! Runtime

The Amzi! runtime comes in many forms.

Arun, in whatever form, executes .xpl Files. This section discusses how to use arun 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 arun 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 arun from the Command-Line

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

You can also copy arun to the same name as your application. In this case the .xpl file with the same name as the .exe will be executed:

Configuration Files

Configuration files (.cfg) 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 .cfg files give you three layers of defaults.

  1. The system as shipped has default values for stacks and the like that it uses if no .cfg files are found.
  2. The system looks first for a file called amzi.cfg. This is your tool for overriding the built-in system defaults.
  3. When an application runs, it first looks for a .cfg 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 .cfg file is composed of lines of the form

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

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

Configuration 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 amzi.cfg, then you'll catch errors in the lsInit() call if there are any. If you specify it in myprog.cfg, where myprog is the name of your .xpl file, you'll get trace information as long as the initialization competed OK.

    Default .cfg 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:

    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:

    To check the status of a mode:

    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).

    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.

    Copyright ©1987-2000 Amzi! inc. All Rights Reserved.