| Data Types | ||
| enum ConnectionType |
enum IsolationType |
#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.
RWBoolean operator==(const RWDBConnection& conn) const;
Returns TRUE if self and conn share the same implementation. Otherwise, returns FALSE.
RWBoolean 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. DBTools.h++ 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 DBTools.h++ access library guide and your database vendor's manual for exact details on isolation levels.
RWBoolean 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.
RWBoolean 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 DBTools.h++ access library guide for details on the name and contents of the database-specific system handle variants.
©Copyright 1999, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.