Overview of the MicroKernel Engine
The Btrieve API is a low-level interface to the MicroKernel Engine that embodies functional aspects of the database design that might be otherwise transparent in higher-level interfaces such as SQL, Java, or ODBC. For example, the SQL interface operates independently of how the data is physically stored. However, the MicroKernel Engine developer must consider lower level aspects such as page size, physical and logical currency, type verification, and data validation. Despite these low-level considerations, the Btrieve API provides excellent flexibility and control over the data.
The MicroKernel Engine stores information in files, which can be up to 256 GB in size for PSQL 9.5 and later, (128 GB for earlier 9.x versions, and 64 GB for other earlier versions). Inside each data file are records, which contain bytes of data. A file can contain up to 4 billion records.
The data in a record might represent an employee name, ID, address, phone number, rate of pay, and so on. However, the MicroKernel Engine interprets a record only as a collection of bytes; it does not recognize logically discrete pieces of information within a record. To the MicroKernel Engine, a last name, first name, employee ID, and so on do not exist inside a record.
The only discrete portions of information that the MicroKernel Engine recognizes in a record are keys. Keys provide both fast, direct access to records and a means of sorting records by key values. Because the MicroKernel Engine has no way of knowing the structure of the records in each file, you define each key by identifying the following:
•
Number. This is the key’s order in the list of keys. Version 6.0 and later files can have gaps between key numbers. That is, the MicroKernel Engine does not require keys to be numbered consecutively. When you add a key, you can specify a key number or let the MicroKernel Engine assign the lowest available key number. When you drop a key, you can leave the remaining key numbers as is or let the MicroKernel Engine renumber them consecutively.
•
Position. This is the key’s offset in bytes from the beginning of the record.
•
Length. This is the number of bytes to use for the key.
•
Type. This is the key’s data type.
•
Attributes. These provide additional information about how you want the MicroKernel Engine to handle the key values. The MicroKernel Engine supports these key attributes: segmentation, duplicatability, modifiability, sort order, case sensitivity, alternate collating sequence, and null value.
You can create or drop keys at any time. For each key defined in a data file, the MicroKernel Engine builds an index. The index is stored inside the data file itself. The index maps each key value in the file to an offset in the actual data. Normally, when accessing or sorting data, the MicroKernel Engine does not search through all the records in the file. Instead, it searches the index and then manipulates only those records appropriate to the request.
You can create indexes when you create the data file, or any time thereafter. When you create a data file, you can define one or more keys for the MicroKernel Engine to use in building indexes.
You can also define external indexes after creating a file. An external index file is a standard data file that contains records sorted by the key you specify. Each record consists of the following:
•
A 4-byte address identifying the physical position of the record in the original data file
•
A key value
Positioning rules (guidelines governing which record is current, which is next, and so on) are the same, regardless of when you create an index.
If you create an index at the same time that you create the file, the MicroKernel Engine stores duplicate key values in the chronological order in which the records are inserted into the file. If you create an index for a file that already exists, the MicroKernel Engine stores duplicate key values in the physical order of the corresponding records in the file at the time the index is created. How the MicroKernel Engine stores duplicate key values in an index also depends on whether the key is linked-duplicatable or repeating-duplicatable. For more information, refer to Duplicatability.
*Note: The chronological ordering of records can change when you update records and change their key values, when you drop and rebuild an index, or when you rebuild the file. Therefore, you should not assume that the order of records in a file always reflects the order in which the records were inserted. If you want to track the order of record insertion, use an AUTOINCREMENT key.
You can delete, or drop, an index when your application no longer needs it. The space that the index used in the file is freed for data or for other index pages. (However, this free space remains allocated to the file; you will not see a reduction in physical file size after dropping an index.)
Refer to Chapter 5, Designing a Database for specific information about defining keys.
MicroKernel Engine Environment
Before an end user can run your MicroKernel Engine application, a version of MicroKernel Engine must be available to the end user’s computer. You should provide the end user with information about any prerequisite the MicroKernel Engine software versions and configurations that your application requires.
Configuration Notes
End users may need to know the following information about your MicroKernel Engine application. Include this information in the documentation you provide with your MicroKernel Engine application.
•
The amount of memory your application requires.
Your application may require more memory or disk space than the MicroKernel Engine requires on its own. Establish the disk space and memory requirements of your application and communicate this information to your users. For information about system requirements of the MicroKernel Engine, refer to Getting Started With PSQL and to the PSQL Web site.
•
Whether the application requires the MicroKernel Engine configuration settings other than the defaults. In particular, consider whether end users need to change these MicroKernel Engine options:
•
Create File Version. Does your application need backward compatibility with a previous version of the MicroKernel Engine? If so, instruct your end users to set an appropriate value for this option.
•
Handles. Does your application need to use more than 60 logical file handles at one time? If so, instruct your end users to set this option to an appropriate value.
•
Index Balancing. Does your application set the Index Balancing file attribute on every file it creates? If so, your end users can use the default of Index Balancing turned off. If not, you may need to instruct your end users to turn Index Balancing on at the MicroKernel level. For more information, see Index Balancing.
•
Largest Compressed Record Size. Does your application use compressed records? If so, see Record and Page Compression in Advanced Operations Guide, and Choosing a Page Size, Estimating File Size, and Record Compression in this book.
•
System Data. Do all files in your database have unique keys? If so, the files are transaction durable. If not, your end users may want to set System Data to If Needed or Always in order to make the files transaction durable.
For descriptions of configuration options, refer to the Advanced Operations Guide.