bam.h

Go to the documentation of this file.

// ============================================================================
// Project:     Deductive Database
// Filename:    bam.h
// Purpose:     Interpreter for Bottom-Up Abstract Machine
// Last Change: 19.09.2017
// Language:    C++
// EMail:       brass@informatik.uni-halle.de
// WWW:         http://www.informatik.uni-halle.de/~brass/
// Address:     Feldschloesschen 15, D-06120 Halle (Saale), GERMANY
// Copyright:   (c) 2017 by Stefan Brass
// License:     See file "LICENSE" for copying conditions.
// Note:        There is no warranty at all - this code may contain bugs.
// ============================================================================


//=============================================================================
// Include File Frame:
//=============================================================================

#ifndef BAM_INCLUDED
#define BAM_INCLUDED

//=============================================================================
// Used Types and Macros:
//=============================================================================

#ifndef VER_INCLUDED
#include "../base/ver.h"
#endif

#ifndef STR_INCLUDED
#include "../base/str.h"
#endif

#ifndef CHECK_INCLUDED
#include "../base/check.h"
#endif

#ifndef MPOOL_INCLUDED
#include "../mem/mpool.h"
#endif

#ifndef FLEXARR_INCLUDED
#include "../bds/flexarr.h"
#endif

#ifndef STACK_INCLUDED
#include "../bds/stack.h"
#endif

#ifndef STRMEM_INCLUDED
#include "../dom/strmem.h"
#endif

#ifndef LIST_2_INCLUDED
#include "../rel/list_2.h"
#endif

#ifndef CUR_2_INCLUDED
#include "../rel/cur_2.h"
#endif

#ifndef SET_2_INCLUDED
#include "../rel/set_2.h"
#endif

#ifndef SET_TT_INCLUDED
#include "../rel/set_tt.h"
#endif

#ifndef REL_N_N_INCLUDED
#include "../rel/rel_n_n.h"
#endif

#ifndef CUR_N_N_INCLUDED
#include "../rel/cur_n_n.h"
#endif

#ifndef INST_INCLUDED
#include "inst.h"
#endif


//=============================================================================
// Public Constants:
//=============================================================================

//-----------------------------------------------------------------------------
// BAM_NULL_ADDR: Address to use when the real address is not yet known.
//-----------------------------------------------------------------------------

static const int BAM_NULL_ADDR = 0;


//=============================================================================
// Private Constants:
//=============================================================================

//-----------------------------------------------------------------------------
// BAM_MAGIC: Magic number (identifies objects of this class).
//-----------------------------------------------------------------------------

static const long BAM_MAGIC = 0x41424D0AL;      // 'BAM\n'

//-----------------------------------------------------------------------------
// BAM_CODE_AREA_SIZE: Size of memory for instructions.
//-----------------------------------------------------------------------------

static const int BAM_CODE_AREA_SIZE = 1024;

//-----------------------------------------------------------------------------
// BAM_MAX_VARS: Size of memory for variables.
//-----------------------------------------------------------------------------

static const int BAM_MAX_VARS = 256;

//-----------------------------------------------------------------------------
// BAM_STACK_SIZE: Size of the stack.
//-----------------------------------------------------------------------------

static const int BAM_STACK_SIZE = 1024;

//-----------------------------------------------------------------------------
// BAM_MAX_LIST_2: Maximal number of list_2_c relations with two columns.
//-----------------------------------------------------------------------------

static const int BAM_MAX_LIST_2 = 10;

//-----------------------------------------------------------------------------
// BAM_MAX_CUR_2: Maximal number of cur_2_c cursors over lists with two cols.
//-----------------------------------------------------------------------------

static const int BAM_MAX_CUR_2 = 10;

//-----------------------------------------------------------------------------
// BAM_MAX_SET_2: Maximal number of set_2_c relations with two columns.
//-----------------------------------------------------------------------------

static const int BAM_MAX_SET_2 = 10;

//-----------------------------------------------------------------------------
// BAM_MAX_SET_2B: Maximal number of set_tt_c relations with two columns.
//-----------------------------------------------------------------------------

static const int BAM_MAX_SET_2B = 10;

//-----------------------------------------------------------------------------
// BAM_MAX_MMAP_1_1: Maximal number of rel_n_n_c relations with two columns.
//-----------------------------------------------------------------------------

static const int BAM_MAX_MMAP_1_1 = 10;

//-----------------------------------------------------------------------------
// BAM_MAX_CUR_1_1: Maximal number cursors for rel_n_n_c relations.
//-----------------------------------------------------------------------------

static const int BAM_MAX_CUR_1_1 = 10;


//=============================================================================
// Class for Abstract Machine:
//=============================================================================


class bam_c {
        public:

//=============================================================================
// Constructors, Destructor:
//=============================================================================


        //---------------------------------------------------------------------
        // Constructor:
        //---------------------------------------------------------------------

        explicit bam_c(str_t name);


        //---------------------------------------------------------------------
        // Destructor:
        //---------------------------------------------------------------------

        ~bam_c();


        //---------------------------------------------------------------------
        // Copy-constructor and assignment operator are not supported:
        //---------------------------------------------------------------------

        private:

        bam_c(const bam_c& obj);                // Not implemented
        bam_c& operator=(const bam_c& obj);     // Not implemented


//=============================================================================
// (Object) Methods:
//=============================================================================

        public:

        //---------------------------------------------------------------------
        // error:
        //---------------------------------------------------------------------

        bool error() {

                // Check this object:
                CHECK_VALID("bam_c::err");

                // Did an error occur?
                return Error;
        }


        //---------------------------------------------------------------------
        // vars:
        //---------------------------------------------------------------------

        void vars(int num_vars);


        //---------------------------------------------------------------------
        // string:
        //---------------------------------------------------------------------

        int string(str_t str);


        //---------------------------------------------------------------------
        // list_2:
        //---------------------------------------------------------------------

        int list_2(list_2_t list);


        //---------------------------------------------------------------------
        // set_2:
        //---------------------------------------------------------------------

        int set_2(set_2_t set);

        //---------------------------------------------------------------------
        // set_2b:
        //---------------------------------------------------------------------

        int set_2b(set_tt_t set);

        //---------------------------------------------------------------------
        // mmap_1_1:
        //---------------------------------------------------------------------

        int mmap_1_1(rel_n_n_t mmap);


        //---------------------------------------------------------------------
        // cur_2:
        //---------------------------------------------------------------------

        int cur_2(int list_id);

        //---------------------------------------------------------------------
        // cur_1_1:
        //---------------------------------------------------------------------

        int cur_1_1(int mmap_id);


        //---------------------------------------------------------------------
        // next_code_addr:
        //---------------------------------------------------------------------

        int next_code_addr() {

                // Check this object:
                CHECK_VALID("bam_c::next_code_addr");

                // Address of next instruction:
                return NextCodeAddr;
        }


        //---------------------------------------------------------------------
        // null:
        //---------------------------------------------------------------------

        void null() {

                // This is an instruction without arguments:
                store_inst(INST_NULL);
        }


        //---------------------------------------------------------------------
        // halt:
        //---------------------------------------------------------------------

        void halt() {

                // This is an instruction without arguments:
                store_inst(INST_HALT);

        }

        //---------------------------------------------------------------------
        // call:
        //---------------------------------------------------------------------

        void call(int addr) {

                // Check this object:
                CHECK_VALID("bam_c::call");

                // Check parameter:
                CHECK(addr >= 0, "bam_c::call: addr is negative");
                CHECK(addr < BAM_CODE_AREA_SIZE,
                                "bam_c::call: addr too large");
                CHECK(addr < NextCodeAddr,
                                "bam_c::call: addr not used");

                // Check whether there is space for the instruction:
                store_inst_16(INST_CALL, addr);
        }


        //---------------------------------------------------------------------
        // call_forward:
        //---------------------------------------------------------------------

        void call_forward() {

                // Check this object:
                CHECK_VALID("bam_c::call_forward");

                // Store CALL instruction with null address:
                store_inst_16(INST_CALL, 0);
        }

        //---------------------------------------------------------------------
        // call_patch:
        //---------------------------------------------------------------------

        void call_patch(int inst_addr, int proc_addr) {

                // Check this object:
                CHECK_VALID("bam_c::call_patch");

                // Check parameters:
                CHECK(inst_addr >= 0,
                        "bam_c::call_patch: inst_addr is negative");
                CHECK(inst_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::call_patch: inst_addr too large");
                CHECK(Code[inst_addr] == INST_CALL,
                        "bam_c::call_patch: no CALL instruction");
                CHECK(proc_addr >= 0,
                        "bam_c::call_patch: proc_addr is negative");
                CHECK(proc_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::call_patch: proc_addr too large");
                CHECK(proc_addr <= NextCodeAddr,
                                "bam_c::call_patch: addr not used");

                // Make sure that jump target has defined instruction:
                if(proc_addr == NextCodeAddr)
                        store_tmp_halt();

                // Store address:
                inst_addr++;
                Code[inst_addr++] = static_cast<char>((proc_addr>>8) & 0xFF);
                Code[inst_addr]   = static_cast<char>(proc_addr & 0xFF);
        }


        //---------------------------------------------------------------------
        // ret:
        //---------------------------------------------------------------------

        void ret() {

                // This is an instruction without arguments:
                store_inst(INST_RETURN);
        }


        //---------------------------------------------------------------------
        // dupcheck_2:
        //---------------------------------------------------------------------

        void dupcheck_2(int set_id, int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::dupcheck_2");

                // Check parameters:
                CHECK(set_id >= 0,
                        "bam_c::dupcheck_2: set_id is negative");
                CHECK(set_id < NumRelSet2,
                        "bam_c::dupcheck_2: set_id too large");
                CHECK(var_id >= 0,
                        "bam_c::dupcheck_2: var_id is negative");
                CHECK(var_id < NumVars,
                        "bam_c::dupcheck_2: var_id too large");

                // This instruction has two 8 bit parameters:
                store_inst_8_8(INST_DUPCHECK_2, set_id, var_id);
        }


        //---------------------------------------------------------------------
        // dupcheck_2b:
        //---------------------------------------------------------------------

        void dupcheck_2b(int set_id, int var1_id, int var2_id) {

                // Check this object:
                CHECK_VALID("bam_c::dupcheck_2b");

                // Check parameters:
                CHECK(set_id >= 0,
                        "bam_c::dupcheck_2b: set_id is negative");
                CHECK(set_id < NumRelSet2B,
                        "bam_c::dupcheck_2b: set_id too large");
                CHECK(var1_id >= 0,
                        "bam_c::dupcheck_2b: var1_id is negative");
                CHECK(var1_id < NumVars,
                        "bam_c::dupcheck_2b: var1_id too large");
                CHECK(var2_id >= 0,
                        "bam_c::dupcheck_2b: var2_id is negative");
                CHECK(var2_id < NumVars,
                        "bam_c::dupcheck_2b: var2_id too large");

                // This instruction has three 8 bit parameters:
                store_inst_8_8_8(INST_DUPCHECK_2B, set_id, var1_id, var2_id);
        }


        //---------------------------------------------------------------------
        // save_var:
        //---------------------------------------------------------------------

        void save_var(int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::save_var");

                // Check parameters:
                CHECK(var_id >= 0,
                        "bam_c::save_var: var_id is negative");
                CHECK(var_id < NumVars,
                        "bam_c::save_var: var_id too large");

                // This instruction has one 8 bit parameter:
                store_inst_8(INST_SAVE_VAR, var_id);
        }


        //---------------------------------------------------------------------
        // restore_var:
        //---------------------------------------------------------------------

        void restore_var(int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::restore_var");

                // Check parameters:
                CHECK(var_id >= 0,
                        "bam_c::restore_var: var_id is negative");
                CHECK(var_id < NumVars,
                        "bam_c::restore_var: var_id too large");

                // This instruction has one 8 bit parameter:
                store_inst_8(INST_RESTORE_VAR, var_id);
        }


        //---------------------------------------------------------------------
        // save_mmap_1_1_cur:
        //---------------------------------------------------------------------

        void save_mmap_1_1_cur(int cur_id) {

                // Check this object:
                CHECK_VALID("bam_c::save_mmap_1_1_cur");

                // Check parameter:
                CHECK(cur_id >= 0,
                        "bam_c::save_mmap_1_1_cur: cur_id is negative");
                CHECK(cur_id < NumCurMMap11,
                        "bam_c::save_mmap_1_1_cur: cur_id too large");

                // This instruction has one 8 bit argument:
                store_inst_8(INST_SAVE_MMAP_1_1_CUR, cur_id);
        }


        //---------------------------------------------------------------------
        // restore_mmap_1_1_cur:
        //---------------------------------------------------------------------

        void restore_mmap_1_1_cur(int cur_id) {

                // Check this object:
                CHECK_VALID("bam_c::restore_mmap_1_1_cur");

                // Check parameter:
                CHECK(cur_id >= 0,
                        "bam_c::restore_mmap_1_1_cur: cur_id is negative");
                CHECK(cur_id < NumCurMMap11,
                        "bam_c::restore_mmap_1_1_cur: cur_id too large");

                // This instruction has one 8 bit argument:
                store_inst_8(INST_RESTORE_MMAP_1_1_CUR, cur_id);
        }

        //---------------------------------------------------------------------
        // loop_list_2:
        //---------------------------------------------------------------------

        void loop_list_2(int cur_id) {

                // Check this object:
                CHECK_VALID("bam_c::loop_list_2");

                // Check parameter:
                CHECK(cur_id >= 0, "bam_c::loop_list_2: cur_id is negative");
                CHECK(cur_id < NumCurList2,
                                "bam_c::loop_list_2: cur_id too large");

                // This instruction has one 8 bit and one (unknown) 16 bit arg:
                store_inst_8_16(INST_LOOP_LIST_2, cur_id, 0);
        }


        //---------------------------------------------------------------------
        // loop_patch:
        //---------------------------------------------------------------------

        void loop_patch(int inst_addr, int loop_done_addr) {

                // Check this object:
                CHECK_VALID("bam_c::loop_patch");

                // Check parameters:
                CHECK(inst_addr >= 0,
                        "bam_c::loop_patch: inst_addr is negative");
                CHECK(inst_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::loop_patch: inst_addr too large");
                CHECK(inst_addr < NextCodeAddr,
                        "bam_c::loop_patch: inst_addr not used");
                CHECK(Code[inst_addr] == INST_LOOP_LIST ||
                                Code[inst_addr] == INST_LOOP_LIST_2 ||
                                Code[inst_addr] == INST_LOOP_MMAP ||
                                Code[inst_addr] == INST_LOOP_MMAP_1_1,
                        "bam_c::loop_patch: no LOOP instruction");
                CHECK(loop_done_addr >= 0,
                        "bam_c::loop_patch: loop_done_addr is negative");
                CHECK(loop_done_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::loop_patch: loop_done_addr too large");
                CHECK(loop_done_addr <= NextCodeAddr,
                                "bam_c::loop_patch: loop_done_addr not used");

                // Make sure that jump target has defined instruction:
                if(loop_done_addr == NextCodeAddr)
                        store_tmp_halt();

                // Store address:
                inst_addr++; // For OpCode
                inst_addr++; // For Cursor ID
                Code[inst_addr++] = static_cast<char>((loop_done_addr>>8)&0xFF);
                Code[inst_addr]   = static_cast<char>(loop_done_addr & 0xFF);
        }

        //---------------------------------------------------------------------
        // loop_mmap_1_1:
        //---------------------------------------------------------------------

        void loop_mmap_1_1(int cur_id, int loop_done_addr, int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::loop_mmap_1_1");

                // Check parameter:
                CHECK(cur_id >= 0,
                        "bam_c::loop_mmap_1_1: cur_id is negative");
                CHECK(cur_id < NumCurMMap11,
                        "bam_c::loop_mmap_1_1: cur_id too large");
                CHECK(loop_done_addr == BAM_NULL_ADDR ||
                                loop_done_addr >= 0,
                        "bam_c::loop_mmap_1_1: loop_done_addr is negative");
                CHECK(loop_done_addr == BAM_NULL_ADDR ||
                                loop_done_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::loop_mmap_1_1: loop_done_addr too large");
                CHECK(loop_done_addr == BAM_NULL_ADDR ||
                                loop_done_addr <= NextCodeAddr,
                        "bam_c::loop_mmap_1_1: loop_done_addr not used");
                CHECK(var_id >= 0,
                        "bam_c::loop_mmap_1_1: var_id is negative");
                CHECK(var_id < NumVars,
                        "bam_c::loop_mmap_1_1: var_id too large");

                // The instruction has one 8 bit, one 16 bit, and one 8 bit arg:
                store_inst_8_16_8(INST_LOOP_MMAP_1_1, cur_id, loop_done_addr,
                                                                var_id);
        }

        //---------------------------------------------------------------------
        // get_list_2_col_1:
        //---------------------------------------------------------------------

        void get_list_2_col_1(int cur_id, int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::get_list_2_col_1");

                // Check parameters:
                CHECK(cur_id >= 0,
                                "bam_c::get_list_2_col_1: cur_id is negative");
                CHECK(cur_id < NumCurList2,
                                "bam_c::get_list_2_col_1: cur_id too large");
                CHECK(var_id >= 0,
                                "bam_c::get_list_2_col_1: var_id is negative");
                CHECK(var_id < NumVars,
                                "bam_c::get_list_2_col_1: var_id too large");

                // This is an instruction with two 8 bit arguments:
                store_inst_8_8(INST_GET_LIST_2_COL_1, cur_id, var_id);
        }


        //---------------------------------------------------------------------
        // get_list_2_col_2:
        //---------------------------------------------------------------------

        void get_list_2_col_2(int cur_id, int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::get_list_2_col_2");

                // Check parameters:
                CHECK(cur_id >= 0,
                                "bam_c::get_list_2_col_2: cur_id is negative");
                CHECK(cur_id < NumCurList2,
                                "bam_c::get_list_2_col_2: cur_id too large");
                CHECK(var_id >= 0,
                                "bam_c::get_list_2_col_2: var_id is negative");
                CHECK(var_id < NumVars,
                                "bam_c::get_list_2_col_2: var_id too large");

                // This is an instruction with two 8 bit arguments:
                store_inst_8_8(INST_GET_LIST_2_COL_2, cur_id, var_id);
        }


        //---------------------------------------------------------------------
        // get_mmap_1_1_out_1:
        //---------------------------------------------------------------------

        void get_mmap_1_1_out_1(int cur_id, int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::get_mmap_1_1_out_1");

                // Check parameters:
                CHECK(cur_id >= 0,
                        "bam_c::get_mmap_1_1_out_1: cur_id is negative");
                CHECK(cur_id < NumCurMMap11,
                        "bam_c::get_mmap_1_1_out_1: cur_id too large");
                CHECK(var_id >= 0,
                        "bam_c::get_mmap_1_1_out_1: var_id is negative");
                CHECK(var_id < NumVars,
                        "bam_c::get_mmap_1_1_out_1: var_id too large");

                // This is an instruction with two 8 bit arguments:
                store_inst_8_8(INST_GET_MMAP_1_1_OUT_1, cur_id, var_id);
        }


        //---------------------------------------------------------------------
        // end_loop_list_2:
        //---------------------------------------------------------------------

        void end_loop_list_2(int cur_id, int loop_body_addr) {

                // Check this object:
                CHECK_VALID("bam_c::end_loop_list_2");

                // Check parameters:
                CHECK(cur_id >= 0,
                        "bam_c::end_loop_list_2: cur_id is negative");
                CHECK(cur_id < NumCurList2,
                        "bam_c::end_loop_list_2: cur_id too large");
                CHECK(loop_body_addr >= 0,
                        "bam_c::end_loop_list_2: loop_body_addr is negative");
                CHECK(loop_body_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::end_loop_list_2: loop_body_addr too large");
                CHECK(loop_body_addr < NextCodeAddr,
                        "bam_c::end_loop_list_2: loop_body_addr not used");

                // This instruction has an 8 bit and a 16 bit parameter:
                store_inst_8_16(INST_END_LOOP_LIST_2, cur_id, loop_body_addr);
        }


        //---------------------------------------------------------------------
        // end_loop_mmap_1_1:
        //---------------------------------------------------------------------

        void end_loop_mmap_1_1(int cur_id, int loop_body_addr) {

                // Check this object:
                CHECK_VALID("bam_c::end_loop_mmap_1_1");

                // Check parameters:
                CHECK(cur_id >= 0,
                        "bam_c::end_loop_mmap_1_1: cur_id is negative");
                CHECK(cur_id < NumCurMMap11,
                        "bam_c::end_loop_mmap_1_1: cur_id too large");
                CHECK(loop_body_addr >= 0,
                        "bam_c::end_loop_mmap_1_1: loop_body_addr is negative");
                CHECK(loop_body_addr < BAM_CODE_AREA_SIZE,
                        "bam_c::end_loop_mmap_1_1: loop_body_addr too large");
                CHECK(loop_body_addr < NextCodeAddr,
                        "bam_c::end_loop_mmap_1_1: loop_body_addr not used");

                // This instruction has an 8 bit and a 16 bit parameter:
                store_inst_8_16(INST_END_LOOP_MMAP_1_1, cur_id, loop_body_addr);
        }


        //---------------------------------------------------------------------
        // insert_list_2:
        //---------------------------------------------------------------------

        void insert_list_2(int rel_id, int var1_id, int var2_id) {

                // Check this object:
                CHECK_VALID("bam_c::insert_list_2");

                // Check parameters:
                CHECK(rel_id >= 0,
                        "bam_c::insert_list_2: rel_id is negative");
                CHECK(rel_id < NumRelList2,
                        "bam_c::insert_list_2: rel_id too large");
                CHECK(var1_id >= 0,
                        "bam_c::insert_list_2: var1_id is negative");
                CHECK(var1_id < NumVars,
                        "bam_c::insert_list_2: var1_id too large");
                CHECK(var2_id >= 0,
                        "bam_c::insert_list_2: var2_id is negative");
                CHECK(var2_id < NumVars,
                        "bam_c::insert_list_2: var2_id too large");

                // This is an instruction with two 8 bit arguments:
                store_inst_8_8_8(INST_INSERT_LIST_2, rel_id, var1_id, var2_id);
        }


        //---------------------------------------------------------------------
        // insert_list_2_v:
        //---------------------------------------------------------------------

        void insert_list_2_v(int rel_id, int var_id) {

                // Check this object:
                CHECK_VALID("bam_c::insert_list_2_v");

                // Check parameters:
                CHECK(rel_id >= 0,
                        "bam_c::insert_list_2_v: rel_id is negative");
                CHECK(rel_id < NumRelList2,
                        "bam_c::insert_list_2_v: rel_id too large");
                CHECK(var_id >= 0,
                        "bam_c::insert_list_2_v: var_id is negative");
                CHECK(var_id < NumVars,
                        "bam_c::insert_list_2_v: var_id too large");

                // This is an instruction with two 8 bit arguments:
                store_inst_8_8(INST_INSERT_LIST_2_V, rel_id, var_id);
        }


        //---------------------------------------------------------------------
        // insert_mmap_1_1:
        //---------------------------------------------------------------------

        void insert_mmap_1_1(int set_id, int var1_id, int var2_id) {

                // Check this object:
                CHECK_VALID("bam_c::insert_mmap_1_1");

                // Check parameters:
                CHECK(set_id >= 0,
                        "bam_c::insert_mmap_1_1: set_id is negative");
                CHECK(set_id < NumRelMMap11,
                        "bam_c::insert_mmap_1_1: set_id too large");
                CHECK(var1_id >= 0,
                        "bam_c::insert_mmap_1_1: var1_id is negative");
                CHECK(var1_id < NumVars,
                        "bam_c::insert_mmap_1_1: var1_id too large");
                CHECK(var2_id >= 0,
                        "bam_c::insert_mmap_1_1: var2_id is negative");
                CHECK(var2_id < NumVars,
                        "bam_c::insert_mmap_1_1: var2_id too large");

                // This instruction has three 8 bit parameters:
                store_inst_8_8_8(INST_INSERT_MMAP_1_1,
                                                set_id, var1_id, var2_id);
        }


        //---------------------------------------------------------------------
        // insert_mmap_1_1:
        //---------------------------------------------------------------------

        void trace_call_2(int str_id, int var1_id, int var2_id) {

                // Check this object:
                CHECK_VALID("bam_c::trace_call_2");

                // Check parameters:
                CHECK(str_id >= 0,
                        "bam_c::trace_call_2: str_id is negative");
                CHECK(str_id < Strings.length(),
                        "bam_c::trace_call_2: str_id too large");
                CHECK(str_id < 256,
                        "bam_c::trace_call_2: str_id not 8 bit");
                CHECK(var1_id >= 0,
                        "bam_c::trace_call_2: var1_id is negative");
                CHECK(var1_id < NumVars,
                        "bam_c::trace_call_2: var1_id too large");
                CHECK(var2_id >= 0,
                        "bam_c::trace_call_2: var2_id is negative");
                CHECK(var2_id < NumVars,
                        "bam_c::trace_call_2: var2_id too large");

                // This instruction has three 8 bit parameters:
                store_inst_8_8_8(INST_TRACE_CALL_2,
                                                str_id, var1_id, var2_id);
        }


        //---------------------------------------------------------------------
        // run:
        //---------------------------------------------------------------------

        bool run(int start_addr);



//=============================================================================
// Debugging Support:
//=============================================================================

        //---------------------------------------------------------------------
        // check:
        //---------------------------------------------------------------------

#if     VER_DEBUG

        public:
        str_t   check() const;

        // Magic number (identifies objects of this class for debugging).
        private:
        long    Magic;          // Must be "BAM_MAGIC".
#endif

        //---------------------------------------------------------------------
        // dump:
        //---------------------------------------------------------------------

#if     VER_DUMP

        public:
        void dump(str_t headline = STR_NULL) const;
#endif

//=============================================================================
// Auxiliary Methods:
//=============================================================================

        private:

        //---------------------------------------------------------------------
        // store_inst:
        //---------------------------------------------------------------------

        void store_inst(inst_t inst);


        //---------------------------------------------------------------------
        // store_inst_8:
        //---------------------------------------------------------------------

        void store_inst_8(inst_t inst, int arg);


        //---------------------------------------------------------------------
        // store_inst_16:
        //---------------------------------------------------------------------

        void store_inst_16(inst_t inst, int arg);


        //---------------------------------------------------------------------
        // store_inst_8_8:
        //---------------------------------------------------------------------

        void store_inst_8_8(inst_t inst, int arg1, int arg2);


        //---------------------------------------------------------------------
        // store_inst_8_8_8:
        //---------------------------------------------------------------------

        void store_inst_8_8_8(inst_t inst, int arg1, int arg2, int arg3);


        //---------------------------------------------------------------------
        // store_inst_8_16:
        //---------------------------------------------------------------------

        void store_inst_8_16(inst_t inst, int arg1, int arg2);


        //---------------------------------------------------------------------
        // store_inst_8_16_8:
        //---------------------------------------------------------------------

        void store_inst_8_16_8(inst_t inst, int arg1, int arg2, int arg3);


        //---------------------------------------------------------------------
        // store_tmp_halt:
        //---------------------------------------------------------------------

        void store_tmp_halt();


//=============================================================================
// Private Object Members:
//=============================================================================

        private:

        // Memory Pool for Allocating Storage Pages:
        mpool_c MemPool;

        // Rest of current memory page for allocating relations and cursors:
        page_u_t FreeMemPtr;

        // Number of page_u units still available in the current memory page:
        int FreeMemUnits;

        // Did an error occur?
        bool Error;

        // Code area (memory for instructions):
        unsigned char Code[BAM_CODE_AREA_SIZE];

        // Next free location in code area:
        int NextCodeAddr;

        // Memory for variables:
        int Vars[BAM_MAX_VARS];

        // Number of variables that are actually used:
        int NumVars;

        // Stack:
        //stack_c<int,BAM_STACK_SIZE> Stack;
        stack_c<int> Stack;

        // String memory:
        strmem_c StrMem;
        flexarr_c<str_t> Strings;

        // Lists with two columns:
        list_2_t RelList2[BAM_MAX_LIST_2];
        int NumRelList2;

        // Cursors over list_2_c relations:
        cur_2_t CurList2[BAM_MAX_CUR_2];
        int NumCurList2;

        // Sets with two columns:
        set_2_t RelSet2[BAM_MAX_SET_2];
        int NumRelSet2;

        // Sets with two columns, bitmap version:
        set_tt_t RelSet2B[BAM_MAX_SET_2B];
        int NumRelSet2B;

        // MultiMaps with one column mapped to one column:
        rel_n_n_t RelMMap11[BAM_MAX_MMAP_1_1];
        int NumRelMMap11;

        // Cursors over multimaps with one column mapped to one column:
        cur_n_n_t CurMMap11[BAM_MAX_CUR_1_1];
        int NumCurMMap11;


//=============================================================================
// End of Class:
//=============================================================================

};

//-----------------------------------------------------------------------------
// Define pointer type:
//-----------------------------------------------------------------------------

typedef bam_c *bam_t;

//-----------------------------------------------------------------------------
// Define null pointer:
//-----------------------------------------------------------------------------

#define BAM_NULL (static_cast<bam_t>(0))

//=============================================================================
// End of Include File:
//=============================================================================

#endif