Environment files

Environment files are used to set initialization parameters for Arity/Prolog32 applications. These parameters are set to default values if no environment file exists for an application. Most applications will not require environment files, but you should understand what an environment file can specify and whether the default values are appropriate for your application.

If you want your program to run in the smallest amount of memory possible, you must first determine how much space the program requires. There is no sure way to determine the best settings ahead of time. However, there are ways to estimate how much space to allow. This is done by running the program with the default settings and then using the statistics/2 predicate to determine how much space was used at runtime. To determine how your program uses memory, add calls to the statistics/2 predicate at the end of your program (and other points as appropriate for understanding). Among the information that the statistics predicate returns is the maximum amount of stack space used by the program at runtime. Make note of this information. Once memory requirements are known, you can trim the sizes specified in the environment file closer to the amounts returned by statistics/2.

After determining the settings for your environment file, remove the call to statistics, recompile, and relink the application.

Note that the Arity/Prolog32 interpreter is itself an application which has its own environment file. Normally, you should run the interpreter with an environment file that contains only one parameter (VANILLA=YES), overriding a historical but largely obsolete default.

The environment file is accessed by your program at start-up. Therefore, you do not need to recompile your application if you create or change its environment file.

Creating an environment file

An environment file is simply a text file that specifies one parameter setting per line. If a parameter does not appear in the file, then the default value is used. If the file does not exist then all defaults are used. In addition to the environment file parameter settings, you can override defaults in the applications compiled startup code. The value in the environment file is the

You must follow these naming conventions:

• An environment file must have the file name extension .env.
• If your application does not include a module declaration, then the name of your environment file must be the same as the name of the file which includes the main entry point of your program. If your application includes a module declaration in the main module, then the environment file must have the same name as the name specified in the module declaration.

Each parameter has the format:

PARAMETER=value

The parameter specification must be uppercase. There cannot be any spaces between the equal sign and the parameter and value specifications. With the exception of the VANILLA and KBDRIVER parameters, the value may be typed in either uppercase or lowercase. These parameters must be uppercase.

Each of the parameters is explained in the sections that follow. For reference, a quick summary of values is provided here.

VANILLA=YES

Mode of Arity/Prolog32 interpreter; You must provide the value = YES

LOCAL=kilobytes

Local stack size in kilobytes; default = 1024

GLOBAL=kilobytes

Global stack size in kilobytes; default = 1024

LALARM=bytes

Local alarm level in bytes for gc; default = 2048

GALARM=bytes

Global alarm level in bytes for gc; default = 2048

DBMODE=never/always/maybe

Database loading type, choices are never, always, maybe; default = maybe

DATABASE=Filepath

Database file name; default is "application name".IDB

MINPAGES=pages

Minimum number of 4 kilobyte database cache pages; default = 4

MAXPAGES=pages

Maximum number of 4 kilobyte database cache pages; default = 1024

OVERFLOW=Dirpath

Overflow file directory; default is system TMP directory or current directory

KBDRIVER=YES/NO

Keyboard driver enable; default = YES

BUFSIZE=bytes

I/O buffer size in bytes; default = 2048

OPDEFSIZE=kilobytes

Operator space size in kilobytes, default = 3

Environment file parameters

Arity/Prolog32 Interpreter configuration

Local stack size

The local stack is a memory area that actually has two kinds of stack which grow from the top and the bottom toward the middle. The local stack is used for call frames which roughly correspond to the stack of a conventional language. The "trail" is a list of entries that represent pointers to memory that must be reset upon backtracking. Neither the call frames nor trail entries can be recovered by garbage collection. Both can be reclaimed during backtracking. The proper use of cuts (!) can have a dramatic impact on local stack consumption because an important effect of a cut (beside the elimination of unneeded choices and wasted execution time upon backtracking) is the re-use of local stack space.

Local stack size is given in kilobytes. The default number of kilobytes is 1024 which is probably far more than required by your program. (Earlier versions of Arity/Prolog set the default at only 64 which was often more than required!)

You should be aware that the interpreter is somewhat less efficient in its use of local stack space than compile code. The process of debugging consumes substantially more local stack space than ordinary interpretation.

The local stack size is specified using the following format:

LOCAL=kilobytes

Global stack size

The global stack is used as a kind of heap for instantiations of structures, including lists, as well as strings and floating-point numbers, and in some cases uninstantiated variables. If your application includes extensive use of lists or other large structures, then you will want to maintain a large global stack size.

Global stack space can be reclaimed whenever backtracking occurs. A garbage collector is used to reclaim no longer needed allocated space by marking what is actively referenced (directly or indirectly) and then compacting. You should be aware that like the local stack, interpreted code, particularly while debugging, may use substantially more global stack space than compiled code.

Global stack size is given in kilobytes with a default of 1024. Again, this is probably more than you require, particularly for compiled applications. (Earlier versions of Arity/Prolog set the default at 64.)

The global stack size is specified using the following format:

GLOBAL=kilobytes

Local and global alarm thresholds

If the amount of free local or global stack space falls below a specified threshold, garbage collection will be invoked. The thresholds are specified in bytes and for each threshold the default is 2048. If the threshold is set too low your program may crash. There is no downside to raising the alarm levels other than less effective use of the stacks and potentially more time spent by the application in garbage collection. Most well-written Prolog programs never or rarely need to garbage collect.

The local and global alarm thresholds are specified using the following formats:

LALARM=bytes
GALARM=bytes

The internal database file

Applications may be designed to run and may be deployed without any IDB file, even if those applications use database predicates. An environment file variable specifies the load behavior at startup for the application's internal database which can have one of three forms:

DBMODE=maybe

Load database if present (DEFAULT)

DBMODE=never

Never load database

DBMODE=always

Always load database - fail startup if not found

The IDB file name that is used at startup defaults to the name of the application with the .IDB extension. This name may be overridden by the DATABASE environment file variable. Thus, the default startup behavior for an application foo.exe is to search for a file foo.idb which is restored if found, or if not found, to start the application with an unnamed empty

The DATABASE file parameter indicates the name of the idb file and where the idb file can be found. Normally, the name given for this file is by convention the same as the main module name. If you use a module directive, then the idb name should be the same as that in the module directive.

The format for specifying the name and location of the internal database file is:

DATABASE=path_name.idb

The path indicates the directory in which the .idb file is stored. If you do not include the path then the system checks the directories specified in the PATH operating system environment variable.

For example, if the main module of your program is named mortgage and the application resides in the \prolog\apps directory, then your idb file parameter should be:

DATABASE=\prolog\apps\mortgage.idb

If you supply an .idb file name other than the name of the main module, then the system will look for the database with the name you supply.

Cache page allocation

The database used for term and interpreted code storage uses an area of memory which caches pages. Each page is 4 Kb in size, with a minimum of 4 required. All workspaces share the same cache.

When an application is started, the system allocates a certain number of pages (each 4K in size) for the internal database cache. The number of pages that the system attempts to allocate is determined by the MINPAGES and MAXPAGES parameters:

MINPAGES

This parameter indicates the fewest number of database cache pages that will be allocated for your application. Depending on your application, system performance may suffer if you set this parameter too low because extensive paging may occur between memory and disk. Therefore, you need to determine a reasonable setting for MINPAGES which results in acceptable performance but does not use large amounts of memory. Since such a setting is dependent on your application, you will need to try different settings to determine the optimum MINPAGES setting. The default setting for MINPAGES is 4. If the system cannot allocate the amount of pages indicated by MINPAGES, then the application will not run and you will receive an error message. However, the MINPAGES setting must be less than or equal to the MAXPAGES setting.

The format for the MINPAGES parameter is:

MINPAGES=number of 4 Kb pages

MAXPAGES

This parameter indicates the maximum number of database cache pages that can be allocated. The default setting for MAXPAGES is 1024. There is no minimum limit for the MAXPAGES parameter, but it must be greater than or equal to the MINPAGES setting. The best performance setting for MAXPAGES depends on a number of factors, including memory availability of the executing hardware and application database usage.

The format for the MAXPAGES parameter is:

MAXPAGES=number of 4 Kb pages

The overflow file

The overflow file is used to swap database pages in and out of memory. This file is created at startup and is used when your database grows larger than cache memory can hold.

You may specify the directory in which the overflow file for the application will be created. The default specification for the overflow file is to create the file in the directory specified by the TMP environment variable or if one does not exist, then in the current directory. The format for specifying the directory is:

OVERFLOW=directory_pathname

The directory pathname is the full pathname of the directory in which the overflow file will reside. This must be an existing directory. For example, the following parameter indicates that the overflow file will be placed in the \prolog\apps directory:

OVERFLOW=\prolog\apps

I/O buffer size and keyboard driver usage

The input and output routines in Arity/Prolog32 use buffering techniques for greater efficiency. Likewise, the handling of keyboard input uses techniques that act on certain key presses, particularly for facilitating line-edit operations.

When using C I/O routines in conjunction with Arity/Prolog32 input and output predicates you may need to do one or both of the following:

• Set the environment variable KBDRIVER to NO so that C input routines will not conflict with Arity/Prolog's keyboard driver.
• Use the C flushall() routine prior to using the C printf() and related routines to avoid problems between C and Prolog buffered I/O routines.

To disable the use of the Arity/Prolog32 keyboard driver, add the following to the application's environment file"

KBDRIVER=NO

The default value for the KBDRIVER parameter is YES.

A program may benefit from changes to the size of the I/O buffer. The size is specified in bytes, with a default of 2048. The format for specifying a different value is:

BUFSIZE=bytes

Operator definition area

Operator definitions may be dynamically modified. The memory area for operator definitions may be increased in size if your application has a large number of operators. The specified space is provided in kilobytes with a default of 3. The format is:

OPDEFSIZE=kilobytes