Neoview ODBC Drivers Manual (R2.5)

aware of each other. A connection in a connection pool can be used repeatedly by multiple
components.
NOTE: Connection pooling can be used by an ODBC application exhibiting ODBC 2.x behavior,
as long as the application can call SQLSetEnvAttr. When using connection pooling, the application
must not execute SQL statements that change the database or the context of the database, such
as changing the database name, which changes the catalog used by a data source.
The connection pool is maintained by the Driver Manager. Connections are drawn from the pool
when the application calls SQLConnect or SQLDriverConnect, and are returned to the pool when
the application calls SQLDisconnect. The size of the pool grows dynamically based upon the
requested resource allocations. It shrinks based on the inactivity timeout: If a connection is
inactive for a period of time (it has not been used in a connection), it is removed from the pool.
The size of the pool is limited only by memory constraints and limits on the server.
The Driver Manager determines whether a specific connection in a pool should be used according
to the arguments passed in SQLConnect or SQLDriverConnect, and the connection attributes
set after the connection was allocated.
When the Driver Manager is pooling connections, it needs to be able to determine if a connection
is still working before handing the connection out. Otherwise, the Driver Manager keeps on
handing out the dead connection to the application whenever a transient network failure occurs.
In ODBC 3.5 a connection attribute, SQL_ATTR_CONNECTION_DEAD, has been defined. This
is a read-only connection attribute that returns either SQL_CD_TRUE or SQL_CD_FALSE. The
value SQL_CD_TRUE means that the connection has been lost, while the value SQL_CD_FALSE
means that the connection is still alive.
A driver must implement this option efficiently, or it will impair the connection pooling
performance. Specifically, a call to get this connection attribute should not cause a round trip to
the server. Instead, a driver should just return the last known state of the connection. The
connection is dead if the last trip to the server failed, and not dead if the last trip succeeded.
To use a connection pool, an application performs the following steps:
1. Enables connection pooling by calling SQLSetEnvAttr to set the
SQL_ATTR_CONNECTION_POOLING environment attribute to
SQL_CP_ONE_PER_DRIVER or SQL_CP_ONE_PER_HENV. This call must be made before
the application allocates the shared environment for which connection pooling is to be
enabled. The environment handle in the call to SQLSetEnvAttr should be set to null, which
makes SQL_ATTR_CONNECTION_POOLING a process-level attribute. If the attribute is
set to SQL_CP_ONE_PER_DRIVER, a single connection pool is supported for each driver.
If an application works with many drivers and few environments, this may be more efficient
because fewer comparisons may be required. If set to SQL_CP_ONE_PER_HENV, a single
connection pool is supported for each environment. If an application works with many
environments and few drivers, this may be more efficient because fewer comparisons may
be required. Connection pooling is disabled by setting
SQL_ATTR_CONNECTION_POOLING to SQL_CP_OFF.
2. Allocates an environment by calling SQLAllocHandle with the HandleType argument set
to SQL_HANDLE_ENV. The environment allocated by this call will be an implicit shared
environment because connection pooling has been enabled. The environment to be used is
not determined, however, until SQLAllocHandle with a HandleType of SQL_HANDLE_DBC
is called on this environment.
3. Allocates a connection by calling SQLAllocHandle with InputHandle set to
SQL_HANDLE_DBC, and the InputHandle set to the environment handle allocated for
connection pooling. The Driver Manager attempts to find an existing environment that
matches the environment attributes set by the application. If no such environment exists,
one is created, with a reference count (maintained by the Driver Manager) of 1. If a matching
Connections 17