TkbmCONNPOOL v. 0.98 (22. Jun 1999)
=========================================================================
A database connection pooling package.

BEFORE USING THIS COMPONENT, YOU ARE REQUESTED TO READ ALL OF THIS TEXT
DOCUMENT AND SPECIALLY TO NOTICE AND ACCEPT THE DISCLAIMER.

Can be used as a demonstration of how to create descendents of TDataSet,
or as in my case, to allow a program to generate temporary data that can
be used directly by all data aware controls.

Copyright 1999 Kim Bo Madsen/Optical Services - Scandinavia
All rights reserved.

You are allowed to used this component in any project for free.
You are NOT allowed to claim that you have created this component or to
copy its code into your own component and claim that is was your idea.

Im offering this for free for your convinience, and the ONLY thing I DEMAND
is to get an E-MAIL about what project this component (or dirived versions)
is used for. That will be my reward of offering this component for free to you!

You dont need to state my name in your software, although it would be
appreciated if you do.

If you find bugs or alter the component (f.ex. see suggested enhancements
further down), please DONT just send the corrected/new code out on the internet,
but instead send it to me, so I can put it into the official version. You will
be acredited if you do so.

Usage
=====

The components are heavily based on TkbmMemTable and thus that component MUST
exist to be able to install the TkbmConnPool package.

- Put a TDatabase on a datamodule. It will only be used as a template for
    internal database components.
- Put a TSession on the datamodule (if you require threaded operation) and 
    set its AutoSessionName to true.
- Put a TkbmConnectionPool on the datamodule and set the Database property to
    point at the TDatabase you previously added. Set the max. number of
    simultanious connections to the database. There can be more than
    one TkbmConnectionPool on a form for different databases. The
    TkbmConnectionPool pool queries and queue them in an intelligent
    way. The seemingly fastest and shortest queue is allways used for 
    a new query.
- Put a TkbmPooledSession on the datamodule Connect it to the TkbmConnectionPool.
    It handles multisession (multithreaded) environments.
- Create a new datamodule which will be cloned every time a new thread (web session)
    is started.
- Now put as many TkbmPooledQuery or TkbmPooledStoredProc as you need on
    the session datamodule and connect them to the TkbmPooledSession component.
    Optionally set the Sync property to either Async or Sync. If set to Sync, the
    queries/sproc will be executed in the queues in the order that they were executed
    in the application. If set to Async, they will be executed as fast as possible
    even in parallel.
    Beware that the components are READONLY. If you want to modify a record, you
    have to do it with SQL UPDATE commands. You ofcourse can use the
    TkbmPooledQuery for that purpose.

Components
==========

TkbmConnectionPool
------------------
Properties:

  MaxConnections (R/W, Integer) Max. number of concurrent database connections
				shared among all users and queries.

  CurConnections (R, Integer)	Returns current number of established database
				connections.

  CurConnectionsOwnerIDs (R, string)
				Returns the owner ID's as a string of the currently
				active connections.

  CurRequests (R, Integer)	Returns current number of queued requests.

  Database (R/W, TDatabase)	The database that is to be used as a template
				for new database connections.

  MaxCacheAge (R/W, integer)	How old in secs. can a cached entry be before its discarded.

  MaxCacheEntries (R/W, integer)
				How many entries can be cached before the least used will
				be discarded.

  EnableCache (R/W, boolean)	Do caching or not.

  ConnectionTimeout (R/W, integer)
				How many secs. will a connection to the database 
				be held after the last use before it is closed.

  GarbageInterval (R/W, integer)
				How many secs between each garbage collection.

  GarbageCollection (R/W, boolean)
				Will garbage collection happen? Garbage collection
				takes care of removing timedout cached entries and
				connections.

  CacheHits (R, longint)	Number of cache hits.
  CacheMisses (R,longint)	Number of cache misses.

Events:
  OnGetLogonParams(DBTemplate:TDatabase; ConnID:integer; var dbParams:TStringList)
				Called whenever a new database connection is to be
				made. ConnID is the number of the new connection (<MaxConnections).
				dbParams contains the parameters (f.ex. user name/password etc) to
				be used in creating a new database connection.

  OnGarbageCollection (R/W, TkbmConnectionPoolGarbageCollection)
				Called each time a garbage collection is starting.

Methods:
  TimeoutConnections;		Mark all connections to be timed out.
  KillConnections;		Kill all connections as fast as possible.



TkbmPooledSession
-----------------
Properties:

   ConnectionPool (R/W, TkbmConnectionPool) The connectionpool to connect to.
  
   AutoSessionName (R/W, boolean) If to generate sessionnames automatically.
				  Should be true for multithreaded applications.

   SessionName (R/W, string)	  The logical name of this session (can be any string).
				  If AutoSessionName=true then SessionName will be
			 	  modified to always being unique.

   ThreadSessionName (R, string)  The unique version of SessionName if AutoSessionName=true.

   OwnerID (R/W, integer)	  A number identifying the current user of this session.
				  Can be used to track who is doing what.

   IsLocked (R, boolean)	  Returns true if this session is locked for sync. use.

   SessionNumber (R/W, integer)	  A user defined number. Not used by the system.   

Methods:
   function LockSession(Sync:boolean):TkbmConnection
				  Returns a connection object. If sync=true, locks the session
				  for synchrone use only.
   procedure UnlockSession;	  Unlocks the session object.

TkbmPooledDataSet
-----------------
   The ancestor of all pooled datasets. Inherits from TkbmMemTable which inherits from TDataset.

Properties:

   Sync (R/W, TkbmPooledSync)	  Either kpssAsync or kpssSync.
   SessionName (R/W, string)      Refers to the SessionName of a TkbmPooledSession.
   CacheHits (R, longint)	  Number of hits in the cache for this dataset.
   CacheMisses (R, longint)	  Number of misses in the cache for this dataset.
   Cached (R/W, boolean)	  Cache the contents of this dataset?
   CacheParams (R/W, TParamType)  Also cache the parameters (in/out) of this dataset?
   IsFromCache (R,boolean)	  Returns true if the answer for the request came from the cache.
   MaxCacheRecordCount (R/W,integer)
				  Dont cache datasets with more than this number of rows.

TkbmPooledQuery
---------------
   Inherits from TkbmPooledDataSet.
   Has the same functionality as TQuery + TkbmPooledDataSet + TkbmMemTable.

TkbmPooledStoredProc
--------------------
   Inherits from TkbmPooledDataSet.
   Has the same functionality as TStoredProc + TkbmPooledDataSet + TkbmMemTable.

Please see the comments in the start of the componentsource for whats new
in this release.

DISCLAIMER
By using this component or parts theiroff you are accepting the full
responsibility of the use. You are understanding that the author cant be
made responsible in any way for any problems occuring using this component.
You also recognize the author as the creator of this component and agrees
not to claim otherwize!

Please forward corrected versions (source code ONLY!), comments,
and emails saying you are using it for this or that project to:
           kbm@optical.dk
//=============================================================================

History:
   Please look in the sourcecode.

Contributors: