This page is also available in

Documentation

Below documentation is part of the BeeBase dictribution and is also available in PDF.

4. Tutorial

The making of a family-tree database.

This chapter contains a brief tutorial describing the basic usage of BeeBase. Within the tutorial a small project is developed that allows the managing of your family tree. The project that results after applying all steps in this tutorial can be found as the `FamilyTree.bbs' project located in the `Demos' directory of your BeeBase installation.

4.1 How BeeBase Works

BeeBase could be said to operate in two different modes, record-editing and structure-editing mode.

The record-editing mode is where you add, change, or delete records.

The structure-editing mode lets you edit how your database should look like and what tables and fields it contains.

Besides this there is the program editor where you enter program functions that are executed automatically when entering data or explicitly when pressing a program button.

4.2 Starting with a Project, the Structure Editor

To create a database you first need to define it's contents. In BeeBase this is done in the structure editor which is opened by choosing `Structure editor' in the `Project' menu. Here you find three different sections:

`Tables'

Add, change, or delete the tables of your project.

`Fields'

Add, change, or delete fields of the currently selected table.

`Display'

Specify the graphical layout of your database, i.e. how it should be displayed.

4.3 Adding a Table

First we need a table, press the `New' button just below the list view in the `Table' section. You will then see a dialog which asks you to enter some data:

`Name'

The name of the table. The name must begin with an uppercase letter and can consist of up to 20 characters. The name can be changed later. In this tutorial we set the name to `Person' since it's going to hold all the person's names in this database.

`Number of records'

A table can either consist of only one or of an unlimited number of records. In our case it should be set to unlimited since we are going to add more than one person.

`Trigger functions'

The adding and deletion of records can be controlled by program functions. This is where you set which function to call. Since we don't have written any program functions yet, we leave the fields empty.

When this is done, just press the `OK' button and we have our first table, `Person'.

4.4 Adding a Field

Then we need a string field for that table, press `New' in the fields section. Fields also need some settings:

`Name'

The same as for a table: first letter must be uppercase and altogether a maximum of 20 characters. We set the name of this field to `Name' as it will contain the names of the persons we are about to add.

`Type'

Here we choose what type this field should be. There are a couple of different ones but for this field we use a string field.

`Max length'

Here you can define the maximum number of characters a user can enter for the string. We set this to 30.

`Initial value'

It's possible to have some fields to use an initial value for every new record you add, here is where you enter what it should contain. Leave this line blank.

`Trigger'

An field could also trigger a program function to be executed. For example, if you enter a name then you can have a program to check if this name already exists. We leave this field empty.

4.5 Displaying the Project

After pressing `OK' you now should notice some changes in the display section. Change the choice button on the top of the display section to `Main window'. There you see what the main window holds, currently only table `Person'. If you change the choice button back to `Table mask', you can see how table `Person' is presented. Currently it's displayed as one panel with one field.

Now double-click on `Person' at the top of the list in the display section and a window should appear. Click on the `Panel' tab and you can set how the panel of the table should be displayed:

`Title'

The title of a table can be different to it's name. Our table is called `Person' but here we could set it to be `THIS IS THE TABLE PERSON!' if we prefer that better.

`Background'

The background can be changed to whatever suits your taste.

`Gadgets'

Here we can define what gadgets we want the panel to have.

Press `OK' and then double-click on `Name' in the list-view in the display section. This brings up the window that contains the settings for how to display the string field `Name'.

`Title'

The same as for the panel. The string you enter here is what is really displayed when in record-editing mode.

`Shortcut'

Here you can set a letter that can be used to jump to this field, when in record-editing mode. For jumping to the field you need to hold down the Alt key (Windows, Mac OS and Linux) respectively the Amiga key and then press the letter.

`Home'

Makes the cursor to jump to this field whenever a new record is added. In our case we will always or most of the time enter the name first in a new record, so set it.

`Read only'

Set this if the field should be read only. Leave it unset.

`Weight'

Decides how much of this field should be visible when competing for the space with other fields. For example, if three 50-character strings resides in a window that only has room for 100 characters, then this number decides how much space the string gets relatively to the other ones. Leave it at 100.

`Background'

The same as for the panel.

`Bubble help'

Here you enter any text you think would be helpful to the user. The bubble help appears after holding the mouse still over a field for some seconds. Set this to `If you need help, call the author at 112'.

Leave the structure editor (choose `Exit structure editor' in the `Project' menu) and you are back to record-editing mode where you see how the database really looks like. You'll see the headline which is the string you may have entered in the display section for the panel. The record counter should say `#0/0' since we haven't added any records yet. Thereafter is a filter button and two arrow buttons. Below all this you should have the `Name' field with the text you may have entered in the display section for this field. If you haven't changed any text at all when in the display section then the panel should be named `Person', and the string field `Name'. Move the mouse above the string field `Name' and leave it there for a couple of seconds. If you entered something in the bubble help above then this text should appear in a popup window.

4.6 Adding two Reference Fields

Now we will add two reference fields. Reference fields are a bit different than other fields. As their name might imply they refer to records. This will become more understandable as you try it out for yourself in just a while.

Enter the structure editor again and add two more fields to table `Person'. Press `New' in the fields section, name it `Father', and change it's type to `Reference'. A reference field has only one setting:

`Set reference to'

Tells which table the field refers to. It should already be pointing to table `Person'. Leave it that way and press `Ok'.

Add another field by pressing `New' in the field section and call it `Mother'. The field's type should also be set to reference and point to table `Person'.

As you may have noticed, there are now three fields in the display section. Click on `Father' and then on the buttons up and down located just to the left. This will change where `Father' is positioned when looking at it while in record-editing mode. Put `Father' at the top, `Name' in the middle, and `Mother' at the bottom.

Next, we specify what contents the reference fields `Father' and `Mother' should display from the referenced records. Double-click on `Father' in the display section and then click on `Extras'. Here we choose to display the string field `Name', then we press `Ok' and repeat the procedure for `Mother'.

4.7 Adding Records

Now we should add some records. Leave the structure editor and enter record-editing mode. To add a new record you choose `New record' from the `Table' menu (on Windows and Linux you find this menu by pressing and holding the right mouse button inside the table mask). The cursor should now automatically jump to the field we have set to `Home' earlier in the display section in the structure editor. Add two records, one with your fathers name in `Name' and another one with your mothers name in `Name'. Thereafter you add another record with your own name in `Name'.

Now it's time to understand those reference fields. By pressing on the list-view button on `Father' we get a list of all records this reference field could refer to. Choose your fathers name and do accordingly down below on the mothers list-view.

Now you should have three records, you, your father and your mother. In your record, your fathers name should be visible in `Father' at the top and your mothers name should be in `Mother' at the bottom. You can browse through the records by pressing Alt together with the cursor keys Up and Down.

But hey! My parents also has/had parents you say! So let's add another four records, the third generation. Just add the records one by one and write their names in `Name'. If you don't remember their names then just enter `father's father', `mother's father' or something like that instead. Then you browse through all the records and set `Father' and `Mother' to what they should contain. When this is done you should have at least seven records, your record, your parents records and your grandparents records.

4.8 Filter

Since we now have some records to work with, we could try out the filter function. The filter can sort out records you don't want to display, they will still remain in the database but they are just not displayed anymore.

To edit the filter you choose `Change filter' from the `Table' menu. A window with loads of operators will appear. This is where you set what conditions a record must fulfill to get displayed.

In this small example we will use the LIKE command, which lets you do a joker comparison of a field. Press once on the LIKE button to the right and then double-click on `Name' in the list to the left and (LIKE Name ) should appear in the string just above the `Ok' and `Cancel' buttons. Thereafter you type "*a*" so the whole string shows (LIKE Name "*a*"). This means that BeeBase should display all records that contain the letter `a' anywhere in `Name'.

Press `Ok' and you may notice that records with no `a' in `Name', no longer are visible. Since the letter `a' is quite common in most languages and names, all records might still be visible but you can try other letters to make the filter function more clear.

As mentioned earlier there is a button on the panel that says `F'. This `F' indicates if the filter is on or off. Finally when you're done testing, turn the filter off so that all records are visible.

4.9 Queries

Now that we have played with the filter function a bit, we turn to the query feature of BeeBase. Queries can be used to display information from a database matching certain criteria.

Choose `Queries' from the `Program' menu to open the query editor. Now a window with some buttons on the top and two larger areas below appear. The string to the upper left is where you enter the name of what you want to call the query you make.

`Run'

Compiles and runs the query.

`Print'

Prints the result of the query to a file or on your printer.

`Load and Save'

Lets you load and save each of the queries.

The first large area is where you enter the query. The second large area is where the result is displayed.

Now let's produce a list of all those persons we tried to filter out previously. Type `Persons with an a in their name' in the string to the upper left. This is the title for this query. In the upper large area, type:

SELECT Name FROM Person WHERE (LIKE Name "*a*")

Now when you run this query by pressing the `Run' button it will produce a list of all persons with the letter `a' in their name. Try changing the letter to see different results.

At this time we can introduce the AND command. Press the list-view button just to the left of the `Run' button in the query editor. Then choose `New' and name it `Persons with both letter a and s in their names'. Then type

SELECT Name FROM Person WHERE
(AND (LIKE Name "*a*") (LIKE Name "*s*"))

Note that we are still using the LIKE command for choosing records containing the letters `a' or `s' in their names, but the AND command requires that BOTH LIKE criteria are met. Therefore, only records with BOTH the letters `a' and `s' in their name are displayed when the query is run.

4.10 Adding a Table with a Memo and a Button Field

These were two ways of selecting and displaying the database. Another way of displaying data can be done by a program. In order to display data we can use a field type called memo.

Enter the structure editor and press `New' in the table section. Name the new table `Control' and set it's number of records to `Exactly one'. Click and hold down the mouse button on the new table. Now drag it just a bit above the middle of table `Person' and release the button. In the table section, `Control' should now be on top, followed by `Person' below.

Make sure that table `Control' is selected, then press `New' in the field section. Set the type of the new field to `Memo' and give it the name `Result'. Press `Ok' and then add another field to table `Control' by once again pressing `New' in the field section. This time, set it's type to `Button' and name it `Pedigree'.

To give the database a better look, click once on `Pedigree' in the display section and push it to the top by pressing the `Up' button once.

4.11 Programming BeeBase to do a Pedigree

Now we have a button that can start a program and a memo to display data in. It's therefore time to enter the program editor. This is done by choosing `Edit' from the `Program' menu. The editor has three buttons:

`Compile & Close'

Which does just that. It compiles the program and leaves the program editor.

`Compile'

Compiles the programs but stays in the program editor.

`Revert'

Reverts all changes back to the state when you entered the program editor.

As all program functions you write will reside in this one window, we will need to separate them from each other. In BeeBase this is done by the DEFUN command. Everything between the two parenthesis will be part of the function pedigree in this example:

(DEFUN pedigree ()

; This is DEFUN's end parenthesis
)

With this in mind we now type in the first function which will produce a family tree of the current person in the database and place the result in field `Result'. This pedigree function is in fact three functions:

• pedigree which sets `Control.Result' by calling another function.

• getpedigree which collects the pedigree into a nested list.

• pedigree2memo which converts this list to the memo.

; The program pedigree

(DEFUN pedigree ()
    (SETQ Control.Result (pedigree2memo (getpedigree Person NIL) 0 3))
)


; The program getpedigree

(DEFUN getpedigree (person:Person level:INT)
    (IF (AND person (OR (NULL level) (> level 0)))
        (LIST person.Name
            (getpedigree person.Father (1- level))
            (getpedigree person.Mother (1- level))
        )
    )
)


; The program pedigree2memo

(DEFUN pedigree2memo (pedigree:LIST indent:INT level:INT)
    (IF (> level 0)
        (+
            (pedigree2memo (NTH 1 pedigree) (+ indent 8) (1- level))
            (IF pedigree (SPRINTF "%*s%s\n" indent "" (FIRST pedigree)) "\n")
            (pedigree2memo (NTH 2 pedigree) (+ indent 8) (1- level))
        )
        ""
    )
)

When typing this program, make sure that all the parenthesis are where they should be. Too many or too few parenthesis is the most common error you get when BeeBase is compiling your program. The error message from BeeBase probably is `Syntax Error' in this case. Press `Compile & close' and the window closes, which means that there weren't any mistakes during compiling.

Don't worry too much if you don't understand all the functions at first. There is a complete chapter (see Programming BeeBase) containing a reference of all functions including their detailed descriptions.

Now we have a program to run, but first we have to assign the program function to the `Pedigree' button. This is done by entering the structure editor, selecting `Control' in the table section and double-clicking on the `Pedigree' field in the field section. Then open the list-view `Trigger'. In this list, all your program functions will be listed, currently there should be three functions: pedigree, getpedigree and pedigree2memo. Double-click on pedigree as the program function the `Pedigree' button will trigger, then press `Ok' and leave the structure editor.

Now if everything is done correctly, pushing the `Pedigree' button will produce a pedigree of the current person. Try changing person to see some different pedigrees.

4.12 Programming BeeBase to List a Person's Children

As the next addition to this database requires some more records, you should add your brothers and sisters. If you don't have any then write `My faked sister 1', `My faked brother 1' which of course should be set to have the same parents as you have.

Then go to the program editor and type the following for creating another program.

; The program children counts the number of children of a person.
; First we define the variables, e.g. "names" holds the children's names.

(DEFUN children ()
    (LET ( (names "") (count 0) (parent Person) )

    ; For all records in table Person do the following:
    ; If the variable parent appears as father or mother 
    ; in any of the records then:
    ;     add the name to the variable names
    ;     increase count by 1.

    (FOR ALL Person DO
        (IF (OR (= parent Father) (= parent Mother))
            (
                (SETQ names (+ names Name "\n"))
                (SETQ count (1+ count))
            )
        )
    )

    ; Then we write the result into the Control.Result.
    ; If the current person doesn't have any children, write one string.
    ; If he/she has children then write another string.

    (SETQ Control.Result 
        (+ Person.Name (IF (> count 0)
            (+ " is the proud parent of " (STR count) " children.")
            " does not have any children (yet :-)."
        ))
    )


    ; If the parent has children then add their names.

    (IF (<> count 0)
        (SETQ Control.Result 
            (+ Control.Result "\n\n"
                (IF (= count 1)
                    "The child's name is:"
                    "The children's names are:" 
                )
		"\n\n"
                names
            )
        )
    )

    ; This is the end parenthesis of the LET-command.
    )

; This is the end parenthesis of DEFUN children.
)

To create variables, we use the LET command. Variables created with the LET command are local and only visible within the `LET' command's open and closing parentheses. Thus any command that accesses these variables has to be placed within these parentheses.

All we need to execute this program is a new program button. Therefore, enter the structure editor and add a button field in table `Control'. Call it `Children' and choose children as the program function it should trigger.

To bring some order in the mask of table `Control' it's now time to introduce groups. All objects can be ordered into vertically or horizontally aligned groups.

In the display section, click on `Pedigree' and shift-click on `Children', thereafter you click on the `Group' button to the left. Now the two program buttons will be together in a vertically aligned group. However, we want this one to be horizontally aligned so double-click on the `VGroup' that has appeared in the display section. This will open a window that lets you change the settings for this group. Set the title to `Programs' and check the `Horizontal' button.

At this time we can hide the name of field `Result' in table `Control'. Double-click on `Result' in the display section and empty the title field. This will display field `Result' without any title string.

To make things easier, if we add more programs or fields in table `Control', we should place `Result' and the `Programs' group into a vertical group. Be sure that you have only marked `Programs' and `Result' then press `Group'. This places `Programs' and `Result' into a vertical group.

Leave the structure editor and take a look at the result. Then press the `Children' button to see the number of children and their names of the current person.

This example could very well be extended into a fully-grown pedigree program. The only real limits are your fantasy and the size of your hard drive.

This document was generated on August, 22 2022 using texi2html