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
Local Index
Members
Synopsis
#include <rw/db/connect.h> RWDBConnection connection = myDbase.connection();
Description
In an XA environment, connections are opened and managed by the transaction processing monitor, based on criteria defined during the set-up phase of the resource manager. An RWDBConnection in this environment, does not have the responsibility of opening and closing a database connection directly with the server. Instead, it attempts to get a valid handle to a connection previously opened by the TPM. This handle is held, and used whenever it is needed.
Even though the TPM actually establishes connections, your programs will still request RWDBConnection objects from an RWDBDatabase. Connection objects specify which connection a method should use. Operations requested without supplying a connection are performed using a connection invisibly supplied by RWDBDatabase. If none are available, an error results. Thus, the use of explicit connections eliminates one likely source of errors.
In the DB Interface Module there is a restriction on the number of RWDBConnection objects that you can create. This is because the DB Interface Module makes use of connections opened by the TPM. Therefore the user should be careful when using default connections. If the number of connections requested is greater than one, the DB Interface Module will return a notSupported error (with the exception of Sybase CT).
NOTE -- We recommend that you always use explicit connections.
Because the TPM actually opens and closes connections, the following RWDBConnection member functions should not be called when using the DB Interface Module: open() and close().
Transactions in an XA environment are controlled by the TPM. Therefore, the following methods should not be called in an XA connection: beginTransaction(), commitTransaction(), rollbackTransaction(), and autocommit().
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's implementation is a base class from which a family of XA-enabled, database-specific connection implementations is derived.
Public Enum
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() methods:
enum ConnectionType {
Synchronous = 1
Asynchronous
}
These values do not have a special impact on an XA connection.
Public Constructors
RWDBConnection();
The default constructor creates an RWDBConnection whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience. Usable RWDBConnection objects are obtained from RWDBDatabases.
RWDBConnection(const RWDBConnection& connection);
Copy constructor. The created object shares an implementation with connection.
Public Member Operators
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.
Public Member Functions
void acquire() const;
The function attempts to acquire the internal mutex lock. If the mutex is already locked, the function blocks until the mutex is released. This function can be called from a const object.
RWDBStatus beginTransaction();
When used with the DB Interface Module, this function returns a notSupported error.
RWDBStatus close();
When used with the DB Interface Module, this function returns a notSupported error.
RWDBStatus commitTransaction();
When used with the DB Interface Module, this function returns a notSupported error.
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 which 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 vendors' implementations. This function can behave asynchronously if executed using an asynchronous connection. See your SourcePro Core Access Module Guide and your database vendor's manual for exact details on isolation levels.
bool isReady() const;
This function is not relevant in an XA environment, because XA connections are always synchronous. In general, this function returns true if the object is in ready state, indicating that accessing the object will not block. Accessing a non-ready object may potentially block.
bool isValid() const;
true if the status of this connection is RWDBStatus::ok, otherwise false.
RWDBStatus open();
When used with the DB Interface Module, this function returns a notSupported error.
void release() const;
This function releases a previously acquired mutex. This function can be called from a const object.
RWDBStatus rollbackTransaction();
When used with the DB Interface Module, this function returns a notSupported error.
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, an RWDBConnection's error handler is inherited from the RWDBDatabase which 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 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 RWDBSystemHandle base class, 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). For details on the name and contents of the database-specific system handle variants, see Chapter 5, "Using the DB Access Modules With XA Functionality," in the DB Interface Module User's Guide. Also see your Access Module Guide.
© 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.