Index of /tcl/ftparchive/sorted/databases/sdb-0.1

      Name                   Last modified     Size  Description


[DIR] Parent Directory       18-Dec-99 07:01      -  
[   ] README                 17-Nov-95 15:05    10k  
[DIR] examples/              29-Jan-99 12:24      -  
[CMP] sdb-0.1.tar.gz         01-Dec-95 09:24   383k  

SDB 0.1 -- Simulation Modelling Database/Spreadsheet extension
			Tom Moore, CFS-PNFI
		      tmoore@pnfi.forestry.ca
			  November 7, 1995

 --------------------------------------------------------------------
 Copyright (c) 1995 Tom Moore.  All rights reserved.

 Permission is hereby granted, without written agreement and without
 license or royalty fees, to use, copy, modify, and distribute this
 software and its documentation for any purpose, provided that the
 above copyright notice appear in all copies of this software.

 The author disclaims all warranties with regard to this software, 
 including all implied warranties of merchantability and fitness.  
 In no event shall the author be liable for any special, indirect or 
 consequential damages or any damages whatsoever resulting from loss 
 of use, data or profits, whether in an action of contract, negligence 
 or other tortuous action, arising out of or in connection with the use 
 or performance of this software. 
 --------------------------------------------------------------------
 

SDB (the Simulation modelling DataBase) is a TCL extension
that provides a convenient and powerful language for defining
simple models of dynamic systems.  SDB was designed as a language to
facilitate the rapid description, prototyping, and implementation
of the type of serial, sequential forecasting models that are popular 
in the field of forest resource management.  Although designed with
natural resource management applications in mind, there may be other 
disciplines that can benefit from this modelling tool.  When used with
the TkTable widget, the SDB appears to operate much like a spreadsheet
with automatic recomputation and display of interdependent variables.

Description of SDB

SDB supports many standard DBMS functions, such as sorting, searching, 
updating, indexing, selecting, aggregating and relational joins between
tables.  In addition, SDB also provides a few features specifically geared 
towards natural resource modelling, such as yield curve interpolation 
and simple hierarchical rule systems.  

The "sdb" command is used to instantiate a database cursor (an object 
containing all data and state of a database).  Once created, the cursor is
referenced as a command in the global command namespace.  The cursor can 
load the database from a simple ascii database description, or be populated 
programmatically.  All database elements are stored in memory:  although
requiring ample virtual memory, database operations are usually very
fast.  Once a cursor has been created, there are numerous sub-commands
available to create and manipulate database fields.

The cursor describes the columns of the database.  Only two basic data types 
are supported in the SDB:  numeric (stored as double precision), and label 
(stored as an arbitratry length string).  There are four storage classes 
for database variables:
- allocated:  a database column has storage allocated so that a unique 
              value can be stored in each row of the database,
- constant:   a database column is represented by a single value, all rows 
              in the database refer to the same value location,
- expression: a database column is represented by an expression, which is 
              evaluated to generate a (possibly) unique value for each row,
- lookup:     a database column is obtained from a table joined to the base 
              table in a relational fashion.

Part of the power of the SDB as a modelling language comes from the ability to
use expression variables define networks of relationships within
the database.  Expression variables (known as virtual fields in some DBMS)
are evaluated when the variable is referenced.  Evaluation of an expression
can trigger the evaulation of other expression, much in the same way as
a spreadsheet operates.  Once the network of relationships in a dynamic 
system have been defined, changes to a single driving variable may result
in a cascade of changes to the state variables.  Expressions are defined
in a 'C'-like language which is parsed by SDB into byte-codes, and
evaluated as required.

Another strength of the SDB is that it is embedded as an extension
within the Tcl/Tk environment.  There are many SDB sub-commands that 
retrieve database state information.  Tcl can be used as a scripting language
to write simulation macros, possibly to loop through database records
for fine-grained control of actions.  Tk can be used to develop a nice 
front-end to the system being simulated.  In particular, the SDB has been
written to be compatible with the TkTable widget.  The combination of
SDB and TkTable provides a fast spreadsheet-style interface to the database.
Within TkTable the contents of the SDB cursor can be shown and scrolled in 
row/column format; changes to driving variables cause an instant cascade 
of updated values to appear in the spreadsheet.


Motivation

The development of this software has been motivated by the following 
observations:

 - Most forest management simulation models perform simple operations, yet
   are composed of thousands of lines of code in low-level languages;
 - Few forest management simulation models adequately capture the 
   essential characteristics of the real systems that they are modelling.
   If they succeed in adequately describing the problem at first, it is not 
   for long because the problem definition changes rapidly. 
 - Forest managers are usually poor at programming.  If they are,
   they are usually lousy at forest management planning.  
As a result, those who best understand the nature of the forest management 
planning problem are usually least able to implement adequate quantitative
analysis by themselves.  If they are lucky, planners might be able to team
up with programmers to give them a hand, but most often software development
is too costly, and existing models are too difficult to modify.

SDB is an attempt to overcome these problems to some degree.  SDB provides
very high level operators that can be used to quickly develop quantitative
models.  As a result, the amount of code required to develop a model is
substantially shorter than using a language such as 'C' or Fortran (still
very popular in the forestry community).  Since the amount of code
required to express a model is greatly reduced, maintainance and
modification of models by planners becomes tractable.  My hypothesis is
that models and modelling concepts developed using SDB can be 'shared'
easily.  With fewer lines of code, the main concepts of the models can be
seen, understood, and copied or modified easier (obfuscated code excepted).


Status of Version 0.1

This is the first public alpha release of this software.   I have tried
to give it a good shake down, and have tested it extensively using 
purify.  I am not planning any major additional enhancements to this software
at this time, but I am willing to fix bugs as they are reported.  I intend 
to use this software to develop a few modelling applications, and will 
probably include these in future releases.

I have compiled and tested this software under SunOS 4.1.3 and Linux 1.2.13
(both aout and ELF).  If you are able to port this software to other platforms
please let me know.

This software was develop under TCL 7.3, but seems to work ok with
TCL 7.4 and TCL 7.5 as well.


Availability

Sdb-0.1 has been uploaded to the TCL archive site and will soon appear at:  
ftp://ftp.aud.alcatel.com/tcl/extensions/sdb-0.1.tar.gz


Basic Installation:

1.  Changes directories to the parent directory where you would like
    to compile the software.

2.  Uncompress and unpack the distribution:

	gzcat sdb-0.1.tar.gz | tar -xf -
	cd sdb0.1/src

3.  Modify the Makefile.

    The bad news is that I have not yet written an auto-configure script.  
    The good news is that there are few (if any) configuration parameters,
    so far just the location of the standard TCL libraries and the name
    of the C compiler.  

4.  Make sample executable:

        make sdbtcl

5.  Run the test suite to verify the installation:

	make test

    The test suite should run without errors.  


Advanced installation:

You might want to link sdbtcl into a custom tcl or tk shell.
This should be pretty easy because the Makefile generates
a standard library: libsdb.a.  Just do the usual tclAppInit.c
and Makefile hacking and everything should work ok.

1.  Include the "sdb.h" header file near the top of the file
    containing Tcl_AppInit():

       #include "sdb.h"

2.  Within the body of Tcl_AppInit(), add the following lines:

       if (Sdb_Init(interp) == TCL_ERROR) {
           return TCL_ERROR;
       }

3.  Link your application with libsdb.a


Dynamic loading:

I have tried this out under linux-elf and it seems to work ok.  I had a 
problem under linux-aout (inadequate support by the OS), and also under
SunOS4.1.3 (I am missing libm.so on my machine).  You will have to
change the configuration information in the Makefile according to
the configInfo file appropriate to your OS.


Documentation:

I have written a manual page that describes the language elements
(man/sdb.1).  I have also provided a set of examples containing datasets 
and scripts that show some of the language features (see examples/README).  
I may attempt to put together an annotated tutorial and user guide, but 
that will not be for a few months.

Acknowledgements:

The C routines in this package make extensive use of the TCL library API
and attempt to follow the TCL engineering manual guidelines.   Thanks to 
Dr. John Ousterhout for good direction in software engineering standards.

Included in this package are the 'bitstring' and balanced binary tree
routines written by Paul Vixie.  Thanks.

Also included are some of the routines from the cumulative distribution 
function library (CDFLIB), written by Barry W. Brown and James Lovato.
Please see the file 'src/normal.c' for a complete citation.


Feedback:

Any and all feedaback on this extension will be greatly appreciated.
My address (for now) is tmoore@pnfi.forestry.ca.

--
Tom Moore R.P.F.                                tmoore@pnfi.forestry.ca
Petawawa National Forestry Institute            
Canadian Forest Service, Box 2000, Chalk River  +1 (613) 589-3048
ONT K0J 1J0  CANADA                             +1 (613) 589-2275 telefax