XDB Engine overview

1. XDB Engine utilization
2. Application model
3. User interface
4. Development interface
5. Database sharing
6. Data security
7. Error detection
8. Known limitations
9. Recommendations

Copyright

    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

Problem:
    You need to make conversions among e-mails stored by Netscape Communicator, Microsoft Outlook and Microsoft Internet Mail.

Solution:
    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.

Benefit:
    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

Problem:
    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.

Future plans:
    Need to make some enhancements, e.g. adding comments to save games to allow their better description.

Solutions:
    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.

    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:

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 filters.
    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

    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.
    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.

9. Recommendations

    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.

Contact:
    rawos@rawos.com
    http://www.rawos.com/xdbe