XDB Engine overview
Table of contents
All versions of XDB Engine and XDB Core - Copyright © Tomáš Koutný.
License, Warranty and Distribution
All XDB Engine and XDB Core versions files except source code
are freeware, but whenever you will use them or copy them to another storage medium, you
must include information of their origin - i.e. this site. There is no warranty for these
files and no one is liable for any damage, which can be done by using these files. You're
accepting this by using these files. If you don't agree with all conditions, you must
delete these files immediately.
Source code can not be treated like any form of freeware, shareware, public domain or similar kind of software if not declared differently.
Status of this document
This document describes only main aspects of XDB Engine and its utilization and presumes knowledge of XDB Engine user and development interfaces.
1. XDB Engine utilization
XDB Engine implements object oriented database kernel which may
completely customized and extended with random number of additional drivers that allows
you to implement your own database look to any data in your applications. In current
version, the XDB Engine is supplied with driver supporting .XDB
format (done by XDB Core) that has character of universal data container and that is
easily extendable to store database data like indexes, queries, forms and so on.
XDB Engine interface hides any detail of data storing and gives you abstract object oriented model that is common for every supported data. It has been built over .XDB data format and by this you no longer need to define your own file organization when you need to store any kind of data, but you can easily use XDB Engine as universal data container. Drivers are not limited only to files, but can be for example used to implement file systems (ability of XDB Core), network communications or e-mail senders. XDB Engine also allows you to store random byte sequences as records' items and their length is limited only by operating systems.
Example of non-standard utilization of XDB Engine
You need to make conversions among e-mails stored by Netscape Communicator, Microsoft Outlook and Microsoft Internet Mail.
Obtain or develop drivers, for each product one driver, that see e-mails like database and you have to program following task:
1. Open e-mails to be converted. (database 1)
2. Create or open destination for them. (database 2)
3. Make (database 1).SaveAs (database 2) - implementation of method TXDBase.Assimilate
4. Close opened files.
Your conversion abilities are limited only by the count of drivers you have. Drivers can be multipurpose, e.g. instead of conversion driver can send or print e-mails.
Example of XDB Engine utilization as universal data container
You plan to program perfect game and progress of games will be stored as sequence of bytes and string describing name of stored game, so that you have to store these save games somehow.
Need to make some enhancements, e.g. adding comments to save games to allow their better description.
1. You will program your own code how to store this and then you will face problems with new file format.
2. Use XDB Engine and add to table with saved games column representing comments. NULL values can be treated like empty strings. 100% file compatibility - no problems to solve.
2. Application model
Libraries XDBStCll.DLL and XDBCustoms.DLL are not implemented in current version, but XDBEngine.DLL is able to use any DLL named XDBCustoms.DLL that complies to definitions described in section Development interface. XDBStdCll.DLL can be implemented independently.
3. User interface
User interface is code that allows you to use object oriented model, but don't modify this model. User interface is everything what you need to employ XDB Engine in your applications and consists of these files:
Define abstract object oriented database model
Defines data structures used in object oriented database model
Defines data constants used in object oriented database model
Defines error codes that may happen when working with object oriented database model
Provides function that creates object oriented database model
Memory manager supplied with Delphi 5.0
How to create object oriented database model
1. Install borlndmm.dll, in Delphi it is
utilization of ShareMem unit
2. Call function CreateXDBEngine from library XDBEngine.DLL that creates object TXDBEngine
Function CreateXDBEngine(CacheSize: integer):TXDBEngine
Cache size determines maximal size of cache that can
be utilized by object that is being created. If CacheSize is zero, then the
system cache will be used. Also installs drivers supplied by XDBCore.DLL and XDBCustoms.DLL.
Drivers are freed automatically. The count of TXDBEngine objects is limited only
by operating system.
Object TXDBEngine is a parent of all opened and created databases.
4. Development interface
Development interface is code that allows to customize XDB Engine, XDB Core, XDBStdCll or to add new drivers. It is consisted of User Interface and EngineLevel.pas that defines internal relations inside of XDB Engine and its components.
How to install new filters
Drivers are in XDB Engine descendants of TAFilter
When new object of TAXEngine kind is being created, XBDEngine.DLL tries to connect libraries XDBCustoms.DLL a XDBCore.DLL. The library will be connected in case that export procedure, procedure's name is stored in AbstractLayer.RegisterFunctionName. This procedure has object TAXEngine, those one that is being create, as parameter. Each DLL can register more than one filter. With taken of TAXEngine.RegisterFilter DLL registers class TAFilter that are able to create descendants of TAXDBase, i.e. database driver.
Connected DLLs are freed automatically, but TAXEngine must free TAFilter descendant.
5. Database sharing
Object TXDBase created by XDBCore.DLL locks database files at the level of operating system, so that sharing among processes is impossible. Database can be shared in address space of application that created TXDBase object. But XDB Engine and XDB Core don't care about any multithreads processing so that application must implement its own mechanisms to keep its data safe.
6. Data security
Library XDBCore.DLL secures data in the meaning of data integrity, not in the meaning of en/decrypting.
What will happen when database operation will not be completed
Adding a new record
Record will not be saved
Deleting existing record
Record will remain unchanged or will miss some items
Changing value of record's item
Data will remain unchanged
Deleting table's column
Column will remain unchanged or will miss some data
Nothing will happen
Database is before close saved and by this way it keeps database integrity. This need enough free space on storage medium - needed size depends on the count of defined tables, see .XDB Format specification how much bytes can be needed. XDBCore.DLL prevents such problems from happening by never freeing taken disk space.
7. Error detection
Whenever error caused by work with XDB Engine
happens, the nil value is returned and/or an exception is raised - almost always Abort
is called. Application can test error reason by TXDBEngine.LastError. If it is xdbrcOK
or xdbrcUnexpected, then it was impossible to determine the reason of
Error values are defined in file XBDRetCodes.pas.
8. Known limitations
XDB Engine is currently written only for Delphi 5.0.
Because XDB Engine primary uses UNICODE to store strings there is problem with Windows 95/98 that doesn't support UNICODE as well as Windows NT. An error can happen when parsing data object under W95/98 so that you have to keep TDataObject.Parse = False under these systems. ANSI strings can be stored as RawData.
When you're creating new TXDBEngine, the system cache is always used in current implementation.
If you plan to enhance capabilities of XDB Engine and keep
compatibility or develop new drivers (filters), please e-mail
about this because FamilyID and FormatID need to generate unique
identification of what filter supports.
If you plan to use XDB Engine, please e-mail also to support its development.