programmable relational database
with graphical user interface
Below documentation is part of the MUIbase dictribution and is also available in PDF.
6. Managing Projects
In this chapter you find:
6.1 File Format
A MUIbase project consists of several files stored in a directory owned by the project. This directory is first created when you save the project. Do not make any assumption about the directory structure or filenames inside the directory. In particular, do not remove or place any files or further directories in this directory! They will get lost when reorganizing the project.
The directory contains a file called `Structure.mb' where the descriptions of all tables, attributes, filters, etc. are stored. The record headers are also placed here. For each table you will find a file with the table's name. Here all records of a table are stored. Last but not least there may be several files named `.lock', `.plock' and `.rlock'. These are used for managing access to the project. Several MUIbase instances may open the project for reading, and acquire a shared access to the `.lock' file. But only one instance is allowed to make changes by acquiring the `.rlock' file, and storing the changes back to disk by acquiring the `.plock' file. Note that for the 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 MUIbase distances on a particular file system before relying on this feature.
MUIbase 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 attributes) then this value is far from accurate.
6.3 New Project
MUIbase 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 MUIbase 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. It's also possible to only load the structure of a project, that is, the whole project is loaded except the record data. To do so, select menu item `Project - Open - Structure'.
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 MUIbase 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.mb' is recreated. Before creating the new `Structure.mb' file, MUIbase first renames a possibly existing `Structure.mb' 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 attribute 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 Admin and User Mode
MUIbase 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.8 Check Data Integrity
MUIbase can verify if all data in your project is still valid and not corrupted by programs trashing your project files or by system crashes. Choose menu item `Project - Check data integrity' for starting this process.
Usually you should never need this functionality and MUIbase should always report that data integrity is perfect. But if it ever happens to you that your project contains `internal errors', that is, some records can't be loaded anymore, then you can repair your project by using this menu item.
MUIbase will write a log file of all affected records and you can save and reorganize the project afterwards. In the log file, records that might be corrupted and records that are not accessible anymore and therefore have been deleted are listed by their record number in the old (corrupted) project and by their record number (in parenthesis) in the reorganized project.
6.9 Swap Records
MUIbase 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 MUIbase should use for the records of a project. Choose one of the predefined values found in menu item `Preferences - Record memory' (see Record memory). MUIbase 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 MUIbase runs out of memory or if the upper limit for the record memory size has been reached then MUIbase tries to free as much record memory as possible. In this case MUIbase may write modified records to disk to get the maximum available memory possible. You can also force MUIbase to do this by choosing menu item `Project - Swap records'.
MUIbase 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 MUIbase makes sure that by reloading you can always go back to the point of the last save operation. MUIbase 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.
This document was generated on September, 11 2016 using texi2html