getDBConnection()

Establish a connection to a database and returns a CwDBConnection object.

Syntax

CwDBConnection getDBConnection(String connectionPoolName)
 CwDBConnection getDBConnection(String connectionPoolName, 
    boolean implicitTransaction)
 

Parameters

connectionPoolName
The name of a valid connection pool. The method connects to the database whose connection is in this specified connection pool.

implicitTransaction
A boolean value to indicate the transaction programming model to use for the database associated with the connection. Valid values are:

true
Database uses implicit transaction bracketing

false
Database uses explicit transaction bracketing

Return values

Returns a CwDBConnection object.

Exceptions

CwDBConnectionFactoryException - If an error occurs while trying to establish the database connection.

Notes

The getDBConnection() method obtains a connection from the connection pool that connectionPoolName specifies. This connection provides a way to perform queries and updates to the database associated with the connection. All connections in a particular connection pool as associated with the same database. The method returns a CwDBConnection object through which you can execute queries and manage transactions. See the methods in the CwDBConnection class for more information.

By default, all connections use implicit transaction bracketing as their transaction programming model. To specify a transaction programming model for a particular connection, provide a boolean value to indicate the desired transaction programming model as the optional implicitTransaction argument to the getDBConnection() method. The following getDBConnection() call specifies explicit transaction bracketing for the connection obtained from the ConnPool connection pool:

conn = getDBConnection("ConnPool",false);
 

The connection is released when the collaboration object finishes execution. You can explicitly close this connection with the release() method. You can determine whether a connection has been released with the isActive() method. For more information, see "Releasing a connection".

Examples

The following example establishes a connection to the database associated with connections in the CustConnPool connection pool. It then uses an implicit transaction to insert and update rows into a table of the database.

CwDBConnection connection = getDBConnection("CustConnPool");
  
 // Insert a row
 connection.executeSQL("insert...");
  
 // Update rows...
 connection.executeSQL("update...");
 

Because the preceding call to getDBConnection() does not include the optional second argument, this connection uses implicit transaction bracketing as its transaction programming model (unless the transaction programming model is overridden in the Collaboration Properties dialog of System Manager). Therefore, it does not specify explicit transaction boundaries with beginTransaction(), commit(), and rollback(). In fact, an attempt to call one of these transaction methods with implicit transaction bracketing generates a CwDBTransactionException exception.

Note:
You can check the current transaction programming model with the implicitDBTransactionBracketing() method.

The following example also establishes a connection to the database associated with connections in the CustConnPool connection pool. However, it specifies the use of explicit transaction bracketing for the connection. Therefore, it uses an explicit transaction to contain the inserts and updates on rows in the database tables.

CwDBConnection connection = getDBConnection("CustConnPool", false);
  
 // Begin a transaction
 connection.beginTransaction();
  
 // Insert a row
 connection.executeSQL("insert...");
  
 // Update rows...
 connection.executeSQL("update...");
  
 // Commit the transaction
 connection.commit();
  
 // Release the connection
 connection.release();
 

The preceding call to getDBConnection() includes the optional implicitTransaction argument to set the transaction programming model to explicit transaction bracketing. Therefore, this examples uses the explicit transaction calls to indicate the boundaries of the transaction. If these transaction methods are omitted, InterChange Server handles the transaction as it would for an implicit transaction.

See also

CwDBConnection class, isActive(), release()

Copyright IBM Corp. 2003, 2004