 |  LoginProducts  SalesSupportDownloadsAbout |
| Home » Technical Support » DBISAM Technical Support » Product Manuals » DBISAM Version 4 Manual for RAD Studio 2009 (C++) » Using DBISAM » DBISAM Architecture |
DBISAM ArchitectureIntroduction
DBISAM is a database engine that can be compiled directly into your Delphi or C++ application, be it a program or library, or it can be distributed as a runtime package (equivalent to a library) as part of your application. DBISAM was written in Delphi's Object Pascal and can be used with the VCL (Windows only).
General Architecture
DBISAM itself is a lightweight engine encapsulated within the TDBISAMEngine component. When the TDBISAMEngine EngineType property is set to etClient, the TDBISAMEngine component is acting as a local client engine, and when the EngineType property is set to etServer, the TDBISAMEngine component is acting as a database server.
Sessions
DBISAM is session-based, where a session is equivalent to a virtual user and is encapsulated within the TDBISAMSession component. There can be many sessions active in a given application, such as is the case with a multi-threaded application. In multi-threaded applications DBISAM requires a separate session for each thread performing database access. Please see the Multi-Threaded Applications topic for more information.
A DBISAM session can be either local or remote:
A developer can mix as many local and remote sessions in one application as needed, thus enabling a single application to access data from a local hard drive, a shared file server, or a database server. Also, local and remote sessions are completely identical from a programming perspective, offering both navigational and SQL access methods. The only changes needed to switch from local access to remote access for a session component is the modification of the TDBISAMSession SessionType property.
Database Server
The database server listens for regular data connections on one port and administrative connections on a second port. All administrative connections must be encrypted or they will be rejected by the database server. When the TDBISAMEngine Active property is set to True, the database server will start listening on the IP addresses and ports indicated by the following properties:
ServerMainAddress
ServerMainPort
ServerAdminAddress
ServerAdminPort
If the either ServerMainAddress or ServerAdminAddress property is blank (the default), the database server will listen on all IP addresses available for the type of connection (either regular or administrative). The default ports are 12005 for the ServerMainPort property and 12006 for the ServerAdminPort property. Once the server is started, you cannot change any of these properties, as well as several other properties. Please see the Configuring and Starting the Server topic for more information.
The database server is a multi-threaded server that uses one thread per client connection, which corresponds to a client TDBISAMSession component set to run as a remote session via the SessionType property. DBISAM will cache threads and keep a pool of unused threads available in order to improve connect/disconnect times. The following properties control the default thread cache size uses by the database server:
ServerMainThreadCacheSize
ServerAdminThreadCacheSize
The default for the ServerMainThreadCacheSize property is 10 threads and the default for the ServerAdminThreadCacheSize property is 1. Both of these properties must be set before the engine is started and cannot be changed when the engine is started.
"Dead" sessions in the database server are sessions that have been inactive for a connection timeout period (configurable) due to lack of client session requests or due to a physical network interruption in service. Such sessions retain their complete state from the time that the disconnect occurred. The sessions remain in this state until:
The age of a dead session is determined by the last time that the session was connected to the server.
Please see the Server Administration topic for more information on configuring these settings on the server.
You can configure the remote sessions on the client to ping the database server at regular intervals via the TDBISAMSession RemotePing and RemotePingInterval properties. Configuring remote sessions to ping the database server in a smaller time period than the connection timeout configuration on the database server allows you to specify a smaller dead session expiration timeout and prevent sessions with active locks from being left around for too long. With pinging turned on, the only reason a session would be disconnected by the server is if the client workstation or the physical network connection has failed.
You may have a database server (or several) accessing a given database at the same time as other local applications such as CGI or ISAPI web server applications. This allows you to put critical server-side processing on the server where it belongs without incurring a lot of unnecessary overhead that would be imposed by the transport protocol of the database server. This can improve the performance of server-based local applications significantly, especially when they reside on the same machine as the database server and the databases being accessed are local to the server machine.
The database server allows you to configure all users, databases, server-side procedures, and scheduled events via a remote administrative connection or directly via the TDBISAMEngine component. User security at the database and server-side procedure level allows the configuration of read, execute, insert, update, delete, create, alter, drop, rename, maintain, backup, and restore privileges for a specific user or users. Additionally, you may allow or block specific IP addresses or ranges of IP addresses (using wildcards) for access to a given database server. A maximum number of connections may be set to prevent too many inbound connections to a given server. Because the database server does not actively establish any communication with a client session and all communication is controlled by the client session, you do not have issues with firewalls as long as the firewall allows for inbound access to the main port and/or administration port on the server. Please see the Server Administration topic for more information.
All connections, errors, and other operational messages are logged and can be retrieved at a later time by an administrator for examination.
Databases and Directories
DBISAM uses the physical directories in the operating system's file system to represent databases. This is true for both local sessions and remote sessions, however with remote sessions these directories are abstracted through logical database names in the server configuration. This allows applications written to use remote sessions connecting to a database server to be portable between different servers with different directory layouts. DBISAM creates a single hidden file called "dbisam.lck" (by default) in a database directory that is used for locking. It is created as needed and may be deleted if not in use by DBISAM. However, if DBISAM cannot write to this file it will treat the database as read-only. Please see the Locking and Concurrency topic for more information.
The default lock file name "dbisam.lck" can be modified to any file name desired by modifying the TDBISAMEngine LockFileName property.
Physical Table Layout
DBISAM tables are divided into up to 3 physical files, one for data records, one for indexes, and one for BLOB data (if there are BLOB fields present in the table):
The file extensions used for these physical files can be changed. Please see the Customizing the Engine topic for more information. The default file extensions are as follows:
In addition, during certain operations such as altering a table's structure, backup files will be created for the physical table files. The default backup file extensions are as follows:
Finally, during the process of upgrading a table from a previous version's format to the latest format, backup files will be created for the physical table files. The default backup file extensions for upgraded tables are as follows:
Please see the Upgrading Tables topic for more information.
Component Architecture
DBISAM includes the following components:
Opening a TDBISAMTable or TDBISAMQuery component will automatically cause its corresponding TDBISAMDatabase component to open, which will also automatically cause its corresponding TDBISAMSession component to start, which will finally cause the TDBISAMEngine to start. This design ensures that the necessary connections for a session, database, etc. are completed before the opening of the table or query is attempted.
DBISAM is a database engine that can be compiled directly into your Delphi or C++ application, be it a program or library, or it can be distributed as a runtime package (equivalent to a library) as part of your application. DBISAM was written in Delphi's Object Pascal and can be used with the VCL (Windows only).
General Architecture
DBISAM itself is a lightweight engine encapsulated within the TDBISAMEngine component. When the TDBISAMEngine EngineType property is set to etClient, the TDBISAMEngine component is acting as a local client engine, and when the EngineType property is set to etServer, the TDBISAMEngine component is acting as a database server.
Sessions
DBISAM is session-based, where a session is equivalent to a virtual user and is encapsulated within the TDBISAMSession component. There can be many sessions active in a given application, such as is the case with a multi-threaded application. In multi-threaded applications DBISAM requires a separate session for each thread performing database access. Please see the Multi-Threaded Applications topic for more information.
A DBISAM session can be either local or remote:
| Session Type | Description |
| Local | A local session gains direct access to database tables via the operating system API to a given storage medium, which can literally be any such medium that is accessible from the operating system in use. This means that a local session on the Windows operating system could access database tables on a Linux file server. DBISAM automatically provides for the sharing of database tables using a local session. For example, an application can use local sessions on a small peer-to-peer network to provide a low-cost, multi-user solution without the added expense of using the client-server version of DBISAM. A local session has all of the capabilities of a remote session except for user and database security, which are only available from a database server. Also, with a local session a directory is synonymous with a database, whereas with a remote session databases are defined as part of the server configuration and the DBISAM client does not know the actual location of a given database. |
| Remote | A remote session uses sockets to communicate to a database server over a network (or on the same physical machine) using the TCP/IP protocol. DBISAM allows a remote session to be entirely encrypted using strong crypto. Compression is also available for remote sessions and can be changed whenever it is deemed necessary in order to improve the data transfer speed. This is especially important with low-bandwidth connections like a dial-up Internet connection. A remote session connects to a given database server via an IP address or host name and one of two different ports, depending upon whether the connection is a regular connection or an administrative connection. Before a remote session can perform any operation on a database server it must be logged in with a proper user ID and password. If a remote session is connecting to the administration port on a database server, the user ID specified during the login must be that of an administrator or the login will be rejected. Also, an administrative connection must be encrypted or the database server will reject the connection. |
A developer can mix as many local and remote sessions in one application as needed, thus enabling a single application to access data from a local hard drive, a shared file server, or a database server. Also, local and remote sessions are completely identical from a programming perspective, offering both navigational and SQL access methods. The only changes needed to switch from local access to remote access for a session component is the modification of the TDBISAMSession SessionType property.Database Server
The database server listens for regular data connections on one port and administrative connections on a second port. All administrative connections must be encrypted or they will be rejected by the database server. When the TDBISAMEngine Active property is set to True, the database server will start listening on the IP addresses and ports indicated by the following properties:
ServerMainAddress
ServerMainPort
ServerAdminAddress
ServerAdminPort
If the either ServerMainAddress or ServerAdminAddress property is blank (the default), the database server will listen on all IP addresses available for the type of connection (either regular or administrative). The default ports are 12005 for the ServerMainPort property and 12006 for the ServerAdminPort property. Once the server is started, you cannot change any of these properties, as well as several other properties. Please see the Configuring and Starting the Server topic for more information.
The database server is a multi-threaded server that uses one thread per client connection, which corresponds to a client TDBISAMSession component set to run as a remote session via the SessionType property. DBISAM will cache threads and keep a pool of unused threads available in order to improve connect/disconnect times. The following properties control the default thread cache size uses by the database server:
ServerMainThreadCacheSize
ServerAdminThreadCacheSize
The default for the ServerMainThreadCacheSize property is 10 threads and the default for the ServerAdminThreadCacheSize property is 1. Both of these properties must be set before the engine is started and cannot be changed when the engine is started.
"Dead" sessions in the database server are sessions that have been inactive for a connection timeout period (configurable) due to lack of client session requests or due to a physical network interruption in service. Such sessions retain their complete state from the time that the disconnect occurred. The sessions remain in this state until:
- The client session attempts another data request or pings the server, in which case the connection will automatically be re-established transparently between the client session and the database server.
- The database server's dead session expiration time period (configurable) is reached and the database server automatically removes the session.
- The number of dead sessions on the database server reaches the maximum threshhold (configurable), thus causing the database server to remove dead sessions in order to bring the number back under the threshhold, oldest dead session first.
The age of a dead session is determined by the last time that the session was connected to the server.Please see the Server Administration topic for more information on configuring these settings on the server.
You can configure the remote sessions on the client to ping the database server at regular intervals via the TDBISAMSession RemotePing and RemotePingInterval properties. Configuring remote sessions to ping the database server in a smaller time period than the connection timeout configuration on the database server allows you to specify a smaller dead session expiration timeout and prevent sessions with active locks from being left around for too long. With pinging turned on, the only reason a session would be disconnected by the server is if the client workstation or the physical network connection has failed.You may have a database server (or several) accessing a given database at the same time as other local applications such as CGI or ISAPI web server applications. This allows you to put critical server-side processing on the server where it belongs without incurring a lot of unnecessary overhead that would be imposed by the transport protocol of the database server. This can improve the performance of server-based local applications significantly, especially when they reside on the same machine as the database server and the databases being accessed are local to the server machine.
The database server allows you to configure all users, databases, server-side procedures, and scheduled events via a remote administrative connection or directly via the TDBISAMEngine component. User security at the database and server-side procedure level allows the configuration of read, execute, insert, update, delete, create, alter, drop, rename, maintain, backup, and restore privileges for a specific user or users. Additionally, you may allow or block specific IP addresses or ranges of IP addresses (using wildcards) for access to a given database server. A maximum number of connections may be set to prevent too many inbound connections to a given server. Because the database server does not actively establish any communication with a client session and all communication is controlled by the client session, you do not have issues with firewalls as long as the firewall allows for inbound access to the main port and/or administration port on the server. Please see the Server Administration topic for more information.
All connections, errors, and other operational messages are logged and can be retrieved at a later time by an administrator for examination.
Databases and Directories
DBISAM uses the physical directories in the operating system's file system to represent databases. This is true for both local sessions and remote sessions, however with remote sessions these directories are abstracted through logical database names in the server configuration. This allows applications written to use remote sessions connecting to a database server to be portable between different servers with different directory layouts. DBISAM creates a single hidden file called "dbisam.lck" (by default) in a database directory that is used for locking. It is created as needed and may be deleted if not in use by DBISAM. However, if DBISAM cannot write to this file it will treat the database as read-only. Please see the Locking and Concurrency topic for more information.
The default lock file name "dbisam.lck" can be modified to any file name desired by modifying the TDBISAMEngine LockFileName property.Physical Table Layout
DBISAM tables are divided into up to 3 physical files, one for data records, one for indexes, and one for BLOB data (if there are BLOB fields present in the table):
| File Type | Description |
| Data File | Used to store a fixed-length header for table-wide definitions such as the table description, field counts, autoinc values, etc., the fixed-length field definitions for the table, and the fixed-length data records themselves. The use of a fixed-length header, field definitions, and data records allows for easier verification and/or repair of tables in the case of physical table corruption. Please see the Verifying and Repairing Tables topic for more information. All data records contain a small record header and the field data. BLOB fields contains a link to the BLOB file where the actual variable-length BLOB data is stored in a blocked format. |
| Index File | Used to store a fixed-length header for index statistics, index counts, etc., the fixed-length index definitions, and the fixed-length index pages themselves. The index page size is variable and can be set between 1024 bytes and 16 kilobytes on a per-table basis. All index pages for all primary, secondary, and full text indexes are stored in this file. |
| BLOB File | Used to store a fixed-length header for BLOB statistics, etc. and the fixed-length BLOB blocks themselves. The BLOB block size is variable and can be set between 64 bytes and 64 kilobytes on a per-table basis. All BLOB blocks for all BLOB fields are stored in this file. |
The file extensions used for these physical files can be changed. Please see the Customizing the Engine topic for more information. The default file extensions are as follows:
| File Type | File Extension |
| Data File | .dat |
| Index File | .idx |
| BLOB File | .blb |
In addition, during certain operations such as altering a table's structure, backup files will be created for the physical table files. The default backup file extensions are as follows:
| File Type | Backup File Extension |
| Data File | .dbk |
| Index File | .ibk |
| BLOB File | .bbk |
Finally, during the process of upgrading a table from a previous version's format to the latest format, backup files will be created for the physical table files. The default backup file extensions for upgraded tables are as follows:
| File Type | Upgrade Backup File Extension |
| Data File | .dup |
| Index File | .iup |
| BLOB File | .bup |
Please see the Upgrading Tables topic for more information.
Component Architecture
DBISAM includes the following components:
| Component | Description |
| TDBISAMEngine | The TDBISAMEngine component encapsulates the DBISAM engine itself. A TDBISAMEngine component is created automatically when the application is started and can be referenced via the global Engine function in the dbisamtb unit (Delphi) and dbisamtb header file (C++). You can also drop a TDBISAMEngine component on a form or data-module to visually change its properties. However, only one instance of the TDBISAMEngine component can exist in a given application, and both the global Engine function and any TDBISAMEngine component on a form or data module point to the same instance of the component (singleton model). The TDBISAMEngine component can be configured so that it acts like a local or client engine (etClient) or a database server via the EngineType property. The engine can be started by setting the Active property to True. |
| TDBISAMSession | The TDBISAMSession component encapsulates a session in DBISAM. A default TDBISAMSession component is created automatically when the application is started and can be referenced via the global Session function in the dbisamtb unit (Delphi) and dbisamtb header file (C++). The TDBISAMSession component can be configured so that it acts like a local (stLocal) or a remote session (stRemote) via the SessionType property. A local session is single-tier in nature, meaning that all TDBISAMDatabase components connected to the session reference directories in a local or network file system via the Directory property and all TDBISAMTable or TDBISAMQuery components access the physical tables directly from these directories using operating system API calls. A remote session is two-tier in nature, meaning that all access is done through the remote session to a database server using the DBISAM messaging protocol over a TCP/IP connection. The database server is specified through the following properties: RemoteHost or RemoteAddress RemotePort or RemoteService In a remote session, all TDBISAMDatabase components reference databases that are defined on the database server via the RemoteDatabase property and all TDBISAMTable or TDBISAMQuery components access the physical tables through the DBISAM messaging protocol rather than directly accessing them. You cannot activate remote sessions in an application whose TDBISAMEngine component is configured as a database server via the EngineType property.A session can be started by setting the Active property to True or by calling the Open method. The TDBISAMSession component contains a SessionName property that is used to give a session a name within the application. All sessions must have a name before they can be started. The default TDBISAMSession component is called "Default". The TDBISAMDatabase, TDBISAMTable, and TDBISAMQuery components also have a SessionName property and these properties are used to specify which session these components belong to. Setting their SessionName property to "Default" or blank ("") indicates that they will use the default TDBISAMSession component. Please see the Starting Sessions topic for more information. |
| TDBISAMDatabase | The TDBISAMDatabase component encapsulates a database in DBISAM. It is used as a container for a set of tables in a physical directory for local sessions or as a container for a set of tables in a database on a database server for remote sessions. Please see the Server Administration topic for more information on defining databases on a database server. A database can be opened by setting the Connected property to True or by calling the Open method. A TDBISAMDatabase component contains a DatabaseName property that is used to give a database a name within the application. All databases must have a name before they can be opened. The TDBISAMTable and TDBISAMQuery components also have a DatabaseName property and these properties are used to specify which database these components belong to. Please see the Opening Tables topic for more information. The TDBISAMDatabase Directory property indicates the physical location of the tables used by the TDBISAMTable and TDBISAMQuery components. If a TDBISAMDatabase component is being used with a local session (specified via the SessionName property), then its Directory property should be set to a valid physical path for the operating system in use. The TDBISAMDatabase RemoteDatabase property indicates the name of a database defined on a database server. If a TDBISAMDatabase component is connected to a remote session (specified via the SessionName property), then its RemoteDatabase property should be set to a valid database for the database server that the session is connected to. The TDBISAMDatabase component is used for transaction processing via the StartTransaction, Commit, and Rollback methods. Please see the Transactions topic for more information. You can backup and restore databases via the Backup, BackupInfo, Restore methods. Please see the Backing Up and Restoring Databases topic for more information. |
| TDBISAMTable | The TDBISAMTable component encapsulates a table cursor in DBISAM. It is used to search and update data within the physical table specified by the TableName property, as well as create the table or alter its structure. A table cursor can be opened by setting the Active property to True or by calling the Open method. The DatabaseName property specifies the database where the table resides. Please see the Opening Tables topic for more information. The TDBISAMTable component descends from the TDBISAMDBDataSet component, which descends from the TDBISAMDataSet component, which descends from the common TDataSet component that is the basis for all data access in Delphi and C++. None of these lower-level components should be used directly and are only for internal structuring purposes in the class hierarchy. You can have multiple TDBISAMTable components using the same physical table. Each TDBISAMTable component maintains its own active index order, filter and range conditions, current record position, record count statistics, etc. |
| TDBISAMQuery | The TDBISAMQuery component encapsulates a single SQL statement or multiple SQL statements in DBISAM. These SQL statements may or may not return a result set. It is used to search and update data within the physical tables specified by the SQL statement or statements in the SQL property. An SQL statement or statements can be executed by setting the Active property to True, by calling the Open method (for SQL statements that definitely return a result set), or by calling the ExecSQL method (for SQL statements that may or may not return a result set). The DatabaseName property specifies the database where the table or tables reside. Please see the Executing SQL Queries topic for more information. The TDBISAMQuery component descends from the TDBISAMDBDataSet component, which descends from the TDBISAMDataSet component, which descends from the common TDataSet component that is the basis for all data access in Delphi and C++. None of these lower-level components should be used directly and are only for internal structuring purposes in the class hierarchy. You can have multiple TDBISAMQuery components using the same physical table. Each TDBISAMQuery component maintains its own result set filter and range conditions, current record position, record count statistics, etc. |
Opening a TDBISAMTable or TDBISAMQuery component will automatically cause its corresponding TDBISAMDatabase component to open, which will also automatically cause its corresponding TDBISAMSession component to start, which will finally cause the TDBISAMEngine to start. This design ensures that the necessary connections for a session, database, etc. are completed before the opening of the table or query is attempted.
More Support Options
This web page was last updated on Thursday, November 16, 2023 at 10:39 AM | Privacy PolicySite Map © 2024 Elevate Software, Inc. All Rights Reserved Questions or comments ?  E-mail us at info@elevatesoft.com |
