Appendix A  Parameters for Initialising an ECLⁱPS^e engine

It is possible to parametrise the initialisation of the ECLⁱPS^eengine by calling the functions ec_set_option_long() and ec_set_option_ptr(). This must be done before initialisation.

Installation directory

 ec_set_option_ptr(EC_OPTION_ECLIPSEDIR, "/usr/tom/eclipse");

This can be used to tell an embedded ECLⁱPS^e where to find it support files. The default setting is NULL, which means that the location is taken from the registry entry or from the ECLIPSEDIR environment variable.

Stack Memory Allocation

 ec_set_option_long(EC_OPTION_LOCALSIZE, 128*1024*1024);
 ec_set_option_long(EC_OPTION_GLOBALSIZE, 128*1024*1024);

The sizes in bytes of the stacks can be varied. They will be rounded to system specific pagesizes. On machines where initially only virtual memory is reserved rather than allocating real memory (WindowsNT/95, Solaris) they default to very large sizes (128MB), where real memory or space in the operating system swap file is taken immediately (SunOS), their default is very small (750KB,250KB).

Heap Memory Allocation

 ec_set_option_long(EC_OPTION_PRIVATESIZE, 32*1024*1024);
 ec_set_option_long(EC_OPTION_SHAREDSIZE, 64*1024*1024);

The sizes in bytes of the private and shared heaps. Normally these are ignored as the heaps grow as required.

They are used in the parallel ECLⁱPS^e, since there allocation is done at fixed addresses and in that case these sizes determine the maximum amount of memory per heap.

Panic Function

        void my_panic(char * what, char * where);
 ...
 ec_set_option_ptr(EC_OPTION_PANIC, my_panic);

When ECLⁱPS^e experiences an unrecoverable error, this function is called. By default a function that prints the panic message and exits is called. After such an error, one should not call any of the functions in this interface.

Startup Arguments

        char *args[] = {"a","b","c"}
 ...
 ec_set_option_long(EC_OPTION_ARGC, 3);
 ec_set_option_ptr(EC_OPTION_ARGV, args);

These setting are used to simulate a command line for an embedded ECLⁱPS^e, or to pass command line information to an embedded ECLⁱPS^e. The ECLⁱPS^e built-in predicates (argc/1 and argv/2) can access this information. This provides a way of passing some initial data to the ECLⁱPS^e engine.

Default Module

 ec_set_option_ptr(EC_OPTION_DEFAULT_MODULE, "my_module");

The default module is the module in which goals called from the top-level execute. It is also the module that goals called from C or C++ execute in. The default setting is "eclipse".

I/O Initialisation

 ec_set_option_long(EC_OPTION_IO, MEMORY_IO);

This option controls whether the default I/O streams of ECLⁱPS^e are connected to stdin/stdout/stderr or to memory queues. The default setting of this option is SHARED_IO, which means the ECLⁱPS^e streams 0,1,2 are connected to stdin/stdout/stderr. In an embedded application, stdin/stdout/stderr may not be available, or the host application may want to capture all I/O from ECLⁱPS^e. In this case, use the MEMORY_IO setting, which creates queue streams for streams 0,1 and 2. These can then be read and written using ec_queue_read() and ec_queue_write().

Parallel system parameters

 ec_set_option_long(EC_OPTION_PARALLEL_WORKER, 0);
 ec_set_option_long(EC_OPTION_ALLOCATION, ALLOC_PRE);
 ec_set_option_ptr(EC_OPTION_MAPFILE, NULL);

The above options are set differently in ECLⁱPS^e when it is a worker in a parallel system. They should not be altered.