This page is also available in

Documentation

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

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6. Managing Projects

In this chapter you find:

6.1 File format		BeeBase uses SQLite3.
6.2 Info		Information about the current project.
6.3 New project		Starting a new project.
6.4 Clear project		Resetting a project.
6.5 Open project		Loading project from disk.
6.6 Save project		Saving project to disk.
6.7 Export as SQLite3 database		Exporting project to a common database format.
6.8 Admin and user mode		Restricting access to project structure.
6.9 Swap records		Memory management of records.
6.10 Close project		Freeing project resources.

6.1 File Format

A BeeBase project is stored as an SQLite3 database. If you are curious, you can use a viewer or editor for SQLite3 files, such as `DB Browser for SQLite', and inspect a BeeBase project file. The contents of the SQLite3 database are somewhat self-explanatory as all information are kept in a readable format, but there are a few things to know that are non-obvious.

All SQLite tables and columns that start with an underscore `_' are used by BeeBase for bookkeeping and for storing the structure and graphical layout of the project.
All other tables are the ones defined by the user in the BeeBase project.
Date values are stored as an integer which represents the number of days since `1.1.0000' using the `Gregorian calendar'.
Time values are stored as an integer which represents the number of seconds since `00:00:00'.
References to records in tables are stored as an integer that corresponds to the `_ID' column of the referenced row.
All record IDs (stored in `_ID') are re-enumerated when reorganizing a project.

It is best not to make any changes to a project file, but if you feel like you want to experiment, here are the rules.

Any change to a project file is best carried out as a single transaction. For example, the `DB Browser for SQLite' allows to edit an SQLite file and then write back all changes in one transaction.
You can add new rows, change rows, or delete rows in a user table. When adding a new row, the `_ID' column should be an unused ID, preferably larger than any existing `_ID' in the same table. When changing a row, also change the `_Version' column in the same row, e.g. by increasing it by 1. In order for BeeBase to notice any change in the project, the `Version' column in the `_Project' table also needs to be increased. BeeBase will then reload the project and update itself based on the changed records.
Column `SavedWith' in table `_Project' should be updated with a meaningful text (e.g. the name of the program that last updated the project).
Changing other BeeBase tables (starting with an underscore `_') is probably a bad idea. But if you do, you also need to increase `StructureVersion' in addition to `Version' in the `_Project' table.

SQLite allows to connect multiple instances of BeeBase to the same project. Several BeeBase instances may open the project for reading, but only one instance is allowed to make changes. Note that for this locking mechanism to work, the file system needs to meet certain guarantees. It is best practice to first test the sharing of a project between different BeeBase instances on a particular file system before relying on this feature.

6.2 Info

BeeBase keeps some information about each project. Select menu item `Project - Info' to get information about the current project. The information you get consists of the project's name, the number of tables, the total number of records in all tables, and a value that shows how many bytes a reorganization of this project would gain. The gain is however only a rough estimate and should not be treated as an exact number. Especially if you have made many changes to the structure of the project (adding or removing fields) then this value is far from accurate.

6.3 New Project

BeeBase can handle any number of projects at a time. You are only limited by the available memory. In order to start another project, choose menu item `Project - New'. This opens a new window with an empty project. You can now define the structure of this project (see Structure editor) or load an existing project from disk (see Open project).

6.4 Clear Project

To reset a project select menu item `Project - Clear - Project'. This closes the current project and replaces it by an empty project. After starting BeeBase without projects you arrive in this state automatically.

By selecting menu item `Project - Clear - Records' you start a new project using the structure of the current one. This means that all except the record data of the current project is used for the new project.

If the current project at the time you selected one of above menu items has not been saved to disk then a dialog appears asking for confirmation of the operation.

6.5 Open Project

To load a project select menu item `Project - Open - Project'. This opens a file dialog where you can choose a project from. There are also several demo projects that illustrate the capabilities of BeeBase. To load one of them, select menu item `Project - Open - Demo'.

If the loaded project has its program source set to external, the external source file is created after opening the project (see External program source).

If you were editing a project at the time of choosing any of the above menu items and the project has not been saved then a dialog appears asking for confirmation.

You can also reload a new version of the current project from disk by choosing menu item `Project - Reload'.

6.6 Save Project

All changes you make to a project are only done in memory or stored temporarily when swapping records (see Swap records). Thus if you want to make them permanent you have to save the project to disk. This is done by choosing menu item `Project - Save'. If your project doesn't have a name yet then a file dialog asking for a filename appears first.

The reason why BeeBase does not automatically save a project when it is changed, is that, this way, it is you who decides when to save a project! You can always go back to the last saved version of your project by choosing menu item `Project - Revert to saved'. This mechanism is similar to the `COMMIT' and `ROLLBACK' commands in SQL database systems.

If you save a project, all modified records are written to disk and the file `Structure.bbs' is recreated. Before creating the new `Structure.bbs' file, BeeBase first renames a possibly existing `Structure.bbs' file to `Structure.old' to have a safety copy in case the save operation fails.

This mechanism guarantees fast load & save operations but it is not free of reorganization. If you have modified many records then the physical place where the records lie and the resulting fragmentation may become disadvantageous. Therefore a menu item `Project - Save & reorg' exists that does a save & reorganize operation. This operation may take some time depending on the number and size of the records. The save & reorganize operation creates a new directory and rewrites all project related files. The old directory is deleted on success.

Another good time to schedule a reorganization is when you have done changes to the data-structure of a project, e.g. after you have installed a new field in a table. These changes are not applied immediately to all records because it would take too much time to load each record, modify it, and save it back to disk. Therefore these changes are put on an internal `todo' list which is applied after loading a record. Applying this list to a record takes only little time. However the longer the list gets the more time it needs. Reorganizing a project causes the `todo' list to be applied to all records, so if you have made many changes to the project structure then reorganizing a project will shorten the time for loading records.

You can also save & reorganize a project to a new filename keeping the old project untouched. To do this select menu item `Project - Save & reorg as' which prompts you to enter a new name for the project.

6.7 Export as SQLite3 Database

BeeBase uses a custom binary format for storing a project (see File format). If you would like to view your project in a different database system, you can export it to the popular SQLite3 format by choosing menu item `Project - Export as SQLite3 database'. This stores all project data including the project structure in an SQLite3 file. There are many tools and viewers that can read and write SQLite3 files. At this point, however, it is not possible to read an SQLite3 file back into BeeBase.

6.8 Admin and User Mode

BeeBase operates either in admin mode (default) or in user mode. You can change between these modes by choosing menu item `Project - Change to admin mode' and `Project - Change to user mode'. When in user mode, several menu items are disabled and structure, program and query editor are not available. Therefore, only basic record editing is possible. In admin mode all operations are permitted.

An admin password can be set for a project by selecting menu item `Project - Change admin password'. Once set, the password has to be entered when changing into admin mode, or permission is denied leaving the project in user mode.

When opening a project that has an admin password set, the project is started in user mode, otherwise (no admin password has been set), it is started in admin mode.

6.9 Swap Records

BeeBase doesn't need to keep all records of a project in memory. Thus loading and saving of projects is much faster. When loading a project, a record header is allocated for each record. The data itself is only loaded when needed, e.g. when it is displayed on the screen. The total number of records is still limited by available memory since each record header needs some few bytes of memory.

You can specify how much memory BeeBase should use for the records of a project. Choose one of the predefined values found in menu item `Preferences - Record memory' (see Record memory). BeeBase does not preallocate a block of the specified memory size, it only checks from time to time if the current size of allocated memory is larger than the specified value.

If BeeBase runs out of memory or if the upper limit for the record memory size has been reached then BeeBase tries to free as much record memory as possible. In this case BeeBase may write modified records to disk to get the maximum available memory possible. You can also force BeeBase to do this by choosing menu item `Project - Swap records'.

BeeBase maintains a free list for each record file. If you delete a record then the record's file space is added to the free list. Also if you change a record and the record needs to be written to disk then the old file space is added to the free list. However BeeBase makes sure that by reloading you can always go back to the point of the last save operation. BeeBase will not write into areas which are free but where a record still exists that could be reached by reopening the project.

6.10 Close Project

When you are done editing a project you can close it by selecting menu item `Project - Close'. This frees the memory and all resources belonging to the project. If the project contains changes that have not been saved yet then a dialog appears first offering to save, continue or cancel the operation.

For closing a project you can also select menu item `Project - Save & close' which saves the project first if there were any changes and then closes it.