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:

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:

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.

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

    Flags controlling arithmetic

    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.

     

    Copyright ©1987-2011 Amzi! inc. All Rights Reserved. Amzi! is a registered trademark and Logic Server is a trademark of Amzi! inc.