RWDBManager Class Reference

A monostate class that manages RWDBDatabase instances, thus mediating access to database servers. More...

#include <rw/db/dbmgr.h>

Static Public Member Functions
static RWDBDatabase	database (const RWCString &serverType, const RWCString &serverName, const RWCString &userName, const RWCString &password, const RWCString &databaseName, const RWDBDatabaseCallback &databasecb=RWDBDatabaseCallback())
static RWDBDatabase	database (const RWCString &serverType, const RWCString &serverName, const RWCString &userName, const RWCString &password, const RWCString &databaseName, const RWCString &propertyString, const RWDBDatabaseCallback &databasecb=RWDBDatabaseCallback())
static bool	emptyStringIsNull ()
static void	emptyStringIsNull (bool n)
static RWDBStatus::ErrorHandler	errorHandler ()
static RWDBStatus::ErrorHandler	setErrorHandler (RWDBStatus::ErrorHandler handler)
static RWCString	version ()
static void *	xaSwitch (const RWCString &serverType)

Detailed Description

There is a single, global RWDBManager in charge of producing RWDBDatabase instances typed according to the application's request. It mediates access to database servers, abstracting details of access to vendor-supplied libraries, including any dynamic loading and linking. The RWDBManager, through its database() method, is responsible for filling requests for database implementations of a particular type. To do so, it maintains a set of database types for which it is able to produce an implementation.

Associated with each database type is a method that produces the implementation. Once this method is invoked, a connection is established and the result is returned to the caller. In a static build, this method resides in the statically linked Access Module library. In a dynamic build, this method resides in the dynamically-linked Access Module library that is loaded at runtime.

Synopsis

#include <rw/db/dbmgr.h>

RWDBDatabase myDbase = RWDBManager::database("myDbaseType",
                        "myDbaseServerName", "myLoginName",
                        "myPassword", "myDbaseName");

DB XA Module

For the DB XA Module you provide a sixth parameter, propertyString, defined with key XA=xaParameter. This produces an XA-enabled RWDBDatabase object. For database-specific values of xaParameter, see the DB XA Module User's Guide.

RWDBDatabase myDbase = RWDBManager::database("myDbaseType",
                       "", "", "", "", "XA=xaParameter");

Member Function Documentation

static RWDBDatabase RWDBManager::database ( const RWCString &  serverType, const RWCString &  serverName, const RWCString &  userName, const RWCString &  password, const RWCString &  databaseName, const RWDBDatabaseCallback &  databasecb = RWDBDatabaseCallback()  )

static

Produces an RWDBDatabase. The first parameter lets the DB Interface Module identify the kind of database being requested. The remaining parameters except the last are used to establish a session with the requested database server. Since the details of logging into a database vary widely among vendors, the actual values supplied for the various parameters vary according to the DB Access Module which will be used. Your DB Access Module guide explains the values you must supply to obtain RWDBDatabase instances from your library. The last parameter provides an instance of the RWDBDatabaseCallback to be associated with the produced RWDBDatabase object.

Note

If no Access Module library is found for the serverType requested, the object being returned has a status of RWDBStatus::notFound.

static RWDBDatabase RWDBManager::database ( const RWCString &  serverType, const RWCString &  serverName, const RWCString &  userName, const RWCString &  password, const RWCString &  databaseName, const RWCString &  propertyString, const RWDBDatabaseCallback &  databasecb = RWDBDatabaseCallback()  )

static

Produces an RWDBDatabase. The first parameter lets the DB Interface Module identify the kind of database being requested. The remaining parameters except the last are used to establish a session with the requested database server. Since the details of logging into a database vary widely among vendors, the actual values supplied for the various parameters vary according to the DB Access Module which will be used. Your DB Access Module guide explains the values you must supply to obtain RWDBDatabase instances from your library. The last parameter provides an instance of the RWDBDatabaseCallback to be associated with the produced RWDBDatabase object.

Note

If no Access Module library is found for the serverType requested, the object being returned has a status of RWDBStatus::notFound.

DB XA Module: The sixth parameter, propertyString, is used to set the key XA=xaParameter.

static bool RWDBManager::emptyStringIsNull ( )

static

Retrieves the setting of this flag.

static void RWDBManager::emptyStringIsNull ( bool  n )

static

Allows an application to specify whether the RWDBDatabase instance produced by the call to RWDBManager::database() treats empty strings as NULL values.

The default setting is false, which means that empty strings are handled as the database vendor normally handles them. If this flag is set to true, empty strings are treated as NULL values by SourcePro DB.

Note that the SQL92 standard does not specify if empty strings are NULL values or not. Various database vendors treat empty strings differently. For example, Oracle considers an empty string to be the same as a NULL, while other database vendors do not. Consider the following example:

RWCString  empty;
RWDBInserter  ins=aTbl.inserter();
ins<<empty;
ins.execute();

If the setting is true, the SQL generated is like:

insert into sometable values(NULL)

Otherwise, it is like:

insert into sometable values('')

However, these two SQL statements mean the same to Oracle. Setting the flag to true has no effect.

static RWDBStatus::ErrorHandler RWDBManager::errorHandler ( )

static

Retrieves the error handler currently installed in the RWDBManager, if any.

static RWDBStatus::ErrorHandler RWDBManager::setErrorHandler ( RWDBStatus::ErrorHandler  handler )

static

Installs handler as the error handler for the RWDBManager. The supplied handler is inherited by all RWDBDatabase instances created by the RWDBManager. By default, the RWDBManager error handler does nothing; this method overrides the default.

static RWCString RWDBManager::version ( )

static

Returns a string that identifies the version of the DB Interface Module in which self resides.

Note

This method does not identify the version of the DB Access Module being used. To see the DB Access Module Version, use RWDBDatabase::version().

static void* RWDBManager::xaSwitch ( const RWCString &  serverType )

static

DB XA Module Only

Returns a database-specific XA switch table based on the server type. The switch table is a structure that lists the names of the xa_ routines implemented in the resource manager. Note that this function returns a void*, which must be cast to a struct xa_switch_t pointer.