Amzi! Runtime

The Amzi! runtime engine is a shared library, amzi.dll under Windows and libamzi.so under Unix. Amzi! Prolog is always run by a host language program that loads and starts the runtime engine.

Arun is a command line interface to the engine that simply loads a compiled Prolog file (.xpl file) and calls its main/0 predicate. Arun is, therefore, the tool to use for running stand-alone command line Prolog programs.

The source code for arun is included in the Amzi! src directory.

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:

c>  arun wgene

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:

c>  copy arun.exe wgene.exe
c>  wgene

The command line listener, alis, and compiler, acmp, are examples of this. Both of these development tools are Prolog programs.

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.

The system as shipped has default values for stacks and the like that it uses if no .cfg files are found.
The system looks first for a file called amzi.cfg. This is your tool for overriding the built-in system defaults.
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

parameter = value

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. Many of the parameters have abbreviations which might be easier to use when using lsInit2. They are in () after the parameter name.

Configuration Parameters

These parameters affect the various control stacks used during Prolog program execution. A Prolog cell is a small internal unit that holds Prolog primitives, such as atoms, numbers, and list and structure elements.

heap (h) -- The number of cells in the Prolog heap stack.

local (l) -- The number of cells in the local stack.

control (c) -- The number of cells in the control stack.

trail (t) -- The number of cells in the trail stack.

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

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

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

readdepth (rd) -- The degree of complexity of a term.

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

These parameters that aid in debugging.

logfile (lf) -- 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.

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

debug_host -- Specifies either the IP address or host name of the machine running Eclipse when using the Remote Debugger. Default is 127.0.0.1.

debug_port -- Specifies the port number for the machine running the Eclipse Remote Debugger. Default is 8000.

Other system parameters.

occurs_check (oc) -- Attempts to unify cyclic terms can lead to hard crashes of the Prolog engine. An example would be ?- A = f(A), B = f(B), A = B. The default is off because: 1) this sort of construct rarely occurs; 2) many cyclic unifications are caught on output, such as simply ?- A = f(A). ; and 3) there is a 10% performance overhead to add the check. But sometimes it's nice to have.

double_quote_strings (dqs) -- Strings are normally delimited by backquotes (`) in Prolog, and doublequotes (") are used as a shorthand for lists of characters, useful for parsing applications. However, for some applications where non-programmers are entering data for Prolog applications, it is desirable to allow the use of the more common doublequotes (") for delimiting strings. When this flag is on, that happens, and there is no special syntax for character lists. The default is off.

preprocessor (prep) -- The Amzi! preprocessor can be dynamically turned on and off using this flag. The default is off.

string_esc (se) -- For strings and atoms, the backslash (\), called an escape character, is used to denote special characters, such as a newline (\n). If a \ is desired as a real \, then \\ is used. This use of \ can be turned off, so that a \ is a \ by setting this flag to off. This is especially useful for applications that parse Windows path names. The default is on.

upper_case_atoms (uca) -- For applications where non-programmers are entering data for Prolog applications, the syntactical use of upper case for variables can be confusing. This flag changes the Prolog reader to accept both lower and upper case letters as legitimate starting characters for atoms. When this flag is on, the only way to represent a variable is with a leading underscore (_). The default is off.

decimals (dn) -- The type of number used to store non-explicit decimals, such as 43.56. The choices are real, for infinite-precision real numbers, or float for floating point numbers. The default is float.

floats (fl) -- The precision of floating point number to use for floats. The choices are single (faster less-precise) or double (slower more-precise). The default is single.

decimal_places (dp) -- The number of decimal places to display on write statements. A value of -1 is the default, which means display all available places. Does not affect writeq statements, which display all available decimal places.

lsxload (ll) -- 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. Multiple names should be separated by a semicolon (;) with NO spaces. NOTE - These will only be loaded if the host application calls LoadLSX. This is done in the Amzi! IDE, alis, acmp and arun, so you can load LSX files for use in the development tools. For your own host language application, be sure to include the call to LoadLSX.

macroheapsz (mh) -- If you are using large complex macros, this parameter may need to be increased.

gcthingfreq (gcf) -- Some internal quantities take up additional memory, such as strings, double precision and very large real numbers. These entities are garbage collected after the number created exceeds this parameter.

maxfiles (mf) -- The maximum number of compiled files that can be loaded.

maxclauses (mf) -- The maximum number of clauses a static (compiled) non-discontiguous predicate can have. Note that compiled predicates declared discontiguous will be broken up into smaller blocks of static (compiled) clauses that fit within the maxclauses limit.

maxmemory (mm) -- Unix only, the maximum memory allowed for the Amzi! process, specified in Megabytes.

vars_sort_equal(vse) -- Variables can be sorted as equals or by internal storage address. A value of on, means sort as equals, off means sort by address.

undefined_predicate(up) -- Calls to undefined predicates can either fail or throw an error. The values are fail and error, with fail being the default.

utf8io -- Sets the I/O to and from the engine to UTF-8. Userful for Internet applications.

Default .cfg Values

The system defaults are listed in the commented out lines for each parameter in the distributed amzi.cfg file.

Flags

Like the configuration parameters, flags relate to various runtime parameters of Amzi! Prolog. But flags can be queried, and in some cases set, directly from Prolog.

A flag are queried and set using two built-in predicates:

current_prolog_flag(FLAG, VALUE)

current_prolog_flag/2 returns the value of a given flag name, FLAG. If FLAG is a variable, current_prolog_flag/2 will backtrack through all of the flags.

set_prolog_flag(FLAG, VALUE)

set_prolog_flag/2 sets the value of the named flag, FLAG.

Configuration Flags

All of the configuration parameters can be queried as flags. Some can also be set and they are listed with the settable flags below.

Settable Flags

The following flags can be dynamically set:

Flags controlling Prolog parsing, sorting and I/O

locale -- A string representing the geographic locale setting used. The locale is initially set to the default locale for the operating system being used. To set the locale, provide a value that is a string representing the locale. Example:
```
set_prolog_flag(locale, `English`)
```
To reset to the system's default locale, provide an empty string (``) as a value.
occurs_check -- Attempts to unify cyclic terms can lead to hard crashes of the Prolog engine. An example would be ?- A = f(A), B = f(B), A = B. The default is off because: 1) this sort of construct rarely occurs; 2) many cyclic unifications are caught on output, such as simply ?- A = f(A). ; and 3) there is a 10% performance overhead to add the check. But sometimes it's nice to have.
double_quote_strings -- Strings are normally delimited by backquotes (`) in Prolog, and doublequotes (") are used as a shorthand for lists of characters, useful for parsing applications. However, for some applications where non-programmers are entering data for Prolog applications, it is desirable to allow the use of the more common doublequotes (") for delimiting strings. When this flag is on, that happens, and there is no special syntax for character lists. The default is off.
preprocessor -- The Amzi! preprocessor can be dynamically turned on and off using this flag. The default is on.
string_esc -- For strings and atoms, the backslash (\), called an escape character, is used to denote special characters, such as a newline (\n). If a \ is desired as a real \, then \\ is used. This use of \ can be turned off, so that a \ is a \ by setting this flag to off. This is especially useful for applications that parse Windows path names. The default is on.
upper_case_atoms -- For applications where non-programmers are entering data for Prolog applications, the syntactical use of upper case for variables can be confusing. This flag changes the Prolog reader to accept both lower and upper case letters as legitimate starting characters for atoms. When this flag is on, the only way to represent a variable is with a leading underscore (_). The default is off.
vars_sort_equal -- Variables can either be sorted as equals or by internal storage location. A value of on means sort as equals, off means sort by location. The default is off.
undefined_predicate -- What happens when you try to execute an undefined predicate. A value can either be fail or error. The default is fail.
utf8io -- Sets the I/O from the engine to UTF-8. Useful for Internet applications. If there is a UTF-8 source file, this can be set using set_prolog_flag/2 in a directive at the beginning of the file so the characters are read in correctly.

Flags controlling arithmetic

decimals -- The type of number used for non-explicit decimals. For example, 1.1, 43.78, 0.6543. The choices are:
- real - Infinite precision real numbers.
- float - Floating point numbers.
floats -- The precision used for floating point numbers. The choices are:
- single - Single precision floats.
- double - Double precision floats.
decimal_places -- The number of decimal places displayed when writing numbers. -1 is the default, and means display all available decimal places. Does not affect writeq, which always displays all available decimal places.
epsilon -- The number of fractional decimal places of precision to use for internal real number series calculations that could exceed reasonable limits. In particular it affects the sqrt function and the power function for fractional numbers raised to large powers. It is expressed in as a negative exponent. For example a value of -18 means results are accurate to 10 ** (-18). Internally, it is stored as a power of gigadigits (base 10**9) so it is rounded to a multiple of 9. By default it is 0, which means power functions are exactly precise, no matter how many digits are required, and square root defaults to -72 digits.
delta -- When dividing two real numbers the precision of the answer might be a repeating decimal. In that case, 'delta' is used to determine how many of digits of precision to use. It is added to the maximum precision of either the numerator or denominator. The default is 18, so there are 18 digits of extra precision on divides. Internally, it is stored as a power of gigadigits (base 10**9) so it is rounded to a multiple of 9.
modulo -- If the modulo flag is non-zero and set to a prime number, then all integer arithmetic is performed modulo that number. See sections on prime numbers for more details.

Information Flags

The following flags can be queried. Some are part of the ISO standard to allow applications to make adjustments based on implementation-specific details, such as whether integers are bounded or not.

bounded -- Whether integers must lie in a bounded interval. The value depends on the flag decimals. If decimals = real, then integers are unbounded (infinite precision), otherwise they are bounded (constrained to the internal size of an integer, usually 32 bits).
char_conversion -- Whether a user defined routine can be used for transforming read unquoted characters. For Amzi! the value is 'off', meaning character conversion is not supported.
debug -- Whether the application is running in debug mode or not.
integer_rounding_function -- The behavior to expect from integer division (//) with regards to rounding the result. For Amzi! the value is 'toward_zero'.
max_arity -- The maximum arity of a structure. (255)
max_integer -- Since Amzi! is not bounded with respect to integers, the value of this ISO flag is 'not_applicable'.
min_integer -- Since Amzi! is not bounded with respect to integers, the value of this ISO flag is 'not_applicable'.
prolog_copyright -- The copyright for this Prolog.
prolog_date -- The date of the build.
prolog_name -- The name of this Prolog implementation.
prolog_version -- The version number.
unicode -- Whether the build supports Unicode (wide 16-bit) characters or not. For Amzi! the value is 'true'.