Icon Starting Sessions

Introduction
As already discussed in the DBISAM Architecture topic, the TDBISAMSession component represents a session in DBISAM. The following information will show how to start a session in an application.

Preparing a Local Session for Startup
If a TDBISAMSession component has its SessionType property set to stLocal, then it is considered a local session as opposed to a remote session. There is nothing extra that must be done to prepare a local session for startup.

Preparing a Remote Session for Startup
If a TDBISAMSession component has its SessionType property set to stRemote, then it is considered a remote session as opposed to a local session. Starting a remote session will cause DBISAM to attempt a connection to the database server specified by the RemoteAddress or RemoteHost and RemotePort or RemoteService properties. In addition, the RemoteEncryption property indicates whether the session's connection to the database server will be encrypted using the RemoteEncryptionPassword property. You must set these properties properly before trying to open the remote session or an exception will be raised.

The RemoteAddress and RemoteHost properties are normally mutually exclusive. They can both be specified, but the RemoteHost property will take precedence. The host name used for the server can be specified via the "hosts" text file available from the operating system. In Windows 98, for example, it's located in the Windows directory and is called "hosts.sam". Renaming this file to just "hosts" and adding an entry in it for the database server will allow you to refer to the database server by host name instead of IP address. The following is an example of an entry for a database server running on a LAN:

192.168.0.1     DBISAMLANServer

This is sometimes more convenient than remembering several IP addresses for different database servers. It also allows the IP address to change without having to modify your application.

The RemotePort and RemoteService properties are also normally mutually exclusive. They can both be specified, but the RemoteService property will take precedence. By default the ports that DBISAM database servers use are:

PortUsage
12005Normal access
12006Administrative access

These ports can be changed, however, so check with your administrator or person in charge of the database server configuration to verify that these are the ports being used.

The service name used for the database server can be specified via the "services" text file available from the operating system. In Windows 98, for example, it's located in the \Windows directory and is called "services". Adding an entry in it for the database server's port will allow you to refer to the server's port by service name instead of port number. The following is an example of an entry for both the normal server port and the administrative port:

DBISAMServer     12005/tcp
DBISAMAdmin     12006/tcp

This is sometimes more convenient than remembering the port numbers for different database servers. It also allows the port number to change without having to modify your application.

The RemoteEncryption property can be set to either True or False and determines whether the session's connection to the server will be encrypted or not. If this property is set to True, the RemoteEncryptionPassword property is used to encrypt and decrypt all data transmitted to and from the database server. This property must match the same encryption password that the database server is using or else an exception will be raised when a request is attempted on the server.

Information When connecting as an administrator to the administrative port of the database server, you must set the RemoteEncryption property to True since administrative connections always require encryption.

If for any reason DBISAM cannot connect to a database server an exception will be raised. The error code that is returned when a connection fails is 11280 and is defined as DBISAM_REMOTECONNECT in the dbisamcn unit (Delphi) or dbisamcn header file (C++). It's also possible for DBISAM to be able to connect to the server, but the connection will be rejected due to the database server's maximum connection setting being reached (11282 and defined as DBISAM_REMOTEMAXCONNECT), the database server not accepting any new logins (11281 and defined as DBISAM_REMOTENOLOGIN), the database server blocking the client workstation's IP address from accessing the server (11283 and defined as DBISAM_REMOTEADDRESSBLOCK), or an encrypted connection being required by the database server (11277 and defined as DBISAM_REMOTEENCRYPTREQ).

The RemoteUser and RemotePassword properties can be used to automate the login to a database server. Every DBISAM database server uses the following default user ID and password if the database server is being started for the first time, or if it is being started with an empty or missing configuration file:

User ID: Admin (case-insensitive)
Password: DBAdmin (case-sensitive)

Starting a Session
To start a session you must set the TDBISAMSession Active property to True or call its Open method. For a local session (SessionType property is set to stLocal), the session will be opened immediately. As discussed above, for a remote session (SessionType property is set to stRemote), performing this operation will cause the session to attempt a connection to the database server specified by the RemoteAddress or RemoteHost and RemotePort or RemoteService properties. If the RemoteUser and RemotePassword properties are specified and are valid, then neither the OnRemoteLogin event nor the interactive login dialog will be triggered. If these properties are not specified or are not valid, the OnRemoteLogin event will be triggered if there is an event handler assigned to it. If an event handler is not assigned to the OnRemoteLogin event, DBISAM will display an interactive login dialog that will prompt for a user ID and password. All database servers require a user ID and password in order to connect and login. DBISAM will allow for up to 3 login attempts before issuing an exception. The error code that is returned when a connection fails due invalid login attempts is 11287 and is defined as DBISAM_REMOTEINVLOGIN in the dbisamcn unit (Delphi) or dbisamcn header file (C++).

Information Any version of DBISAM for Delphi 6 or higher (including C++Builder 6 and higher) requires that you include the DBLogDlg unit to your uses clause in order to enable the display of a default remote login dialog. This is done to allow for DBISAM to be included in applications without linking in the forms support, which can add a lot of unnecessary overhead and also cause unwanted references to user interface libraries. This is not required for Delphi 5 or C++Builder 5, but these versions always include forms support.

The OnStartup event is useful for handling the setting of any pertinent properties for the session before the session is started. This event is called right before the session is started, so it is useful for situations where you need to change the session properties from values that were used at design-time to values that are valid for the environment in which the application is now running. The following is an example of using an OnStartup event handler to set the remote connection properties for a session:

void __fastcall TMyForm::MySessionStartup(TObject *Sender)
{
   TRegistry *Registry = new TRegistry;
   try
      {
      Registry->RootKey=HKEY_LOCAL_MACHINE;
      if (Registry->OpenKey("SOFTWARE/My Application",false)
         {
         if (Registry->ReadBool("IsRemote"))
            {
            MySession->SessionType=stRemote;
            MySession->RemoteAddress=Registry->ReadString("RemoteAddress");
            MySession->RemotePort=Registry->ReadString("RemotePort");
            }
         else
            {            
            MySession->SessionType=stLocal;
            }
         }
      else
         {
         ShowMessage("Error reading connection information "+
                     "from the registry");
         }
      }
   __finally
      {
      delete Registry;
      }
}

Information You should not call the session's Open method or toggle the Active property from within this event handler. Doing so can cause infinite recursion.

The OnShutdown event can be used for taking specific actions after a session has been stopped. As is the case with the OnStartup event, the above warning regarding the Open method or Active property also applies for the OnShutDown event.

More Session Properties
After a session is started, it can also be used to control certain global settings for all TDBISAMDatabase, TDBISAMQuery, and TDBISAMTable components that link to the session via their SessionName properties. The properties that represent these global settings are detailed below:

PropertyDescription
ForceBufferFlushControls whether the session will automatically force the operating system to flush data to disk after every write operation completed by DBISAM. Please see the Buffering and Caching topic for more information.
LockProtocolControls whether the session will use a pessimistic or optimistic locking model when editing records via navigational or SQL methods. Please see the Locking and Concurrency topic for more information.
LockRetryCountControls the number of times that the engine will retry a record or table lock before raising an exception. This property is used in conjunction with the LockWaitTime property.
LockWaitTimeControls the amount of time, in milliseconds, that the engine will wait in-between lock attempts. This property is used in conjuction with the LockRetryCount property.
KeepConnectionsControls whether temporary TDBISAMDatabase components are kept connected even after they are no longer needed. This property has no effect upon a local session, but can result in tremendous performance improvements for a remote session, therefore it defaults to True and should be left as such in most cases.
PrivateDirControls where temporary files generated by DBISAM are stored for a local session. This property is ignored for remote sessions.
ProgressStepsControls the maximum number of progress events that any batch operation will generate. Setting this property to 0 will cause the suppression of all progress messages.
StrictChangeDetectionControls whether DBISAM will use strict or lazy change detection for the session. The default is False, or lazy change detection. Please see the Change Detection topic for more information.

Information You can modify all of the above session properties both before and after a session is started. However, they do not have any effect upon a session until the session is actually started.
Image