RWDBConnection

Module:  DB Interface Module   Group:  Database Classes

Does not inherit

• Local Index
• Synopsis
• Description
• Public Enum
• Public Constructors
• Public Member Operators
• Public Member Functions

Members

acquire() beginTransaction() close() commitTransaction() connectionType() database()

enum ConnectionType enum IsolationType errorHandler() executeSql() isolation() isReady()

isValid() open() operator!=() operator=() operator==() release()

rollbackTransaction() RWDBConnection() setErrorHandler() setSavepoint() status() systemHandle()

#include <rw/db/connect.h>

RWDBConnection connection = myDbase.connection();

Connections represent a scarce resource that applications can allocate and manage themselves. An RWDBConnection is an object that may be requested from an RWDBDatabase, and passed to many methods to specify that the method should use the given connection. Operations requested without supplying a connection are performed using a connection supplied invisibly by RWDBDatabase. If none are available, an error results. Thus, the use of explicit connections eliminates one likely source of errors, at some cost in program complexity.

Each RWDBConnection knows which RWDBDatabase produced it, and each RWDBDatabase knows what connections it has produced.

RWDBConnection is designed around the Interface/Implementation paradigm. An RWDBConnection instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBConnection implementation is a base class from which a family of database-specific connection implementations is derived.

These are the values used for the isolation() methods:

enum IsolationType {
Unknown,                   //  the default
ANSILevel1,
ANSILevel2,
ANSILevel3
}

These are the values used for the connectionType() method:

enum ConnectionType {
Synchronous = 1
Asynchronous
}

RWDBConnection();

The default constructor creates an RWDBConnection whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBConnections. Usable RWDBConnections are obtained from RWDBDatabases.

RWDBConnection(const RWDBConnection& connection);

Copy constructor. The created object shares an implementation with connection.

RWDBConnection&
operator=(const RWDBConnection& connection);

Assignment operator. Self shares an implementation with connection.

bool 
operator==(const RWDBConnection& conn) const;

Returns true if self and conn share the same implementation. Otherwise, returns false.

bool 
operator!=(const RWDBConnection& conn) const;

Returns true if self and conn do not share the same implementation. Otherwise, returns false.

void
acquire() const;

Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.

RWDBStatus
beginTransaction(const RWCString& name=RWCString());

Sends a begin transaction, or the vendor-specific equivalent, to the database server. Here name means the name of the transaction, if you choose to supply it and the vendor supports named transactions. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
close(); 

Closes this connection. This method should only be used in exceptional circumstances, as it causes all references to this connection to become unusable. It is usually best to allow connections to close themselves as they go out of scope.

RWDBStatus
commitTransaction(const RWCString& name=RWCString());

Sends a commit transaction, or the vendor-specific equivalent, to the database server. Here name means the name of the transaction, if you choose to supply it and the vendor supports named transactions. This function can behave asynchronously if executed using an asynchronous connection.

RWDBConnection::ConnectionType
connectionType() const;

Returns the connection type of self. An RWDBConnection can be synchronous or asynchronous.

RWDBDatabase
database() const;

Provides access to the RWDBDatabase that produced the connection.

RWDBStatus::ErrorHandler
errorHandler() const;

Returns the error handler attached to self.

RWDBResult
executeSql(const RWCString& sqlProgram) const;

The SQL statement(s) in sqlProgram are submitted to the connection for execution. The DB Interface Module does not check the contents of sqlProgram for validity. The return value represents a sequence of zero or more RWDBTables. This function can behave asynchronously if executed using an asynchronous connection.

RWDBConnection::IsolationType
isolation() const;

Returns self's isolation level, as defined by the most recent call to isolation(). If isolation(RWDBConnection::IsolationType level) has not been called, returns Unknown. In this case, self's isolation level is whatever the database vendor provides by default.

RWDBStatus
isolation (RWDBConnection::IsolationType level);

Makes a database-specific call or calls to set self's isolation level to the specified level. The details vary widely among database vendor implementations. This function can behave asynchronously if executed using an asynchronous connection. See your DB Access Module guide and your database vendor's manual for exact details on isolation levels.

bool
isReady() const;

This function returns true if the object is in ready state, indicating that accessing the object will not block. Accessing a nonready object may potentially block.

bool
isValid() const;

Returns true if the status of this connection is RWDBStatus::ok, otherwise returns false.

RWDBStatus
open(); 

Reopens this connection after closing or error condition. If the connection cannot be opened for use, both the status returned and the connection will be invalid.

void
release() const;

Releases a previously acquired mutex. This function can be called from a const object. Note: in nonmultithreaded builds, this function evaluates to a no-op.

RWDBStatus
rollbackTransaction(const RWCString& name=RWCString());

Sends a rollback transaction, or the vendor-specific equivalent, to the database server. Here name means the name of the transaction, if you choose to supply it and the vendor supports named transactions. This function can behave asynchronously if executed using an asynchronous connection.

void
setErrorHandler(RWDBStatus::ErrorHandler handler);

Installs handler as the error handler for self. The supplied handler is called whenever the status of self changes to anything except RWDBStatus::ok. By default, the error handler of an RWDBConnection is inherited from the RWDBDatabase that produced the RWDBConnection; this method overrides the default. ErrorHandler is declared as a typedef within the scope of RWDBStatus:

typedef void (*ErrorHandler)(const RWDBStatus&);

RWDBStatus
setSavepoint(const RWCString& name); 

Sends a savepoint name or the vendor-specific equivalent to the database server.

RWDBStatus
status() const;

Provides the current status of this connection.

RWDBSystemHandle*
systemHandle();

This member allows an application to gain access to the underlying vendor-specific database API. The result is a pointer to the base class RWDBSystemHandle, which must be cast by the application to a derived class representing a database-specific system handle. This can be done in a type-safe manner if your compiler supports runtime type identification. See your DB Access Module guide for details on the name and contents of the database-specific system handle variants.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.