RWDBDatabase

Module:  DB Interface Module   Group:  Database Classes

Does not inherit

• Local Index
• Synopsis
• Description
• Public Enums 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 AdjustCaseType 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", "Servername",
                        "Username", "PassWord",
                        "DatabaseName");

RWDBDatabase manages connections with database servers. A database object represents a server, a user on that server, and a database opened for that user. Database objects are produced by the RWDBManager. Class RWDBDatabase provides an interface for obtaining database-specific objects and data definition language (DDL) concepts.

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. For example, the database type might be Sybase or Oracle. 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.

enum AdjustCaseType { Exact = 0, Normalize = 1 };

These enumeration values are used in dbTables() and dbStoredProcedures() calls to indicate whether or not the case of the search parameters should be normalized for the database.

#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 returns false.

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

Returns true if self and dbase 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.

RWCString::caseCompare
caseCompare() const;

Returns the 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 a database that establishes a physical connection to the server. By default, the DB Interface Module establishes a default connection to the server when an RWDBDatabase object is produced. To change this behavior, an application calls RWDBDatabase::connect() with enable set to false. 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 is always valid; however, if the first connection attempt fails, the status of the RWDBDatabase object is changed to reflect the connection status.

This method is a static method and affects 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.

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

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. You can 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;

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. You can 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;

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. You can 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;

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. You can 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;

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. You can check the return value's isValid() method to determine whether the operation succeeded.

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

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. You can 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;

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. You can check the return value's isValid() method to determine whether the operation succeeded.

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

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. You can check the return value's isValid() method to determine whether the operation succeeded.

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

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. You can 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;

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. You can 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;

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. You can 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;

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. You can 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;

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. You can 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;

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. You can 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;

Uses a default connection to create viewName in the database. The supplied sql is used as the body of the new view. You can 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;

Uses a default connection to create viewName in the database. The supplied sql is used as the body of the new view. You can 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;

Uses the supplied connection to create viewName in the database. The supplied sql is used as the body of the new view. You can 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;

Uses the supplied connection to create viewName in the database. The supplied sql is used as the body of the new view. You can 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 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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. The DB Interface Module 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. The DB Interface Module 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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 can be either RWDBCursor::Sequential or RWDBCursor::Scrolling. The cursorAccess can 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;

Returns the name of the database used when constructing self. See RWDBManager for more information.

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 data type is String. Each row in the returned table contains information about a single database object.

RWDBTable
dbStoredProcedures(const RWCString& name,
     AdjustCaseType adjustCase = Normalize) 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 data type 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. When adjustCase is Normalize, name is normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name is used as is in the search.

RWDBTable
dbStoredProcedures(const RWCString& name, 
     const RWCString& owner,
     AdjustCaseType adjustCase = Normalize) 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 data type 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. When adjustCase is Normalize, name and owner are normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name and owner are used as is in 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 data type 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,
     AdjustCaseType adjustCase = Normalize) 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 data type 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. When adjustCase is Normalize, name is normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name is used as is in the search.

RWDBTable
dbStoredProcedures(const RWDBConnection& conn, 
     const RWCString& name, 
     const RWCString& owner,
     AdjustCaseType adjustCase = Normalize) 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 data type 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. When adjustCase is Normalize, name and owner are normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name and owner are used as is in the search.

RWDBTable
dbTables(int type = rwdbAllTypes) const;

Like an RWDBTable, returns a list of tables stored in the database encapsulated by self. The table contains three columns, name, owner, and type, whose data types 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 that 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,
     AdjustCaseType adjustCase = Normalize) const;

Like an RWDBTable, returns a list of tables stored in the database encapsulated by self. The table contains three columns, name, owner, and type, whose data types 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 that make up type. No restriction is placed on the type of table that this method searches for, if the default argument rwdbAllTypes is used. When adjustCase is Normalize, name is normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name is used as is in the search.

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

Like an RWDBTable, returns a list of tables stored in the database encapsulated by self. The table contains three columns, name, owner, and type, whose data types 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 that make up type. No restriction is placed on the type of table searched for, if the default argument rwdbAllTypes is used. When adjustCase is Normalize, name and owner are normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name and owner are used as is in the search.

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

Like an RWDBTable, returns a list of tables stored in the database encapsulated by self. The table contains three columns, name, owner, and type, whose data types 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 that 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,
     AdjustCaseType adjustCase = Normalize) const;

Like an RWDBTable, returns a list of tables stored in the database encapsulated by self. The table contains three columns, name, owner, and type, whose data types 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 that make up type. No restriction is placed on the type of table searched 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. When adjustCase is Normalize, name is normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name is used as is in the search.

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

Like an RWDBTable, returns a list of tables stored in the database encapsulated by self. The table contains three columns, name, owner, and type, whose data types 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 that 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. When adjustCase is Normalize, name and owner are normalized to the default case used by the database server before using it for the search. When adjustCase is Exact, name and owner are used as is in the search.

size_t
defaultConnections() const;

Returns the number of default connections retained in self's connection pool. Initially, 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. Optimizing the number of default connections can significantly boost performance when using implicit connections. Also see totalConnections().

size_t
defaultConnections(size_t reqdConnections);

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 affects 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 that encapsulates the SQL statement:

DELETE FROM table WHERE criterion

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

RWDBStatus
dropView(const RWCString& viewName);

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

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

Uses the supplied connection to drop viewName from the database. You can 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, size_t cache=1) const;

Produces an RWDBInserter that encapsulates the SQL statement:

INSERT INTO table VALUES ...

where the actual values must be added to the inserter later. When cache is passed in as 0, it is interpreted as 1.

---

NOTE -- When using Access Modules that support an inserter cache, increasing the cache value can greatly improve performance. However, setting the cache parameter greater than one may adversely affect transactions. Check your Access Module documentation for limitations and warnings.

---

RWDBInserter
inserter(const RWDBTable& table, 
         const RWDBSchema& schema,
         size_t cache=1) const;

Produces an RWDBInserter that 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 schema are used to build up the column-name list. When cache is passed in as 0, it is interpreted as 1.

---

NOTE -- When using Access Modules that support an inserter cache, increasing the cache value can greatly improve performance. However, setting the cache parameter greater than one may adversely affect transactions. Check your Access Module documentation for limitations and warnings.

---

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

Produces an RWDBInserter that 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 nonready 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;

Returns the password of the user that was used when constructing self. See RWDBManager for more information.

RWCString
passWord(const RWCString& pwd);

Updates self's password to pwd. Database connections obtained after this call will use the new password. Returns the old password.

const RWDBPhraseBook&
phraseBook() const;

Returns a reference to self's RWDBPhraseBook.

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.

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 criterion, rather than adds to it.

RWCString
serverName() const;

Returns the name of the server that was used when constructing self. See RWDBManager for more information.

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, the error handler of an RWDBDatabase 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,
           const RWDBColumn& 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,
           const RWDBColumn& 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 RWDBTables.

Each RWDBTable that is produced has a unique alias. When producing a table that will be used for self-joins, this may or may not be desirable. Exact copies of tables and associated tags should be produced by RWDBTable::operator= or copy constructor.

RWDBTable
table(const RWDBSelectorBase& selector) const;

Produces a RWDBTable representing the SQL query encapsulated by selector. The returned object is an instance of a derived table. See RWDBTable for an explanation of the different kinds of RWDBTables. The returned RWDBTable will have a unique alias.

size_t
totalConnections() const;

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

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;

Returns the name of the user that was used when constructing self. See RWDBManager for more information.

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.

---

version() const;

Returns a string that identifies the version number of the DB Interface Module being used.

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