 SourcePro® 2023.1 |
SourcePro® API Reference Guide |
Represents an explicit database connection object that can be used in place of the implicit database connection provided by RWDBDatabase. More...
#include <rw/db/connect.h>
Public Types | |
| enum | ConnectionType { Synchronous, Asynchronous } |
| enum | IsolationType { Unknown, ANSILevel1, ANSILevel2, ANSILevel3 } |
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 the 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.
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.
The DB Interface Module restricts the number of RWDBConnection objects you can create. This is because the DB Interface Module makes use of connections opened by the TPM. Therefore, you should be careful when using default connections. If the number of connections requested is greater than one, the DB Interface Module returns a RWDBStatus::notSupported error (with the exception of Sybase).
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(), and rollbackTransaction().
These are the values used for the connectionType() methods:
| Enumerator | |
|---|---|
| Synchronous |
Connection type is set to Synchronous. |
| Asynchronous |
Connection type is set to Asynchronous. |
These are the values used for the isolation() methods:
| RWDBConnection::RWDBConnection | ( | ) |
The default constructor creates an RWDBConnection with a status of RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBConnection instances. Usable RWDBConnection objects are obtained from an RWDBDatabase.
| RWDBConnection::RWDBConnection | ( | const RWDBConnection & | connection | ) |
Copy constructor. The created object shares an implementation with connection.
| void RWDBConnection::acquire | ( | void | ) | 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.
| RWDBStatus RWDBConnection::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.
DB XA Module: Returns a RWDBStatus::notSupported error.
| RWDBStatus RWDBConnection::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.
DB XA Module: Returns a RWDBStatus::notSupported error.
| RWDBStatus RWDBConnection::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.
DB XA Module: Returns a RWDBStatus::notSupported error.
| ConnectionType RWDBConnection::connectionType | ( | ) | const |
Returns the connection type of self. An RWDBConnection can be Synchronous or Asynchronous.
| RWDBDatabase RWDBConnection::database | ( | ) | const |
Provides access to the RWDBDatabase that produced the connection.
| RWDBStatus::ErrorHandler RWDBConnection::errorHandler | ( | ) | const |
Returns the error handler attached to self.
| RWDBResult RWDBConnection::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 RWDBTable objects. This function can behave asynchronously if executed using an asynchronous connection.
| RWDBStatus RWDBConnection::isolation | ( | 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.
| IsolationType RWDBConnection::isolation | ( | ) | const |
Returns self's isolation level, as defined by the most recent call to isolation(IsolationType). If isolation(IsolationType) has not been called, returns Unknown. In this case, self's isolation level is whatever the database vendor provides by default.
| bool RWDBConnection::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 RWDBConnection::isValid | ( | ) | const |
Returns true if the status of this connection is RWDBStatus::ok, otherwise returns false.
| RWDBStatus RWDBConnection::open | ( | ) |
Reopens this connection after closing or an error condition. If the connection cannot be opened for use, both the status returned and the connection will be invalid.
DB XA Module: Returns a RWDBStatus::notSupported error.
| bool RWDBConnection::operator!= | ( | const RWDBConnection & | conn | ) | const |
Returns true if self and conn do not share the same implementation. Otherwise, returns false.
| RWDBConnection& RWDBConnection::operator= | ( | const RWDBConnection & | connection | ) |
Assignment operator. Self shares an implementation with connection.
| bool RWDBConnection::operator== | ( | const RWDBConnection & | conn | ) | const |
Returns true if self and conn share the same implementation. Otherwise, returns false.
| void RWDBConnection::release | ( | void | ) | const |
Releases a previously acquired mutex. This function can be called from a const object.
| RWDBStatus RWDBConnection::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.
DB XA Module: Returns a RWDBStatus::notSupported error.
| void RWDBConnection::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 RWDBStatus::ErrorHandler is inherited from the RWDBDatabase that produced self; this method overrides the default.
| RWDBStatus RWDBConnection::setSavepoint | ( | const RWCString & | name | ) |
Sends a savepoint name or the vendor-specific equivalent to the database server.
| RWDBStatus RWDBConnection::status | ( | ) | const |
Provides the current status of this connection.
| RWDBSystemHandle* RWDBConnection::systemHandle | ( | ) | const |
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.
DB XA Module: See the chapter on using the DB access modules with XA functionality in the DB XA Module User's Guide.
| const RWZone& RWDBConnection::timeZone | ( | ) | const |
Returns a reference to the time zone set on self. If the time zone is not set, returns RWZone::local(). When self is produced, it inherits the time zone setting from the producer RWDBDatabase object. If the time zone was not set on the RWDBDatabase object at the time, the time zone is not set on self.
Sets the time zone used when extracting the date and time data from the RWDateTime objects sent to the database, and when creating the RWDateTime objects from the date and time data retrieved from the database. When the time zone is not set, RWZone::local() is used. When self is produced, it inherits the time zone setting from the producer RWDBDatabase object. If the time zone was not set on the RWDBDatabase object at the time, the time zone is not set on self.
| zone | The time zone to be set on self. Pass NULL to unset the time zone setting. |
NULL when the time zone was not set.|
Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |