RWDBDatabase

Module:  DB Interface Module   Group:  Database Classes

Does not inherit

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

Members

#define rwdbAllTypes() acquire() caseCompare() connect() connection() createProcedure() createTable() createView() cursor() dateVector() dbName()

dbStoredProcedures() dbTables() defaultConnections() deleter() dropView() emptyStringIsNull() enum tableType() environmentHandle() errorHandler() inserter() isReady()

isValid() memTable() operator!=() operator=() operator==() passWord() phraseBook() release() RWDBDatabase() selector() serverName()

serverType() setErrorHandler() status() storedProc() table() totalConnections() tracer() updater() userName() verboseAsString() version()

#include <rw/db/dbase.h>
#include <rw/db/dbmgr.h>

RWDBDatabase dBase = 
  RWDBManager::database("accessLib", "", "", "", "",
                        "XA=xaParameter");

RWDBDatabase manages connections with database servers. A database object represents a server, a user on that server, and a database opened for that user. In the DB Interface Module, database objects are produced by calling RWDBManager::database() and defining the propertyString parameter with key XA=xaParameter. Class RWDBDatabase provides an interface for obtaining XA-enabled database-specific objects. For database-specific values of xaParameter, see the User's Guide.

---

NOTE -- In an XA environment, use of DDL calls may result in a server error. DDL calls can be used before XA connectivity is established.

---

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

Every valid RWDBDatabase implementation has a database type that applies to both XA and non-XA implementations. For example, the database type might be SYBASE. Applications request RWDBDatabases of a particular type by specifying the type to the RWDBManager; once a valid RWDBDatabase instance is obtained, its implementation type is transparent to the application. Objects produced by an RWDBDatabase instance automatically have the same implementation type as the producer. For example, a SYBASE type RWDBDatabase automatically produces SYBASE-type RWDBTables.

enum tableType(UserTable = 1, SystemTable = 2, View = 4, 
               Synonym = 8)

The values used in dbTables() to make up the type argument.

#define rwdbAllTypes (SystemTable|UserTable|View| Synonym)

The default value for the type argument to dbTables().

RWDBDatabase();

The default constructor creates a database with a status of RWDBStatus::notInitialized. This constructor is provided for convenience; usable RWDBDatabase objects must be obtained from the RWDBManager.

RWDBDatabase(const RWDBDatabase& dbase);

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

RWDBDatabase&
operator=(const RWDBDatabase& dbase);

Assignment operator. Self shares an implementation with dbase. Returns a reference to self.

bool 
operator==(const RWDBDatabase& dbase) const;

Returns true if self and dbase share the same implementation, otherwise false.

bool
operator!=(const RWDBDatabase& dbase) const;

Returns true if self and dbase do not share the same implementation, otherwise false.

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.

RWCString::caseCompare
caseCompare() const;

Returns current value of self's caseCompare member. If the caseCompare member is set to RWCString::exact, objects produced by self use case sensitive search when looking for objects by name; if it is set to RWCString::ignoreCase, they use case-insensitive search. The default for any particular implementation is set to mirror the behavior of the underlying database. RWDBTable uses the caseCompare setting when accessing columns by name

RWCString::caseCompare
caseCompare(RWCString::caseCompare cmp);

Sets self's caseCompare member to cmp, and returns its previous value.

static bool
connect() const

Accessor function that returns the connection policy set by the mutator static void connect(bool enable).

static void
connect(bool enable);

This method allows an application to specify whether the call to RWDBManager::database() should result in fetching the XA connection from the server. By default, the DB Interface Module fetches the XA connection from the server when an RWDBDatabase object is produced. An application calls RWDBDatabase::connect() with enable set to false to change this behavior. In this case, a connection to the server is established only when a statement is to be executed against the server or when a connection is explicitly created by the application.

A side effect of disabling the initial connection is that the RWDBDatabase will always be valid; however, if the first connection attempt fails, the status of the RWDBDatabase object will be changed to reflect the connection status.

This method is a static method and effects the creation of all databases within an application. For related topics, see RWDBEnvironmentHandle.

RWDBConnection
connection(RWDBConnection::ConnectionType type = 
           RWDBConnection::Synchronous) const;

Produces an RWDBConnection that provides a connection to self. On return, the connection is either open and ready for use, or connection.isValid() is false.

RWDBConnection
connection((const RWDBConnCallback& conncb,
            RWDBConnection::ConnectionType type = 
            RWDBConnection::Synchronous ) const;

Produces an RWDBConnection that provides a connection to self. On return, the connection is either open and ready for use, or connection.isValid() is false. The first argument provides an instance of the RWDBConnCallback to be associated with the produced RWDBConnection object. Connection produced will not be fetched from the connection pool nor will it be returned to the connection pool.

---

NOTE -- With the exception of Sybase CT, this method produces a notSupported error if used to create more than one connection.

---

RWDBStatus
createProcedure(const RWCString& name, 
                const RWCString& sql) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create a stored procedure with the given name in the database. The supplied sql is used as the body of the new procedure. The new procedure takes no parameters. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createProcedure(const RWCString& name, const RWCString& sql,
                const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create a stored procedure with the given name in the database. The supplied sql is used as the body of the new procedure. The new procedure takes no parameters. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createProcedure(const RWCString& name, const RWCString& sql,
                const RWDBSchema& params) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create a stored procedure with the given name in the database. The supplied sql is used as the body of the new procedure. The new procedure's parameters are specified by params. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createProcedure(const RWCString& name, const RWCString& sql,
                const RWDBSchema& params, 
                const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create a stored procedure with the given name in the database. The supplied sql is used as the body of the new procedure. The new procedure's parameters are specified by params. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createProcedure(const RWDBStoredProc& proc) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create a stored procedure in the database. Also opens a connection to proc's database. The new procedure's name, parameter definitions and body are copied from the supplied proc. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createProcedure(const RWDBStoredProc& proc,
                const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create a stored procedure in the database. Also opens a connection to proc's database. The new procedure's name, parameter definitions and SQL body are copied from the supplied proc. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createTable(const RWDBTable& table) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create a new table in the database. Creates the table with the same name and schema as the given table. The new table has no data in it. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createTable(const RWCString& name, 
            const RWDBSchema& schema) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create a new table in the database. Creates the table with the given name and schema. The new table has no data in it. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createTable(const RWDBTable& table,
            const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create a new table in the database. Creates the table with the same name and schema as the given table. The new table has no data in it. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createTable(const RWCString& name, const RWDBSchema& schema, 
            const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create a new table in the database. Creates the table with the given name and schema. The new table has no data in it. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createView(const RWCString& viewName,
           const RWDBSelectorBase& select) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create viewName in the database. The SQL SELECT statement encapsulated in select is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createView(const RWCString& viewName, 
           const RWDBSchema& columnList,
           const RWDBSelectorBase& select) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to create viewName in the database. The SQL SELECT statement encapsulated in select is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded. The resulting columns from the SELECT statement are named according to the columnList provided.

RWDBStatus
createView(const RWCString& viewName, 
           const RWDBSelectorBase& select, 
           const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create viewName in the database. The SQL SELECT statement encapsulated in select is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createView(const RWCString& viewName,
           const RWDBSchema& columnList,
           const RWDBSelectorBase& select, 
           const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create viewName in the database. The SQL SELECT statement encapsulated in select is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded. The resulting columns from the SELECT statement are named according to the columnList provided. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createView(const RWCString& viewName, 
           const RWCString& sql) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection is to create viewName in the database. The supplied sql is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus
createView(const RWCString& viewName, 
           const RWDBSchema& columnList,
           const RWCString& sql) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection is to create viewName in the database. The supplied sql is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded. The resulting columns from the SELECT statement are named according to the columnList provided.

RWDBStatus
createView(const RWCString& viewName, RWCString& sql, 
           const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create viewName in the database. The supplied sql is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus
createView(const RWCString& viewName, 
           const RWDBSchema& columnList,
           const RWCString& sql, 
           const RWDBConnection& connection) const;

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to create viewName in the database. The supplied sql is used as the body of the new view. Check the return value's isValid() method to determine whether the operation succeeded. The resulting columns from the SELECT statement are named according to the columnList provided. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor     
cursor(const RWCString& select, 
       const RWDBSchema& updateCols, 
       const RWDBConnection& connection,
       RWDBCursor::CursorType cursorType = 
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the given SQL SELECT statement. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the supplied connection. The argument updateCols is used in building a clause:

FOR UPDATE OF column-name, column-name, ...

Some SQL dialects require this form. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor     
cursor(const RWCString& select, 
       const RWDBSchema& updateCols,
       RWDBCursor::CursorType cursorType = 
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the given SQL SELECT statement. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the default connection. The argument updateCols is used in building a clause:

FOR UPDATE OF column-name, column-name, ...

Some SQL dialects require this form.

RWDBCursor
cursor(const RWDBSelector& selector,
       const RWDBSchema& updateCols,
       const RWDBConnection& connection,
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the supplied connection. The argument updateCols is used in building a clause:

FOR UPDATE OF column-name, column-name,...

Some SQL dialects require this form. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor     
cursor(const RWDBSelector& selector, 
       const RWDBSchema& updateCols, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on a default connection. The argument updateCols is used in building a clause:

FOR UPDATE OF column-name, column-name,...

Some SQL dialects require this form.

RWDBCursor
cursor(const RWDBCompoundSelector& selector, 
       const RWDBSchema& updateCols, 
       const RWDBConnection& connection,
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the supplied connection. The argument updateCols is used in building a clause:

FOR UPDATE OF column-name, column-name,...

Some SQL dialects require this form. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor
cursor(const RWDBCompoundSelector& selector, 
       const RWDBSchema& updateCols, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on a default connection. The argument updateCols is used in building a clause:

FOR UPDATE OF column-name, column-name, ...

Some SQL dialects require this form.

RWDBCursor
cursor(const RWCString& sql, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the given sql. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on a default connection. SourcePro Core does not check the contents of sql for validity.

RWDBCursor
cursor(const RWCString& sql, 
       const RWDBConnection& connection, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the given sql. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the connection provided. SourcePro Core does not check the contents of sql for validity. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor
cursor(const RWDBSelector& select, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on a default connection.

RWDBCursor
cursor(const RWDBSelector& select, 
       const RWDBConnection& connection, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the supplied connection. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor
cursor(const RWDBCompoundSelector& select,
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on a default connection.

RWDBCursor
cursor(const RWDBCompoundSelector& select, 
       const RWDBConnection& connection, 
       RWDBCursor::CursorType cursorType =
                              RWDBCursor::Sequential, 
       RWDBCursor::CursorAccess cursorAccess = 
                              RWDBCursor::Read) const;

Produces an RWDBCursor for execution of the SQL SELECT statement encapsulated in select. The cursorType may be either RWDBCursor::Sequential, or RWDBCursor::Scrolling. The cursorAccess may be either RWDBCursor::Read or RWDBCursor::Write. The cursor is created on the supplied connection. This function can behave asynchronously if executed using an asynchronous connection.

RWDBDateVector
dateVector(size_t n);

Produces an RWDBDateVector of size n with RWDBVendorDates appropriate for use with self's underlying implementation.

---

NOTE -- This method is deprecated. Use classes RWDateTime and RWDBTBuffer<RWDateTime> directly.

---

RWCString
dbName() const;

For RWDBDatabase objects produced by RWDBManager dbName() returns an empty string.

RWDBTable
dbStoredProcedures() const;

Returns, as an RWDBTable, a list of stored procedures available in the database encapsulated by self. The table contains two columns, name and owner, whose datatype is String. Each row in the returned table contains information about a single database object.

RWDBTable
dbStoredProcedures(const RWCString& name) const;

Returns, as an RWDBTable, a list of stored procedures available in the database encapsulated by self. The table contains two columns, name and owner, whose datatype is String. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with names that match, according to the SQL LIKE operator. A blank name places no restrictions on the search.

RWDBTable
dbStoredProcedures(const RWCString& name, 
                   const RWCString& owner) const;

Returns, as an RWDBTable, a list of stored procedures available in the database encapsulated by self. The table contains two columns, name and owner, whose datatype is String. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with names that match, according to the SQL LIKE operator. A blank name places no restrictions on the search. The owner argument restricts the search to tables with owners that match, according to the SQL LIKE operator. A blank owner places no restrictions on the search.

RWDBTable
dbStoredProcedures(const RWDBConnection& conn) const;

Returns, as an RWDBTable, a list of stored procedures available in the database encapsulated by self. The table contains two columns, name and owner, whose datatype is String. Each row in the returned table contains information about a single database object. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.

RWDBTable
dbStoredProcedures(const RWDBConnection& conn, 
                   const RWCString& name) const;

Returns, as an RWDBTable, a list of stored procedures available in the database encapsulated by self. The table contains two columns, name and owner, whose datatype is String. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with names that match, according to the SQL LIKE operator. A blank name places no restrictions on the search. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.

RWDBTable
dbStoredProcedures(const RWDBConnection& conn, 
                   const RWCString& name, 
                   const RWCString& owner) const;

Returns, as an RWDBTable, a list of stored procedures available in the database encapsulated by self. The table contains two columns, name and owner, whose datatype is String. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with names that match, according to the SQL LIKE operator. A blank name places no restrictions on the search. The owner argument restricts the search to tables with owners that match, according to the SQL LIKE operator. A blank owner places no restrictions on the search. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.

RWDBTable
dbTables(int type = rwdbAllTypes) const;

Returns, as an RWDBTable, a list of tables stored in the database encapsulated by self. The table contains 3 columns, name, owner, and type, whose datatypes are String, String, and Int, respectively. Each row in the returned table contains information about a single database object. The type argument is made up of the bitwise-ORed combination of the enumerated values UserTable, SystemTable, View, and, Synonym. The search is restricted to tables of those types which make up type. No restriction is placed on the type of table that this method searches for, if the default argument rwdbAllTypes is used.

RWDBTable
dbTables(const RWCString& name,int type=rwdbAllTypes) const;

Returns, as an RWDBTable, a list of tables stored in the database encapsulated by self. The table contains 3 columns, name, owner, and type, whose datatypes are String, String, and Int, respectively. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with matching names (according to the SQL LIKE operator). A blank name places no restrictions on the search. The type argument is made up of the bitwise-ORed combination of the enumerated values UserTable, SystemTable, View, and, Synonym. The search is restricted to tables of those types which make up type. No restriction is placed on the type of table that this method searches for, if the default argument rwdbAllTypes is used.

RWDBTable
dbTables(const RWCString& name, const RWCString& owner, 
         int type = rwdbAllTypes) const;

Returns, as an RWDBTable, a list of tables stored in the database encapsulated by self. The table contains 3 columns, name, owner, and type, whose datatypes are String, String, and Int, respectively. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with matching names (according to the SQL LIKE operator). A blank name places no restrictions on the search. The owner argument restricts the search to tables with matching owners (according to the SQL LIKE operator). A blank owner places no restrictions on the search. The type argument is made up of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and, Synonym. The search is restricted to tables of those types which make up type. No restriction is placed on the type of table that this method searches for if the default argument rwdbAllTypes is used.

RWDBTable
dbTables(const RWDBConnection& conn, 
         int type = rwdbAllTypes) const;

Returns, as an RWDBTable, a list of tables stored in the database encapsulated by self. The table contains 3 columns, name, owner, and type, whose datatypes are String, String, and Int, respectively. Each row in the returned table contains information about a single database object. The type argument is made up of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and, Synonym. The search is restricted to tables of those types which make up type. No restriction is placed on the type of table that this method searches for if the default argument rwdbAllTypes is used. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.

RWDBTable
dbTables(const RWDBConnection& conn, const RWCString& name,
         int type = rwdbAllTypes) const;

Returns, as an RWDBTable, a list of tables stored in the database encapsulated by self. The table contains 3 columns, name, owner, and type, whose datatypes are String, String, and Int, respectively. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with matching names (according to the SQL LIKE operator). A blank name places no restrictions on the search. The type argument is made up of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and, Synonym. The search is restricted to tables of those types which make up type. No restriction is placed on the type of table that this method searches for if the default argument rwdbAllTypes is used. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.

RWDBTable
dbTables(const RWDBConnection& conn, const RWCString& name, 
         const RWCString& owner,int type=rwdbAllTypes)const;

Returns, as an RWDBTable, a list of tables stored in the database encapsulated by self. The table contains 3 columns, name, owner, and type, whose datatypes are String, String, and Int, respectively. Each row in the returned table contains information about a single database object. The name argument restricts the search to tables with matching names (according to the SQL LIKE operator). A blank name places no restrictions on the search. The owner argument restricts the search to tables with matching owners (according to the SQL LIKE operator). A blank owner places no restrictions on the search. The type argument is made up of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and, Synonym. The search is restricted to tables of those types which make up type. No restriction is placed on the type of table that this method searches for if the default argument rwdbAllTypes is used. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.

size_t
defaultConnections() const;

Returns the number of default connections retained in self's connection pool. In the XA environment, the number of default connections is set to 1. Each database maintains a pool of connections from which all requests for explicit and implicit connection are satisfied.

size_t
defaultConnections(size_t reqdConnections);

---

NOTE -- The DB Interface Module limits the number of valid connections to one. Therefore, setting the number of default connections to more than one serves no purpose.

---

Sets the number of default connections retained in self's connection pool. Each database maintains a pool of connections from which all requests for explicit and implicit connection are satisfied. This method allows applications to change the number of connections to retain as they are returned to the connection pool, that is, default connections. Increasing or decreasing the number of default connections does not immediately enlarge or shrink the connection pool, but effects only the number of default connections. The total size of the connection pool changes as connections are created and destroyed, and the requested number of default connections is retained.

This method returns the previous number of default connections retained. Initially, the number of default connections is set to 1. Optimizing the number of default connections can significantly boost performance when using implicit connections. Also see totalConnections().

RWDBDeleter
deleter(const RWDBTable& table) const;

Produces an RWDBDeleter which encapsulates the SQL statement:

DELETE FROM table

The deleter can be used to delete all the data from the database table represented by table, or can be augmented with an RWDBCriterion (representing an SQL WHERE clause) in order to delete data selectively.

RWDBDeleter
deleter(const RWDBTable& table, 
        const RWDBCriterion& criterion) const;

Produces an RWDBDeleter which encapsulates the SQL statement:

DELETE FROM table WHERE criterion

The deleter can be used to delete rows from the database table represented by table, which meet the given criterion (representing an SQL WHERE clause). Note that a subsequent call to deleter.where() replaces, rather than adds to, the criterion.

RWDBStatus
dropView(const RWCString& viewName);

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses a default connection to drop viewName from the database. Check the return value's isValid() method to determine whether or not the operation succeeded.

RWDBStatus
dropView(const RWCString& viewName,
         const RWDBConnection& connection);

When used in an XA-environment, this call may generate a server error. This method can still be used before XA connectivity is established.

Uses the supplied connection to drop viewName from the database. Check the return value's isValid() method to determine whether or not the operation succeeded. This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus::ErrorHandler
errorHandler() const;

Returns the currently-installed error handler, if any.

bool
emptyStringIsNull() const;

Retrieves the setting of this flag for this instance of RWDBDatabase. See RWDBManager::emptyStringIsNull(bool) for details.

RWDBEnvironmentHandle*
environmentHandle() const;

Returns the handle to the environment. Through the environment handle, the user can set environment-specific values. Should be used before a connection is established. See RWDBEnvironmentHandle for more information.

RWDBInserter
inserter(const RWDBTable& table) const;

Produces an RWDBInserter, which encapsulates the SQL statement:

INSERT INTO table VALUES ...

where the actual values must be added to the inserter later.

RWDBInserter
inserter(const RWDBTable& table, 
         const RWDBSchema& columnList) const;

Produces an RWDBInserter, which encapsulates the SQL statement:

INSERT INTO <table> ( col1, ..., coln)

VALUES(val1, ..., valn)

where <table> is represented by table. The names of the column entries in columnList are used to build up the column-name list.

RWDBInserter
inserter(const RWDBTable& table,
         const RWDBSelector& selector)const;

Produces an RWDBInserter which encapsulates the SQL statement:

INSERT INTO table select-statement

where the select-statement is encapsulated by the given selector.

RWDBInserter
inserter(const RWDBTable& table, const RWDBSelector& selector, 
         const RWDBSchema& columnList)const;

Produces an RWDBInserter which encapsulates the SQL statement:

INSERT INTO <table> ( col1, ..., coln) select-statement

where <table> is represented by table. The names of the column entries in columnList are used to build up the column-name list. The select-statement is encapsulated by the given selector.

RWDBInserter
inserter(const RWDBTable& table, 
         const RWDBCompoundSelector& selector) const;

Produces an RWDBInserter which encapsulates the SQL statement:

INSERT INTO table select-statement

where the select-statement is encapsulated by the given selector.

RWDBInserter
inserter(const RWDBTable& table, 
         const RWDBCompoundSelector & select, 
         const RWDBSchema& columnList)const;

Produces an RWDBInserter which encapsulates the SQL statement:

INSERT INTO <table> (col1, ..., coln) select-statement

where <table> is represented by table. The names of the column entries in columnList are used to build up the column-name list. The select-statement is encapsulated by the given selector.

bool
isReady() const;

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;

Returns true if self's status is RWDBStatus::ok, otherwise returns false.

RWDBMemTable
memTable(const RWCString& name, size_t capacity = 0) const;

Produces an RWDBMemTable with the given name. A default connection is used to query the database for a table matching name. If one is found, the RWDBMemTable is populated with rows of data from the database. If capacity is zero, all rows are fetched into the memTable. Otherwise a maximum of capacity rows are fetched.

RWDBMemTable
memTable(const RWCString& name,
         const RWDBConnection& connection, size_t capacity=0);

Produces an RWDBMemTable with the given name. The given connection is used to query the database for a table matching name. If one is found, the RWDBMemTable is populated with rows of data from the database. If capacity is zero, all rows are fetched into the memTable. Otherwise a maximum of capacity rows are fetched.

RWCString
passWord() const;

For RWDBDatabase objects produced by RWDBManager passWord() returns an empty string.

const RWDBPhraseBook&
phraseBook() const;

Returns a reference to self's RWDBPhraseBook.

void
release() const;

This function releases a previously acquired mutex. This function can be called from a const object. Note: In non-multithreaded builds, this function evaluates to a no-op.

RWDBSelector
selector() const;

Produces an empty RWDBSelector appropriate for this database. The result can be used to build an encapsulated SQL SELECT statement. See RWDBSelector for details.

RWDBSelector
selector(const RWDBCriterion& criterion) const;

Produces an RWDBSelector whose criterion, or WHERE clause, is initialized with the given criterion. The result can be used to build an encapsulated SQL SELECT statement. See RWDBSelector for details. Note that a subsequent call to selector.where() replaces, rather than adds to, criterion.

RWCString
serverName() const;

For RWDBDatabase objects produced by RWDBManager serverName() returns an empty string.

RWCString
serverType() const;

Returns a mnemonic based on the Access Module you are using. This is the same as the string you use for the RWDBManager::database() accessLib parameter for static libraries, as described in your DB Access Module guide. Specifically, it is not the same as the accessLib parameter for dynamic libraries.

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 RWDBDatabase's error handler is inherited from the RWDBManager; this method overrides the default. ErrorHandler is declared as a typedef within the scope of RWDBStatus:

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

RWDBStatus
status() const;

Returns the current status of self.

RWDBStoredProc
storedProc(const RWCString& name) const;

Produces an RWDBStoredProc. The result represents the stored procedure with the given name in the database. Uses a default connection to retrieve information about the stored procedure's parameters.

RWDBStoredProc
storedProc(const RWCString& name, 
           const RWDBConnection& connection) const;

Produces an RWDBStoredProc. The result represents the stored procedure with the given name in the database. Uses the supplied connection to retrieve information about the stored procedure's parameters.

RWDBStoredProc
storedProc(const RWCString& name, 
           const RWDBSchema& schema,
           constRWDBColumn& col = RWDBColumn()) const;

Produces an RWDBStoredProc. The result represents the stored procedure with the given name in the database. Uses the supplied RWDBSchema to determine the parameters in the stored procedure and the supplied column to determine the return value, if any. This means that the call does not have to query the database about the parameters needed or the return value.

RWDBStoredProc
storedProc(const RWCString& name, 
           const RWDBConnection& connection
           const RWDBSchema& schema,
           constRWDBColumn& col = RWDBColumn()) const;

Produces an RWDBStoredProc. The result represents the stored procedure with the given name in the database. Uses the supplied RWDBSchema to determine the parameters in the stored procedure and the supplied column to determine the return value, if any. This means that the call does not have to query the database about the parameters needed or the return value.

RWDBTable
table(const RWCString& name) const;

Produces an RWDBTable with the given name. The returned object is an instance of the most general kind of RWDBTable, which applications are likely to need most often. See RWDBTable for an explanation of the different kinds of RWDBTable.

Each RWDBTable produced has a unique alias. This may or may not be desirable based on the usage of the table when creating a selector, i.e., self-joins. Exact copies of tables (and associated tags) should be produced by RWDBTable::operator= or copy constructor.

size_t
totalConnections() const;

Returns the total number of connections an application is using or has retained in the connection pool. See defaultConnections().

---

NOTE -- When the DB Interface Module is used with the Sybase CT Access Module the connection pool is disabled and, if used, returns 0.

---

RWDBTracer&
tracer();

Returns a reference to self's RWDBTracer. The result can be used to control trace output from this RWDBDatabase. See RWDBTracer for an explanation of tracing capabilities.

RWDBUpdater
updater(const RWDBTable& table) const;

Produces an RWDBUpdater. The result can be used to create an encapsulated SQL UPDATE statement to update rows in the database table represented by table.

RWDBUpdater
updater(const RWDBTable& table, 
        const RWDBCriterion & criterion) const;

Produces an RWDBUpdater whose criterion (WHERE clause) is initialized with the given criterion. The result can be used to create an encapsulated SQL UPDATE statement to update rows in the database table represented by table. Note that a subsequent call to updater.where() replaces criterion, rather than adding to it.

RWCString
userName() const;

For RWDBDatabase objects produced by RWDBManager userName() returns an empty string.

bool
verboseAsString() const;
bool
verboseAsString(bool verbose) const;

The accessor and the mutator, respectively, of self's verboseAsString member. The default value is false.

The value of this member affects the SQL returned by the asString() methods of the RWDBInserter, RWDBUpdater, RWDBDeleter, RWDBSelector, and RWDBCompoundSelector instances produced by this RWDBDatabase.

• If the verboseAsString member is set to false, the asString() methods of the above classes return the SQL as sent to the database for execution, meaning that it may include placeholders.

• If the verboseAsString member is set to true, the asString() methods of the above classes will return the SQL with the placeholders replaced by their bound values.

The mutator method sets self's verboseAsString member to verbose and returns its previous value.

---

NOTE -- Setting the verboseAsString member to true enables the asString()methods to return SQL in which placeholders are replaced by their bound values, but it does not affect the SQL passed to the database for execution.

---

RWCString
version() const;

Returns a string that identifies the version of the SourcePro Core Access Module that produced self. Note that this method identifies the version of a SourcePro Core Access Module, while RWDBManager::version() identifies the version of the DB Interface Module. If self is not valid, returns an empty string.

.

© 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.