SDB - a Simple Database System



                              by David Betz

                            114 Davenport Ave.

                           Manchester, NH 03103

                              (603) 625-4691



                        Converted to the IBM/PC by

                              David N. Smith

                            44 Ole Musket Lane

                            Danbury, CT  06810

                              (203) 748-5934





        1.0  INTRODUCTION



        SDB is a simple database manager for small systems.  It  was

        developed  to  provide  a relatively low overhead system for

        storing data  on  machines  with  limited  disk  and  memory

        resources.   The current version runs on a PDT-11/150 with 2

        RX01 floppy disk drives and 60K bytes of  memory  under  the

        RT-11 operating system.  (it also runs on the VAX under VMS)



        SDB was originally intended  to  be  a  relational  database

        system, so many of the terms used in describing it are taken

        from the relational database literature.  Within the context

        of SDB the user can safely make the following associations:



             1.  RELATION can be taken to mean FILE



             2.  TUPLE can be taken to mean RECORD



             3.  ATTRIBUTE can be taken to mean FIELD



        It should be noted that SDB is not a  relationally  complete

        system.   It  provides  the relational operations of SELECT,

        PROJECT, and JOIN, but does not provide the  set  operations

        of  UNION,  INTERSECTION,  or  DIFFERENCE  as  well  as some

        others.





        2.0  RELATION FILE FORMATS



        SDB maintains a separate file for  each  relation  that  the

        user  creates.  This file contains a header block containing

        the definition of the relation including the names and types

        of  all  of the relation's attributes.  The remainder of the

        file contains fixed length records each containing one tuple

        from the relation.



        Tuples can be of three types:



             1.  active - tuples that contain actual active data



             2.  deleted - tuples that have been deleted



             3.  unused - tuples that haven't been used yet



        SDB - a Simple Database System                        Page 2





        Initially, all tuples are  unused.   When  a  new  tuple  is

        stored  into  a  relation,  the  first unused tuple is found

        (they are all contiguous at the end of the  relation  file).

        The new tuple is stored as an active tuple.



        When a tuple is deleted, it is marked as  such.   The  space

        previously  allocated  to  the  deleted tuple is left unused

        until the relation is compressed.



        It is possible that when attempting to store a new tuple, no

        unused  tuple can be found even though the relation contains

        fewer than the maximum active  tuples.   This  happens  when

        tuples  have  been  deleted since the time the relation file

        was last compressed.



        The compress function  allows  all  of  the  space  lost  by

        deleting tuples to be regained.  It does this by copying all

        of the active tuples as far backward in the file as possible

        leaving  all  of  the  available space toward the end of the

        file.







        3.0  SELECTION EXPRESSIONS



        A selection expression specifies a set of tuples over  which

        some  SDB  operation  is  to  be executed.  The syntax for a

        selection expression is:



        <rse>           ::= <rnames> [ where <boolean> ]

        <rnames>        ::= <rname> [ , <rname> ] ...

        <rname>         ::= <relation-name> [ <alias> ]



        When a single relation name  is  specified  in  a  selection

        expression,  each  tuple  within  that  relation  becomes  a

        candidate for selection.



        When more than one relation name is  specified,  the  tuples

        are  formed  by  taking  the  cross product of all specified

        relations.  If a relation is to be crossed with  itself,  an

        alias must be given to one or both of the occurances of that

        relation name in the selection expression.  This allows  SDB

        to determine which relation occurance is being refered to in

        the boolean part of the selection expression.



        After the set of candidate tuples is determined, the boolean

        expression  is evaluated for each candidate.  The candidates

        for which the boolean expression evaluates  to  TRUE  become

        the selected tuples.



        SDB - a Simple Database System                        Page 3





        4.0  INITIALIZATION FILE AND COMMAND FILES



        When SDB is first run,  it  attempts  to  read  and  process

        commands  from  a  file  named "SDB.INI".  This file usually

        contains macro definitions, but can contain  any  valid  SDB

        command.   In  addition,  it  is possible to process command

        files from within SDB.   This  is  done  by  typing  an  '@'

        followed by the command file name after the SDB prompt.







        5.0  FILE NAMES



        Whenever a file name is allowed in the syntax for a command,

        it  is  possible  to  use  either  an identifier or a quoted

        string.  An identifier is interpreted as the file name and a

        string  is  interpreted  as  a full file specification.  The

        string form allows for the  specification  of  an  alternate

        device or extension.







        6.0  FORM DEFINITION FILES



        A form  definition  file  contains  a  template  into  which

        attribute  values  are substituted during a print operation.

        There are two types of information that can be included in a

        form definition:



             1.  Literal text



             2.  Attribute references



        Attribute references are indicated by placing  the  name  of

        the  attribute  being  referenced  between  a  pair of angle

        brackets.  Literal text is anything that is not enclosed  in

        angle brackets.



        SDB - a Simple Database System                        Page 4





        Example:

        ________



        print using test amount,category from checks;



        Where test.frm contains:



        Amount: <amount>

        Category: <category>



        (MPK) For ease in generating English text, a $ character  may

        be placed before  the  attribute  name  inside  an  attribute

        reference, in which case no trailing blanks  will  appear  in

        the output for that reference.  For example:



        print using test number,category from checks;



        Where test.frm contains:



        Check #<$number> was spent on <$category





        7.0  ALIASES FOR RELATIONS AND ATTRIBUTES



        When a relation or attribute name is specified  in  a  print

        statement,  it  is possible to provide an alternate name for

        that relation or attribute.  This is useful  for  relations,

        when  it  is  necessary to join a relation to itself.  It is

        useful for attributes when it is  desired  that  the  column

        headers  in  a  table be different from the actual attribute

        names.  Also, alternate  attribute  names  can  be  used  in

        references  to that attribute in the where clause as well as

        in a  form  definition  file.   The  syntax  for  specifying

        aliases is:



            <name> <alias>





        Example:

        ________



        print using test amount a,category c from checks;



        Where test.frm contains:



        Amount: <a>

        Category: <c>



        SDB - a Simple Database System                        Page 5





        8.0  BOOLEAN EXPRESSIONS



        The syntax for boolean expressions:



        <expr>          ::= <land> [ '|' <land> ]

        <land>          ::= <relat> [ '&' <relat> ]

        <relat>         ::= <primary> [ <relop> <primary> ]

        <primary>       ::= <term> [ <addop> <term> ]

        <term>          ::= <unary> [ <mulop> <unary> ]

        <unary>         ::= <factor> | <unop> <unary>

        <factor>        ::= <operand> | '(' <expr> ')'

        <operand>       ::= <number> | <string> | <attribute>

        <attribute>     ::= [ <rname> . ] <aname>

        <relop>         ::= '=' | '<>' | '<' | '>' | '<=' | '>='

        <addop>         ::= '+' | '-'

        <mulop>         ::= '*' | '/'

        <unop>          ::= '+' | '-' | '~'





        Operators:



             1.  '=' - equal



             2.  '<>' - not equal



             3.  '<' - less than



             4.  '>' - greater than



             5.  '<=' - less than or equal



             6.  '>=' - greater than or equal



             7.  '+' - addition or unary plus (not implemented)



             8.  '-' - subraction or unary minus (not implemented)



             9.  '*' - multiplication (not implemented)



            10.  '/' - division (not implemented)



            11.  '&' - logical and



            12.  '|' - logical or



            13.  '~' - logical not



        Operands:



             1.  number - a string of digits containing at most  one

                 decimal point



             2.  string - a string of characters enclosed in  double

                 quotes



        SDB - a Simple Database System                        Page 6





             3.  attribute - an attribute name optionally  qualified

                 by a relation name





        SDB - a Simple Database System                        Page 7





        9.0  INTERACTIVE COMMAND DESCRIPTIONS



        Function:

        _________



        Create a relation file





        Format:

        _______



        create <rname> ( <alist> ) <size>





        Rules:

        ______



             1.  <rname> is the name of the relation file



             2.  <alist> is a list of attribute definitions  of  the

                 form:



                   <aname> { char | num } <size>



                 where:



                 1.  <aname> is the name of the attribute



                 2.  the type of the attribute is either  "char"  or

                     "num"



                 3.  <size> is the number of bytes allocated to  the

                     attribute value





             3.  <size> is the maximum number of tuples the file  is

                 to hold







        Example:

        ________



        create checks (

            number      num     4

            date        char    8

            payee       char    20

            amount      num     8

            category    char    5

        ) 200



        This command creates a relation file named "checks.sdb" with

        attributes   "number",   "date",   "payee",   "amount",  and

        "category" and space to store 200 tuples.



        SDB - a Simple Database System                        Page 8





        Function:

        _________



        Insert tuples into a relation





        Format:

        _______



        insert <rname>





        Rules:

        ______



             1.  <rname> is the name of a relation



             2.  the user will be prompted for  the  values  of  the

                 attributes for the tuple to be inserted



             3.  a  null  response  to  an  attribute  prompt   will

                 terminate tuple entry



             4.  if a null value is desired, a single space  can  be

                 entered





        SDB - a Simple Database System                        Page 9





        Function:

        _________



        Delete tuples from a set of relations





        Format:

        _______



        delete <rse> ;





        Rules:

        ______



             1.  <rse> is a tuple selection expression



             2.  selected tuples are deleted







        Example:

        ________



        delete checks where category = "junk";



        SDB - a Simple Database System                       Page 10







        Function:

        _________



        Update the values of selected attributes in selected tuples





        Format:

        _______



        update { <attrs> | * } from <rse> ;





        Rules:

        ______



             1.  <attrs> is a list of attribute names to be updated



             2.  * means all attributes



             3.  <rse> is a tuple selection expression



             4.  for each  set  of  selected  tuples,  the  user  is

                 prompted for new values for the selected attributes



             5.  a null response to an attribute prompt will  retain

                 the previous attribute value



             6.  if a null value is desired, a single space  can  be

                 entered







        Example:

        ________



        update amount,category from checks where number > 10;



        SDB - a Simple Database System                       Page 11





        Function:

        _________



        Print a table of values of selected attributes





        Format:

        _______



        print [ using <fname> ] { <attrs> | * } from  <rse>  [  into

        <fname> ] ;





        Rules:

        ______



             1.  using  <fname>  indicates  output  using   a   form

                 definition file (.FRM)



             2.  <attrs> is a list of attribute names to be printed



             3.  * means all attributes



             4.  <rse> is a tuple selection expression



             5.  <fname> is the name of an file to which  the  table

                 will be output (.TXT)



             6.  if the output file name is omitted,  output  is  to

                 the terminal



             7.  for each set of selected tuples, a table  entry  is

                 printed containing the selected attributes







        Example:

        ________



        print payee,amount from checks where category = "junk";



        SDB - a Simple Database System                       Page 12





        Function:

        _________



        Import tuples from a file into a relation





        Format:

        _______



        import <fname> into <rname>





        Rules:

        ______



             1.  <fname> is the name of the input file (.DAT)



             2.  the input file contains the  values  of  the  tuple

                 attributes with each on a separate line



             3.  <rname> is the name of a relation



             4.  tuples are appended to the named relation





        SDB - a Simple Database System                       Page 13





        Function:

        _________



        Export tuples from a relation into a file





        Format:

        _______



        export <rname> [ into <fname> ] ;





        Rules:

        ______



             1.  <rname> is the name of a relation



             2.  <fname> is the name of the output file (.DAT)



             3.  if the output file name is omitted,  output  is  to

                 the terminal



             4.  tuples are written to  the  output  file  with  one

                 attribute value per line





        SDB - a Simple Database System                       Page 14





        Function:

        _________



        Extract the definition of a relation into a file





        Format:

        _______



        extract <rname> [ into <fname> ] ;





        Rules:

        ______



             1.  <rname> is the name of a relation



             2.  <fname> is the name of the output file (.DEF)



             3.  if the output file name is omitted,  output  is  to

                 the terminal



             4.  the definition of the relation is  written  to  the

                 output file





        SDB - a Simple Database System                       Page 15





        Function:

        _________



        Compress a relation file





        Format:

        _______



        compress <rname>





        Rules:

        ______



             1.  <rname> is the name of a relation file



             2.  tuples are copied toward the front of the  relation

                 file  such  that  any  space  freed  by  previously

                 deleted tuples becomes adjacent to the  free  space

                 at the end of the file, thus becoming available for

                 use in inserting new tuples





        SDB - a Simple Database System                       Page 16





        Function:

        _________



        Sort a relation file





        Format:

        _______



        sort <rname> by <sname> { , <sname } ...  ;





        Rules:

        ______



             1.  <rname> is the name of a relation file



             2.  <sname> is the name of  an  attribute  to  sort  on

                 followed optionally by "ascending" or "descending"



             3.  if a sort order  is  not  specified,  ascending  is

                 assumed



             4.  tuples within the  relation  are  sorted  in  place

                 using the attributes indicated





        SDB - a Simple Database System                       Page 17





        Function:

        _________



        Define a macro





        Format:

        _______



        define <mname>





        Rules:

        ______



             1.  <mname> is the name of the macro being defined



             2.  if a macro with the specified name already  exists,

                 it is replaced



             3.  after entering the define command, definition  mode

                 is entered



             4.  definition  mode  is  indicated   by   the   prompt

                 "SDB-DEF>"



             5.  all lines typed in definition mode are added to the

                 macro definition



             6.  a blank line terminates definition mode



             7.  a macro can be deleted by entering a blank line  as

                 the only line in the definition



             8.  after a macro is defined, every  occurance  of  the

                 macro name is replaced by the macro definition





        SDB - a Simple Database System                       Page 18





        Function:

        _________



        Show a macro definition





        Format:

        _______



        show <mname>





        Rules:

        ______



             1.  <mname> is the name of a macro whose definition  is

                 to be shown





        SDB - a Simple Database System                       Page 19





        Function:

        _________



        Print a short help message







        Format:

        _______



        help





        Rules:

        ______



             1.  (none)





        SDB - a Simple Database System                       Page 20





        Function:

        _________



        Exit from SDB





        Format:

        _______



        exit





        Rules:

        ______



             1.  (none)





        SDB - a Simple Database System                       Page 21





        10.0  PROGRAM INTERFACE



        SDB provides a callable program interface to allow  programs

        written  in  DECUS-C  to access relation files.  In order to

        use the call interface, the users program should  be  linked

        with  the SDBUSR.OBJ object library.  Also, additional stack

        space should be allocated at link  time  using  the  /BOTTOM

        qualifier  on  the link command.  /BOTTOM:3000 seems to work

        well, but it is probably possible to get away with less.



        Example:

        ________



        #include <stdio.h>

        #include "sdb.h"



        main()

        {

            DB_SEL *sptr;

            char payee[100],amount[100];



            /* setup retrieval */

            if ((sptr = db_retrieve("checks where amount > 25.00")) == NULL) {

                printf("*** error: %s ***\n",db_ertxt(dbv_errcode));

                exit();

            }



            /* bind user variables to attributes */

            db_bind(sptr,"checks","payee",payee);

            db_bind(sptr,"checks","amount",amount);



            /* loop through selection */

            while (db_fetch(sptr))

                printf("%s\t%s\n",payee,amount);



            /* finish selection */

            db_done(sptr);

        }



        SDB - a Simple Database System                       Page 22





        Function:

        _________



        Setup a tuple retrieval context





        Format:

        _______



        dbptr = db_retrieve(sexpr [ ,arg ]...)





        Rules:

        ______



             1.  sexpr is a pointer to a string containing an rse



             2.  arg is a "printf" argument



             3.  dbptr is a database context pointer



             4.  db_retrieve returns NULL on errors



             5.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 23





        Function:

        _________



        Fetch the next set of tuples from a retrieval context





        Format:

        _______



        db_fetch(dbptr)





        Rules:

        ______



             1.  dbptr is a database context pointer



             2.  updates the values of all bound user variables



             3.  db_fetch returns FALSE if no more tuples  match  or

                 if an error occurs



             4.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 24





        Function:

        _________



        Update the current tuple within a retrieval context





        Format:

        _______



        db_update(dbptr)





        Rules:

        ______



             1.  dbptr is a database context pointer



             2.  db_update returns FALSE if an error occurs



             3.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 25





        Function:

        _________



        Store a new tuple within a retrieval context





        Format:

        _______



        db_store(dbptr)





        Rules:

        ______



             1.  dbptr is a database context pointer



             2.  db_store returns FALSE if an error occurs



             3.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 26





        Function:

        _________



        Bind a user variable to  the  value  of  a  tuple  attribute

        within a retrieval context





        Format:

        _______



        db_bind(dbptr,rname,aname,value)





        Rules:

        ______



             1.  dbptr is a database context pointer



             2.  rname is a pointer to the relation name



             3.  aname is a pointer to the attribute name



             4.  value is a pointer to a character array to  receive

                 the attribute value



             5.  db_bind returns FALSE if an error occurs



             6.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 27





        Function:

        _________



        Get the value  of  a  tuple  attribute  within  a  retrieval

        context





        Format:

        _______



        db_get(dbptr,rname,aname,value)





        Rules:

        ______



             1.  dbptr is a database context pointer



             2.  rname is a pointer to the relation name



             3.  aname is a pointer to the attribute name



             4.  value is a pointer to a character array to  receive

                 the attribute value



             5.  db_get returns FALSE if an error occurs



             6.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 28





        Function:

        _________



        Put the value  of  a  tuple  attribute  within  a  retrieval

        context





        Format:

        _______



        db_put(dbptr,rname,aname,value)





        Rules:

        ______



             1.  dbptr is a database context pointer



             2.  rname is a pointer to the relation name



             3.  aname is a pointer to the attribute name



             4.  value is a pointer to the new value



             5.  db_put returns FALSE if an error occurs



             6.  on errors, the error code is in dbv_errcode





        SDB - a Simple Database System                       Page 29





        Function:

        _________



        Discontinue usage of a retrieval context







        Format:

        _______



        db_done(dbptr)





        Rules:

        ______



             1.  dbptr is a database context pointer





        SDB - a Simple Database System                       Page 30





        Function:

        _________



        Translate an error code to an error message text





        Format:

        _______



        db_ertxt(errcode)





        Rules:

        ______



             1.  errcode is an SDB error code