 SourcePro® 2023.1 |
SourcePro® API Reference Guide |
Manages connections with database servers. More...
#include <rw/db/dbase.h>
Public Types | |
| enum | { UserTable, SystemTable, View, Synonym } |
| enum | AdjustCaseType { Exact, Normalize } |
Static Public Member Functions | |
| static void | connect (bool enable) |
| static bool | connect () |
Related Functions | |
(Note that these are not member functions.) | |
| #define | rwdbAllTypes |
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 RWDBDatabase objects 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 RWDBTable objects.
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 DB XA Module User's Guide.
In the XA environment, you would create an RWDBDatabase instance like this:
| anonymous enum |
These enumeration values are used in dbTables() to make up the type argument.
| Enumerator | |
|---|---|
| UserTable |
User table |
| SystemTable |
System table |
| View |
Views |
| Synonym |
Synonyms |
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.
| Enumerator | |
|---|---|
| Exact |
Exact value; search parameters are not normalized. |
| Normalize |
Normalized value; search parameters are converted to the default case of the database. |
| RWDBDatabase::RWDBDatabase | ( | ) |
Default constructor that 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::RWDBDatabase | ( | const RWDBDatabase & | dbase | ) |
Copy constructor. The object created shares an implementation with dbase.
| void RWDBDatabase::acquire | ( | void | ) | const |
Attempts to acquire the internal mutex lock. If the mutex is already locked by another thread, the function blocks until the mutex is released. This function can be called from a const object.
| RWDBCacheManager* RWDBDatabase::cacheManager | ( | ) | const |
Returns a pointer to the currently installed cache manager. If a cache manager is not installed, returns NULL.
| RWDBCacheManager* RWDBDatabase::cacheManager | ( | RWDBCacheManager * | mgr | ) |
Sets the cache manager to mgr. Returns a pointer to the previous cache manager. Pass NULL to unset the cache manager.
| RWCString::caseCompare RWDBDatabase::caseCompare | ( | ) | const |
Returns the current value of self's case comparison setting. If it 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, objects use case-insensitive search. The default for any particular implementation is set to mirror the behavior of the underlying database. RWDBTable uses the case comparison setting when accessing columns by name.
| RWCString::caseCompare RWDBDatabase::caseCompare | ( | RWCString::caseCompare | cmp | ) |
Sets self's case comparison setting to cmp, and returns its previous value.
|
static |
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. If the subsequent first connection attempt fails, the status of the RWDBDatabase object will remain unchanged and the RWDBConnection should be inspected to determine the connection status.
This method is a static method and affects the creation of all databases within an application. For related topics, see RWDBEnvironmentHandle.
DB XA Module: The default behavior is to obtain the XA connection from the server. Alternatively, the connection is obtained only when a statement is to be executed, or when a connection is explicitly created by the application.
|
static |
Accessor function that returns the connection policy set by the mutator.
| RWDBConnection RWDBDatabase::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 RWDBConnection::isValid() of the produced RWDBConnection object returns false.
DB XA Module: With the exception of Sybase, this method produces a RWDBStatus::notSupported error if used to create more than one connection.
| RWDBConnection RWDBDatabase::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 RWDBConnection::isValid() of the produced RWDBConnection object returns false. The argument conncb provides an instance of the RWDBConnCallback to be associated with the produced RWDBConnection object. The connection produced is not fetched from the connection pool nor is it returned to the connection pool.
DB XA Module: With the exception of Sybase, this method produces a RWDBStatus::notSupported error if used to create more than one connection.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::createProcedure | ( | const RWDBStoredProc & | proc | ) | const |
Uses a default connection to create a stored procedure in the database. Also opens a connection to the database of proc. 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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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 the database of proc. 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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::createView | ( | const RWCString & | viewName, |
| 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. This function can behave asynchronously if executed using an asynchronous connection.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBCursor RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::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.
| RWDBCursor RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::cursor | ( | const RWDBSelector & | 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 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 RWDBDatabase::cursor | ( | const RWDBSelector & | select, |
| 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 RWDBDatabase::cursor | ( | const RWDBCompoundSelector & | 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 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 RWDBDatabase::cursor | ( | const RWDBCompoundSelector & | select, |
| 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.
| RWDBDateVector RWDBDatabase::dateVector | ( | size_t | n | ) | const |
Produces an RWDBDateVector of size n with RWDBVendorDate objects appropriate for use with self's underlying implementation.
| RWCString RWDBDatabase::dbName | ( | ) | const |
Returns the name of the database used when constructing self. See RWDBManager for more information.
DB XA Module: Returns an empty string.
| RWDBTable RWDBDatabase::dbStoredProcedures | ( | ) | const |
| RWDBTable RWDBDatabase::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.
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| adjustCase | Specifies whether the search value name should be normalized. |
| RWDBTable RWDBDatabase::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.
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| owner | Restricts the search to tables with matching owners, according to the SQL LIKE operator. A blank owner places no restrictions on the search. |
| adjustCase | Specifies whether the search values name and owner should be normalized. |
| RWDBTable RWDBDatabase::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.
| conn | Database connection to be used for this query. |
| RWDBTable RWDBDatabase::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 query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.
| conn | Database connection to be used for this query. |
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| adjustCase | Specifies whether the search value name should be normalized. |
| RWDBTable RWDBDatabase::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 query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.
| conn | Database connection to be used for this query. |
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| owner | Restricts the search to tables with matching owners, according to the SQL LIKE operator. A blank owner places no restrictions on the search. |
| adjustCase | Specifies whether the search values name and owner should be normalized. |
| RWDBTable RWDBDatabase::dbTables | ( | int | type = SystemTable|UserTable|View|Synonym | ) | 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 search is restricted to tables of those types that make up type. If the default argument is used, this method returns all tables encapsulated by self.
| type | Consists of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and Synonym. |
| RWDBTable RWDBDatabase::dbTables | ( | const RWCString & | name, |
| int | type = SystemTable|UserTable|View|Synonym, |
||
| 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 search is restricted to tables of those types that make up type. If the default argument
is used, this method returns all tables encapsulated by self.
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| type | Consists of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and Synonym. |
| adjustCase | Specifies whether the search value name should be normalized. |
| RWDBTable RWDBDatabase::dbTables | ( | const RWCString & | name, |
| const RWCString & | owner, | ||
| int | type = SystemTable|UserTable|View|Synonym, |
||
| 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 search is restricted to tables of those types that make up type. If the default argument is used, this method returns all tables encapsulated by self.
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| owner | Restricts the search to tables with matching owners, according to the SQL LIKE operator. A blank owner places no restrictions on the search. |
| type | Consists of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and Synonym. |
| adjustCase | Specifies whether the search values name and owner should be normalized. |
| RWDBTable RWDBDatabase::dbTables | ( | const RWDBConnection & | conn, |
| int | type = SystemTable|UserTable|View|Synonym |
||
| ) | 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 search is restricted to tables of those types that make up type. If the default argument is used, this method returns all tables encapsulated by self. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.
| conn | Database connection to be used for this query. |
| type | Consists of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and Synonym. |
| RWDBTable RWDBDatabase::dbTables | ( | const RWDBConnection & | conn, |
| const RWCString & | name, | ||
| int | type = SystemTable|UserTable|View|Synonym, |
||
| 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 search is restricted to tables of those types that make up type. If the default argument is used, this method returns all tables encapsulated by self. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.
| conn | Database connection to be used for this query. |
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| type | Consists of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and Synonym. |
| adjustCase | Specifies whether the search value name should be normalized. |
| RWDBTable RWDBDatabase::dbTables | ( | const RWDBConnection & | conn, |
| const RWCString & | name, | ||
| const RWCString & | owner, | ||
| int | type = SystemTable|UserTable|View|Synonym, |
||
| 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 search is restricted to tables of those types that make up type. If the default argument is used, this method returns all tables encapsulated by self. The query is issued through the supplied conn. This function can behave asynchronously if executed using an asynchronous connection.
| conn | Database connection to be used for this query. |
| name | Restricts the search to tables with matching names, according to the SQL LIKE operator. A blank name places no restrictions on the search. |
| owner | Restricts the search to tables with matching owners, according to the SQL LIKE operator. A blank owner places no restrictions on the search. |
| type | Consists of the bitwise ORed combination of the enumerated values UserTable, SystemTable, View, and Synonym. |
| adjustCase | Specifies whether the search values name and owner should be normalized. |
| size_t RWDBDatabase::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 connections are satisfied. Optimizing the number of default connections can significantly boost performance when using implicit connections.
DB XA Module: The number of default connections is always 1, except with the DB Access Module for Sybase, where the connection pool is disabled and this method always returns 0.
| size_t RWDBDatabase::defaultConnections | ( | size_t | size | ) |
Sets the number of default connections retained in self's connection pool to size. Each database maintains a pool of connections from which all requests for explicit and implicit connections are satisfied. This method allows applications to change the number of default connections to retain as they are returned to the connection pool.
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 are 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().
DB XA Module: The number of default connections is restricted to 1, so using this method to set a higher number does nothing. The exception is the DB Access Module for Sybase, where the connection pool is disabled so use of this method results in an RWDBStatus::notSupported error.
| RWDBDeleter RWDBDatabase::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 RWDBDatabase::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 RWDBDeleter::where() on the produced RWDBDeleter object replaces the criterion, rather than adding to it.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| RWDBStatus RWDBDatabase::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.
DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.
| bool RWDBDatabase::emptyStringIsNull | ( | ) | const |
Retrieves the setting of this flag for this instance of RWDBDatabase. See RWDBManager::emptyStringIsNull(bool) for details.
| RWDBEnvironmentHandle* RWDBDatabase::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.
| RWDBStatus::ErrorHandler RWDBDatabase::errorHandler | ( | ) | const |
Returns the currently-installed error handler, if any.
| RWDBInserter RWDBDatabase::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.
| RWDBInserter RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::inserter | ( | const RWDBTable & | table, |
| const RWDBSchema & | columnList, | ||
| size_t | cache = 1 |
||
| ) | const |
Produces an RWDBInserter that encapsulates the SQL statement:
INSERT INTO table(col1, ..., coln) VALUES(val1, ..., valn)
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.
| RWDBInserter RWDBDatabase::inserter | ( | const RWDBTable & | table, |
| const RWDBSelector & | selector, | ||
| const RWDBSchema & | columnList | ||
| ) | const |
Produces an RWDBInserter that encapsulates the SQL statement:
INSERT INTO table(col1, ..., coln) select-statement
The names of the column entries in schema are used to build up the column-name list. The select-statement is encapsulated by the given selector.
| RWDBInserter RWDBDatabase::inserter | ( | const RWDBTable & | table, |
| const RWDBCompoundSelector & | selector, | ||
| const RWDBSchema & | columnList | ||
| ) | const |
Produces an RWDBInserter that encapsulates the SQL statement:
INSERT INTO table(col1, ..., coln) select-statement
The names of the column entries in schema are used to build up the column-name list. The select-statement is encapsulated by the given selector.
| bool RWDBDatabase::isReady | ( | ) | const |
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 RWDBDatabase::isValid | ( | ) | const |
Returns true if self's status is RWDBStatus::ok, otherwise false.
| RWDBMemTable RWDBDatabase::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 RWDBMemTable, otherwise a maximum of capacity rows is fetched.
| RWDBMemTable RWDBDatabase::memTable | ( | const RWCString & | name, |
| const RWDBConnection & | connection, | ||
| size_t | capacity = 0 |
||
| ) | const |
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 RWDBMemTable. Otherwise a maximum of capacity rows is fetched.
| bool RWDBDatabase::operator!= | ( | const RWDBDatabase & | dbase | ) | const |
Returns true if self and dbase do not share the same implementation, otherwise false.
| RWDBDatabase& RWDBDatabase::operator= | ( | const RWDBDatabase & | dbase | ) |
Assignment operator. Self shares an implementation with dbase. Returns a reference to self.
| bool RWDBDatabase::operator== | ( | const RWDBDatabase & | dbase | ) | const |
Returns true if self and dbase share the same implementation, otherwise false.
| RWCString RWDBDatabase::passWord | ( | ) | const |
Returns the password of the user passed in when constructing self. See RWDBManager for more information.
DB XA Module: Returns an empty string.
Updates self's password to pwd. Database connections obtained after this call will use the new password. Returns the old password.
| const RWDBPhraseBook& RWDBDatabase::phraseBook | ( | ) | const |
Returns a reference to self's RWDBPhraseBook.
| void RWDBDatabase::release | ( | void | ) | const |
Releases a previously acquired mutex. This function can be called from a const object.
| RWDBSelector RWDBDatabase::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 RWDBDatabase::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 RWDBSelector::where() on the produced RWDBSelector object replaces criterion, rather than adds to it.
| RWCString RWDBDatabase::serverName | ( | ) | const |
Returns the name of the server used when constructing self. See RWDBManager for more information.
DB XA Module: Returns an empty string.
| RWCString RWDBDatabase::serverType | ( | ) | const |
Returns a mnemonic based on the Access Module you are using. This is the same as the string you use for the accessLib parameter of RWDBManager::database() 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 RWDBDatabase::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 self is inherited from the RWDBManager; this method overrides the default.
| RWDBStatus RWDBDatabase::status | ( | ) | const |
Returns the current status of self.
| RWDBStoredProc RWDBDatabase::storedProc | ( | const RWCString & | name | ) | const |
Produces an RWDBStoredProc. The result represents the stored procedure with the given name in the database. If a cache manager is present, this method checks the cache for a schema. If it isn't found or a cache manager isn't present, uses a default connection to retrieve information about the stored procedure's parameters. If a cache manager is present, the stored procedure metadata fetched from the database is stored in the cache.
| RWDBStoredProc RWDBDatabase::storedProc | ( | const RWCString & | name, |
| const RWDBConnection & | connection | ||
| ) | const |
Produces an RWDBStoredProc. The result represents the stored procedure with the given name in the database. If a cache manager is present, this method checks the cache for a schema. If it isn't found or a cache manager isn't present, uses the supplied connection to retrieve information about the stored procedure's parameters. If a cache manager is present, the stored procedure metadata fetched from the database is stored in the cache.
| RWDBStoredProc RWDBDatabase::storedProc | ( | const RWCString & | name, |
| const RWDBConnection & | connection, | ||
| const RWDBSchema & | sch, | ||
| const RWDBColumn & | col = RWDBColumn(), |
||
| const RWCString & | text = RWCString() |
||
| ) | 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, the supplied column to determine the return value, if any, and the supplied RWCString to determine the text. If text is an empty string, the next call to RWDBStoredProc::text() will attempt to fetch the text. This means that the call does not have to query the database for the parameters needed or the return value, so the connection is not used. If a cache manager is present, the schema and column are stored in the cache, replacing any existing metadata present in the cache. If the text is not empty, it too is stored in the cache.
| RWDBStoredProc RWDBDatabase::storedProc | ( | const RWCString & | name, |
| const RWDBSchema & | sch, | ||
| const RWDBColumn & | col = RWDBColumn(), |
||
| const RWCString & | text = RWCString() |
||
| ) | 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, the supplied column to determine the return value, if any, and the supplied RWCString to determine the text. If text is an empty string, the next call to RWDBStoredProc::text() will attempt to fetch the text. This means that the call does not have to query the database for the parameters needed or the return value. If a cache manager is present, the schema and column are stored in the cache, replacing any existing metadata present in the cache. If the text is not empty, it too is stored in the cache.
Produces an RWDBTable with the given name. The returned object is an instance of a database table, which applications are likely to need most often. See RWDBTable for an explanation of the different kinds of RWDBTable objects.
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 a table and associated tags should be produced by RWDBTable::operator=() or copy constructor.
| RWDBTable RWDBDatabase::table | ( | const RWCString & | name, |
| const RWDBSchema & | schema, | ||
| bool | isView = false |
||
| ) | const |
Produces an RWDBTable with the given name. The returned object is an instance of a database table. The supplied schema is used as the table's schema. If isView is true, it is assumed that the table represents a database view. If a cache manager is present, schema and isView are stored in the cache, replacing any existing schema and isView information stored in the cache. See RWDBTable for an explanation of the different kinds of RWDBTable objects.
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 a table and associated tags should be produced by RWDBTable::operator=() or copy constructor. It is assumed that the contents of the supplied schema are correct for the named RWDBTable. If not, the program may produce unexpected results.
| RWDBTable RWDBDatabase::table | ( | const RWDBSelectorBase & | selector | ) | const |
| const RWZone& RWDBDatabase::timeZone | ( | ) | const |
Returns a reference to the time zone set on self. If the time zone is not set, returns RWZone::local().
Sets self's time zone to zone. All explicit and implicit RWDBConnection objects produced from self inherit the time zone setting at the time they are produced.
| zone | The time zone to be set on self. Pass NULL to unset the time zone setting. |
NULL when the time zone was not set.| size_t RWDBDatabase::totalConnections | ( | ) | const |
Returns the total number of connections an application is using or has retained in the connection pool.
| RWDBTracer& RWDBDatabase::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 RWDBDatabase::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 RWDBDatabase::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 RWDBUpdater::where() on the produced RWDBUpdater object replaces criterion, rather than adds to it.
| RWCString RWDBDatabase::userName | ( | ) | const |
Returns the user name passed in when constructing self. See RWDBManager for more information.
DB XA Module: Returns an empty string.
| bool RWDBDatabase::verboseAsString | ( | ) | const |
Accessor function that returns self's verboseAsString setting.
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.
verboseAsString setting 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.verboseAsString setting is set to true, the asString() methods of the above classes return the SQL with the placeholders replaced by their bound values. | bool RWDBDatabase::verboseAsString | ( | bool | verbose | ) |
Sets self's verboseAsString setting to verbose and returns its previous value. 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.
verboseAsString setting 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.verboseAsString setting is set to true, the asString() methods of the above classes will return the SQL with the placeholders replaced by their bound values.verboseAsString setting 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 RWDBDatabase::version | ( | ) | const |
Returns a string that identifies the version number of the DB Interface Module and the DB Access Module being used.
|
related |
The default value for the type argument to dbTables().
|
Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |