This page is also available in

Documentation

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

5. Basic Concepts

Before you start setting up your own database projects and entering data for them, you should now about some basic concepts BeeBase is built on.

5.1 Projects

A BeeBase project consists of all relevant information you need for managing your data. This includes the project's user interface, the project's data you entered and the programs you wrote for the project.

A project can be loaded from, saved to, and deleted from disk. Any change you make to a project is only done in memory. At any time you can go back to the state of the last saved project by reloading it.

BeeBase is able to handle multiple projects at a time. Therefore it is not necessary to start BeeBase twice just to load another project.

Furthermore, multiple instances of BeeBase can access the same project. Multiple instances can read the project but only one is allowed to make changes. This should also work across different computers on a network when the project is located on a mounted network drive.

5.2 Tables

BeeBase manages data in tables. A table is organized in rows and columns, where rows are called records and columns are called fields.

See the following table for an example on how to structure a set of addresses in a table.

    Name              | Street              | City
    ------------------|---------------------|------------------------
    Steffen Gutmann   | Wiesentalstr. 30    | 73312 Geislingen/Eybach
    Charles Saltzman  | University of Iowa  | Iowa City 52242
    Nicola Müller     | 21W. 59th Street    | Westmont, Illinois 60559

There exists a special table kind which can hold exactly one record. A table of this kind is sometimes useful for controlling the database project, e.g. you can put buttons into this table for executing various actions, or a read-only field for displaying project related information.

For an example suppose you have an account database where you store all your income and expense. An exactly-one table now could have a read-only field of type real for displaying the total balance.

Each table has two record pointers, a pointer to the record that is currently displayed in the user interface (called GUI record pointer) and a pointer to the record that is the current one while executing a BeeBase program (called program record pointer).

You can define any number of tables for a BeeBase project. Tables can be added to, renamed, and deleted from a project.

5.3 Records

A record is one row of a table. It holds all information about one set, e.g. in a table that manages addresses, one record holds one address.

Each record has a record number that reflects the record's position in the table. This number may change when you add or delete records.

For each table a record called initial record exists that holds the default values for initializing new records. The initial record always has a record number of 0.

Records can be added to, changed, and deleted from a table. The records are not necessary held in memory but are loaded from and stored to disk when needed. There are two restrictions for the total number of records of one table. The record number is a 32bit integer value, which (theoretically) limits the total number of records to 4294967295. Another (and more severe) limitation is that for each record a small record header is kept in memory. These limitations still make BeeBase usable for record numbers of 10,000 and more.

5.4 Fields

An field defines one column of a table. It specifies the type and appearance of the corresponding column.

Fields can be added to, renamed, and deleted from a table. There is no upper limit on the number of fields per table.

For each field you have to specify a type that restricts the contents of this field. See the next section for a list of available field types.

5.5 Field Types

For fields the following types are available:

Please note that once you have set the type of a field, you cannot change it later.

5.5.1 String Fields

String fields can store any single line of text (0 to 999 characters). Strings are the most often used field type in a database project. For example an address database could store the name, street, and city of a person each in its own string field.

For a string field you have to specify the maximum number of characters allowed in the string. This number does not directly affect the amount of memory or disk space that is used by this field because only the actual string contents are stored (other databases have called this feature compressed strings). If necessary the number can be changed after you have installed a string field.

String fields can also be used to store font- and filenames. For filenames external viewers can be launched to display the file contents. Furthermore an in-line image class allows displaying the image of a file.

String fields do not support the NIL value.

5.5.2 Integer Fields

Integer fields store integral values in the range of -2147483648 to 2147483647. They are mostly used for storing quantities of any kind, e.g. the number of children of a person, or the number of song titles on a CD.

Integer fields support the NIL value representing an undefined integer value.

5.5.3 Real Fields

Real fields store floating point values in the range of -3.59e308 to +3.59e308. They are used for storing numbers of any kind, e.g. the amount of money in an income/expense project.

For each real field you can specify the number of decimal places used for displaying the real value, though internally always the full precision is stored.

Real fields support the NIL value representing an undefined real value.

5.5.4 Boolean Fields

Boolean fields store one bit of information. They are used for storing yes/no or true/false values, e.g. in a project managing invoices a Boolean field could store the `has paid?' information.

Boolean fields use TRUE and NIL as Boolean values. NIL in this case stands for a value of FALSE.

5.5.5 Choice Fields

Choice fields store one item out of an enumeration of items. For example, in an address project a choice field may be used for storing a country name, where the country is one out of `USA', `Canada', `Germany', or `others'.

A choice field does not store the item string but the item number (index) in a record. The number of items and the items itself can be modified after the field has been created. However when making changes to a choice field, values in existing records are not changed to reflect the new labeling.

Choice fields do not support the NIL value.

5.5.6 Date Fields

Date fields store calendar dates. For example, a date field can be used for storing birthdays.

The format for entering and displaying date values can be one of `DD.MM.YYYY', `MM/DD/YYYY', or `YYYY-MM-DD', where `DD', `MM' and `YYYY' are standing for two and four digit values representing the day, month and year of the date respectively.

Date fields support the NIL value representing an undefined date.

5.5.7 Time Fields

Time fields store the time of day or a period of time. For example, a time field can be used for storing the durations of music titles on a CD.

The format for entering and displaying time values can be one of `HH:MM:SS', `MM:SS' or `HH:MM', where `HH' represents the hours, `MM' the minutes, and `SS' the seconds. Internally time values are stored as the number of seconds since 0 AM. Time values larger than 23:59:59 up to the maximum value of 596523:14:07 are possible but negative values are not supported.

Time fields support the NIL value representing an undefined time.

5.5.8 Memo Fields

Memo fields store multi-line text of any size. Text size is handled dynamically which means that memory is only allocated for the actual text size. In a project managing movies for example, a memo field can be used to store summaries of the movies.

Memo fields do not support the NIL value.

5.5.9 Reference Fields

Reference fields are a special type of field, normally not found in other database systems. Reference fields store a pointer to another record. The referenced record may reside in the same or in any other table the reference field belongs to.

For example in a pedigree project two reference fields can be used for storing pointers to the father and mother record. Or in a project managing CDs and music titles, a reference field in the table holding the music titles can be used to point to the records of the corresponding CDs.

For displaying a reference field, any fields of the referenced record can be specified. Entering a reference field can be done by selecting a record from a list of records.

Reference fields support the NIL value. Here a value of NIL stands for a pointer to the initial record of the referenced table.

5.5.10 Virtual Fields

Virtual fields do not store any information in the database itself, but compute them on the fly when needed.

For example, in a project managing invoices where a real field holds the amount of money excluding tax, a virtual field can be used to "store" the amount of money with tax. Every time the value of the virtual field is needed, e.g. for displaying it, it is computed from the corresponding value without tax.

For displaying virtual fields three kinds exists: Boolean, string and list. These three kinds allow showing the value of the virtual field as a TRUE/FALSE value, as a single line of text including numbers, dates, and times, or as a list of several single lines, e.g. for listing all music titles of a CD.

Virtual fields support the NIL value standing for FALSE (Boolean kind), undefined (string kind), or empty (list kind).

5.5.11 Buttons

Actually, buttons are not a real field type as they cannot store or display any information. Buttons are just used for triggering BeeBase programs.

5.6 Table of Field Types

The following table summarizes all available fields types:

Type        Description                             Nil allowed?

String      For strings (0 to 999 characters).      No
            A string can also be used for storing
            filenames, font-names or one-string-
            out-of-n-strings.  For filenames you
            can add a field where the contents
            of the file are displayed as an image.

Integer     For storing integer values              Yes
            (-2147483648 to 2147483647).

Real        For floating point numbers              Yes
            (-3.59e308 to +3.59e308).

Boolean     TRUE or NIL.                            Yes (NIL = FALSE)

Choice      One number out of n numbers.  Numbers   No
            are represented by label strings.

Date        For storing a date value                Yes
            (1.1.0000 - 31.12.9999).

Time        For storing time values                 Yes
	    (00:00:00 - 596523:14:07)

Memo        Multi-line text of unlimited length.    No

Reference   For storing a reference to a record     Yes (NIL means
            of another table.                       initial record)

Virtual     For displaying results from a BeeBase   Yes
            program.

Button      For triggering a program function       No (N/A)

5.7 Relationships

Up to now you know how to organize your information into tables with records and fields. But you may also want to setup relationships between tables.

For example if you want to collect CDs in a database project you would have two tables, one for the CDs themselves and one for the music titles of the CDs. Of course you could also have all music titles within the CD table but then you would have a fixed number of music titles for each CD.

So having these two tables, you now need a link for each music title to the CD containing this title. This is called a relationship between the two tables. In BeeBase you use a reference field for setting up such a relationship.

By installing a reference field into a table you automatically have a relationship between the table the field resides in and the table it refers to.

The following classes of relationships can be distinguished:

5.7.1 One to one Relationships

One to one relationships are very simple relationships where for each record you have one or zero partners in another or in the same table.

For example in a database project that manages your favorite movie actors you could setup a reference field called `married with' that shows the person the actor is married with. An actor that is currently not married does have a NIL value for this reference field.

Of course, no one prevents the user to set the `married with' references of several actors all to the same person. However by programming BeeBase it is possible to detect such cases and handle accordingly.

5.7.2 One to many Relationships

One to many relationships are useful for connecting a set of records to one record in another or the same table.

For example in a project managing your bank accounts you could have one table for all bank accounts and one table for all transactions. Now you surely want to know which transaction belongs to which account so you setup a reference field in the transaction table referring to the account table.

One to many relationships are the most often used ones. You can use them for managing any hierarchical-like structures, e.g. CDs with music titles, bank accounts with transactions, family trees, etc.

One to many relationships are also the basis for realizing many to many relationships as described in the next section.

5.7.3 Many to many Relationships

Many to many relationships are used when you want a set of records to refer to another set of records.

For example in a project that manages movies and actors you would have two tables, one for the movies and the other one for the actors. Now for each movie you want to know the actors that took part in the movie. So you might think to setup a reference field in the actor table that refers to the movie table. But when doing this you could only have one movie referenced for each actor because there is only one reference field in the actor table. So what you need is an unlimited number of references from the actor table to the movie table.

This is done by adding a new table that just has two reference fields, one pointing to the actor table and the other to the movie table. Now you can enter the relationships by adding new records to this table. For each movie-actor constellation you add a new record and specify the movie and actor by setting the corresponding reference fields.

If you want to know in which movies an actor took part then you only have to search for all records in the new table that refer to the actor in question and look at the movie records the found records refer to. Such a search can be done automatically by BeeBase and the result can be displayed in a list-view.

The following tables show an example of how to connect a set of actors to a set of movies.

      Title           Country
      ----------------------------
m1:   Batman          USA
m2:   Batman Returns  USA
m3:   Speechless      USA
m4:   Tequila Sunrise USA
m5:   Mad Max         Australia
m6:   Braveheart      USA

      Name
      -------------------
a1:   Michael Keaton
a2:   Jack Nicholson
a3:   Kim Basinger
a4:   Danny DeVito
a5:   Michelle Pfeiffer
a6:   Geena Davis
a7:   Christopher Reeve
a8:   Mel Gibson
a9:   Kurt Russell
a10:  Sophie Marceau
a11:  Patrick McGoohan
a12:  Catherine McCormack
a13:  Christopher Walken

      MovieRef  ActorRef
      ------------------
      m1        a1
      m1        a2
      m1        a3
      m2        a1
      m2        a4
      m2        a5
      m2        a13
      m3        a1
      m3        a6
      m3        a7
      m4        a8
      m4        a5
      m4        a9
      m5        a8
      m6        a8
      m6        a10
      m6        a11

From these tables you can find out for example that Mel Gibson took part in the movies Tequila Sunrise, Mad Max, and Braveheart, or that in movie Batman the actors Michael Keaton, Jack Nicholson, and Kim Basinger took part.

5.8 User Interface

BeeBase uses a graphical user interface (GUI) organized in a hierarchical way for displaying record contents and for entering data. Each project owns its own main window in which further GUI elements (including sub windows) can be placed. The GUI elements are also called display objects.

A table is displayed in an own GUI element called mask. A mask can display only one record at a time. Its layout and the fields included in the mask are customizable by the user.

The following GUI elements are available for designing a project's GUI layout:

5.8.1 Windows

Windows can be used to spread information of a project across several independent areas.

Each project automatically has its own main window. If needed, e.g. if the space of the main window exceeds, additional sub windows can be created. Sub windows can also have further sub windows.

For each sub window a window button can be placed into the parent window allowing to open the sub window. The window button looks like a normal text button but may show a small icon to distinguish itself from other buttons.

Main windows do not have a parent window and therefore have no window button. Closing a main window means closing the whole project.

A window can have other GUI elements as children. If no child has been added to a window then a default image is shown.

5.8.2 Masks

A mask is used to display the contents of a table. Only one record of the table can be shown at a time.

The mask may include a panel (see next section) for controlling the table. Other GUI elements like field or text objects can be placed into a mask to show the record contents.

Masks cannot be placed inside other masks as this would lead to a hierarchy of masks and therefore to a hierarchy of tables. To setup a hierarchy of tables, use an 1:n relationship between the two tables.

5.8.3 Panels

A panel is a small and wide rectangular area placed at the top edge of a mask. A panel can display a title, e.g. the name of the corresponding table, a pair of numbers showing the record number of the current record and the total number of records, and several buttons for controlling the table, e.g. for displaying the next or previous record.

A panel is part of the table mask but can be hidden if desired. If you setup a panel for a mask then an additional border is drawn around the mask.

5.8.4 Field Objects

Field objects are used to display the contents of one item of a record.

Depending on the type of the field the GUI element is either a string field (types string, integer, real, date and time), a check-mark button (type Boolean), a cycle button or a set of radio buttons (type choice), an editor field (type memo), a pop-up list-view (type reference), a text, check-mark, or list-view field (type virtual) or a text or image button (type button). In some cases the GUI element may also be a simple text field if the field object is set to read-only.

5.8.5 Text Objects

Text objects are used for describing the various field elements of a record mask or just to display some static text.

5.8.6 Images

Images can be displayed anywhere in a window. An image can be a pattern, a simple color field, or a pictures in an external file. The image size can be resize-able or fixed.

The image is static. For storing images in a table you use a string field (see String type).

5.8.7 Space Objects

Space objects are used to insert space in the layout of a window or a table mask. A space object can have a vertical (or horizontal) bar for delimiting other GUI elements.

5.8.8 Groups

GUI elements can be grouped into horizontal or vertical groups. A group places its children from left to right (horizontal group) or from top to bottom (vertical group).

A group can surround its child objects with a rectangular frame, can display an optional title at the top of the group, and can insert space between its child objects.

5.8.9 Balance Objects

Balance objects can be placed between other child objects of a window, mask, or group object. A balance object allows the user to control the weight values of the other child objects and therefore how much space each child gets.

5.8.10 Register Groups

A register group can be used to layout GUI elements into several pages where only one page is visible at a time. This is useful if the user interface becomes too large and you don't want to spread it over several windows.

This document was generated on August, 22 2022 using texi2html