SourcePro® API Reference Guide

 
List of all members | Public Types | Public Member Functions | Related Functions
RWDBTable Class Reference

Base class for a family of classes that represent the abstract notion of a database table in a number of different ways. More...

#include <rw/db/table.h>

Inheritance diagram for RWDBTable:
RWDBMemTable RWDBTMemTableBase RWDBTPtrMemTable< T, C >

Public Types

enum  CacheType { Local, All }
 
enum  Metadata {
  None, ColumnList, DefaultValues, IdentityConstraint,
  PrimaryKey
}
 

Public Member Functions

 RWDBTable ()
 
 RWDBTable (const RWDBTable &table)
 
void acquire (void) const
 
RWDBStatus addColumn (const RWDBColumn &column)
 
RWDBStatus addColumn (const RWDBColumn &column, const RWDBConnection &connection)
 
RWDBStatus addColumn (const RWCString &name, RWDBValue::ValueType type=RWDBValue::NoType, long storageLength=0, int nativeType=-1, int precision=-1, int scale=-1, bool nullAllowed=true, RWDBColumn::ParamType paramType=RWDBColumn::notAParameter)
 
RWDBStatus addColumn (const RWCString &name, const RWDBConnection &connection, RWDBValue::ValueType type=RWDBValue::NoType, long storageLength=0, int nativeType=-1, int precision=-1, int scale=-1, bool nullAllowed=true, RWDBColumn::ParamType paramType=RWDBColumn::notAParameter)
 
RWDBStatus addConstraint (const RWDBPrimaryKey &pk)
 
RWDBStatus addConstraint (const RWDBPrimaryKey &pk, const RWDBConnection &connection)
 
RWDBStatus addConstraint (const RWDBForeignKey &fk)
 
RWDBStatus addConstraint (const RWDBForeignKey &fk, const RWDBConnection &connection)
 
RWDBStatus addConstraint (const RWDBCheckConstraint &cc)
 
RWDBStatus addConstraint (const RWDBCheckConstraint &cc, const RWDBConnection &connection)
 
RWDBStatus addConstraint (const RWDBUniqueConstraint &uc)
 
RWDBStatus addConstraint (const RWDBUniqueConstraint &uc, const RWDBConnection &connection)
 
RWDBBulkInserter bulkInserter (const RWDBConnection &conn) const
 
RWDBBulkReader bulkReader (const RWDBConnection &conn) const
 
RWDBStatus checkConstraints (const RWDBConnection &conn, const RWCString &constraintName, RWDBCheckConstraintList &list)
 
RWDBStatus checkConstraints (const RWCString &constraintName, RWDBCheckConstraintList &list)
 
void clearCache (CacheType cache=RWDBTable::Local)
 
RWDBColumn column (size_t index) const
 
RWDBColumn column (const RWCString &name) const
 
RWDBColumn column (const RWCString &name, RWCString::caseCompare caseCompare) const
 
RWDBStatus createIndex (const RWCString &name, const RWDBSchema &columns, bool unique=true, bool clustered=true)
 
RWDBStatus createIndex (const RWCString &name, const RWDBSchema &columns, const RWDBConnection &connection, bool unique=true, bool clustered=true)
 
RWDBCursor cursor (RWDBCursor::CursorType type=RWDBCursor::Sequential, RWDBCursor::CursorAccess access=RWDBCursor::Read) const
 
RWDBCursor cursor (const RWDBConnection &connection, RWDBCursor::CursorType type=RWDBCursor::Sequential, RWDBCursor::CursorAccess access=RWDBCursor::Read) const
 
RWDBCursor cursor (const RWDBSchema &updateCols, RWDBCursor::CursorType type=RWDBCursor::Sequential, RWDBCursor::CursorAccess access=RWDBCursor::Read) const
 
RWDBCursor cursor (const RWDBSchema &updateCols, const RWDBConnection &connection, RWDBCursor::CursorType type=RWDBCursor::Sequential, RWDBCursor::CursorAccess access=RWDBCursor::Read) const
 
RWDBDatabase database () const
 
RWDBDeleter deleter () const
 
RWDBDeleter deleter (const RWDBCriterion &criterion) const
 
virtual RWDBSchema describe (Metadata md)
 
virtual RWDBSchema describe (Metadata md, const RWDBConnection &conn)
 
RWDBStatus drop ()
 
RWDBStatus drop (const RWDBConnection &connection)
 
RWDBStatus dropColumn (const RWDBColumn &column)
 
RWDBStatus dropColumn (const RWDBColumn &column, const RWDBConnection &connection)
 
RWDBStatus dropConstraint (const RWCString &constraintName)
 
RWDBStatus dropConstraint (const RWCString &constraintName, const RWDBConnection &connection)
 
RWDBStatus dropConstraint (const RWDBPrimaryKey &pk)
 
RWDBStatus dropConstraint (const RWDBPrimaryKey &pk, const RWDBConnection &connection)
 
RWDBStatus dropConstraint (const RWDBForeignKey &fk)
 
RWDBStatus dropConstraint (const RWDBForeignKey &fk, const RWDBConnection &connection)
 
RWDBStatus dropConstraint (const RWDBCheckConstraint &cc)
 
RWDBStatus dropConstraint (const RWDBCheckConstraint &cc, const RWDBConnection &connection)
 
RWDBStatus dropConstraint (const RWDBUniqueConstraint &uc)
 
RWDBStatus dropConstraint (const RWDBUniqueConstraint &uc, const RWDBConnection &connection)
 
RWDBStatus dropIndex (const RWCString &name)
 
RWDBStatus dropIndex (const RWCString &name, const RWDBConnection &connection)
 
RWDBStatus::ErrorHandler errorHandler () const
 
bool exists (bool forceLookup=false)
 
bool exists (const RWDBConnection &connection, bool forceLookup=false)
 
virtual bool fetchSchema ()
 
virtual bool fetchSchema (const RWDBConnection &connection)
 
RWDBStatus foreignKeys (const RWDBConnection &conn, const RWCString &refName, RWDBForeignKeyList &keyList)
 
RWDBStatus foreignKeys (const RWCString &refName, RWDBForeignKeyList &keyList)
 
RWDBStatus grant (const RWCString &priv, const RWCString &user)
 
RWDBStatus grant (const RWCString &priv, const RWCString &user, const RWDBConnection &connection)
 
RWDBStatus grant (const RWCString &priv, const RWDBSchema &colList, const RWCString &user)
 
RWDBStatus grant (const RWCString &priv, const RWDBSchema &colList, const RWCString &user, const RWDBConnection &connection)
 
RWDBColumn identityColumn () const
 
size_t index (const RWCString &name) const
 
size_t index (const RWCString &name, RWCString::caseCompare caseCompare) const
 
size_t index (const RWDBColumn &column) const
 
RWDBInserter inserter (size_t cache=0) const
 
RWDBInserter inserter (const RWDBSelector &selector) const
 
RWDBInserter inserter (const RWDBCompoundSelector &selector) const
 
RWDBInserter inserter (const RWDBSchema &columnList, size_t cache=0) const
 
RWDBInserter inserter (const RWDBSelector &selector, const RWDBSchema &columnList) const
 
RWDBInserter inserter (const RWDBCompoundSelector &selector, const RWDBSchema &columnList) const
 
bool isReady () const
 
bool isValid () const
 
bool isView () const
 
bool isView (const RWDBConnection &conn) const
 
RWCString name () const
 
RWDBTablename (const RWCString &name)
 
size_t numberOfColumns () const
 
RWDBTableoperator= (const RWDBTable &table)
 
RWDBColumn operator[] (const RWCString &name) const
 
RWDBColumn operator[] (size_t position) const
 
RWDBPrimaryKey primaryKey (const RWDBConnection &conn)
 
RWDBPrimaryKey primaryKey ()
 
RWDBReader reader (size_t cacheSize=0) const
 
RWDBReader reader (const RWDBConnection &connection, size_t cacheSize=0) const
 
RWDBStatus referredToBy (const RWDBConnection &conn, RWDBForeignKeyList &keyList)
 
RWDBStatus referredToBy (RWDBForeignKeyList &keyList)
 
void release (void) const
 
RWDBStatus revoke (const RWCString &privilege, const RWCString &user)
 
RWDBStatus revoke (const RWCString &privilege, const RWCString &user, const RWDBConnection &connection)
 
RWDBStatus revoke (const RWCString &privilege, const RWDBSchema &columnList, const RWCString &user)
 
RWDBStatus revoke (const RWCString &privilege, const RWDBSchema &columnList, const RWCString &user, const RWDBConnection &connection)
 
RWDBSchema schema () const
 
void setErrorHandler (RWDBStatus::ErrorHandler errorHandler)
 
RWDBStatus status () const
 
RWCString tag () const
 
RWDBTabletag (const RWCString &newtag)
 
RWDBStatus uniqueConstraints (const RWDBConnection &conn, const RWCString &constraintName, RWDBUniqueConstraintList &list)
 
RWDBStatus uniqueConstraints (const RWCString &constraintName, RWDBUniqueConstraintList &list)
 
RWDBUpdater updater () const
 
RWDBUpdater updater (const RWDBCriterion &criterion) const
 

Related Functions

(Note that these are not member functions.)

RWDBTable::Metadata operator& (RWDBTable::Metadata lhs, RWDBTable::Metadata rhs)
 
RWDBTable::Metadataoperator&= (RWDBTable::Metadata &lhs, RWDBTable::Metadata rhs)
 
RWDBTable::Metadata operator^ (RWDBTable::Metadata lhs, RWDBTable::Metadata rhs)
 
RWDBTable::Metadataoperator^= (RWDBTable::Metadata &lhs, RWDBTable::Metadata rhs)
 
RWDBTable::Metadata operator| (RWDBTable::Metadata lhs, RWDBTable::Metadata rhs)
 
RWDBTable::Metadataoperator|= (RWDBTable::Metadata &lhs, RWDBTable::Metadata rhs)
 
RWDBTable::Metadata operator~ (RWDBTable::Metadata md)
 

Detailed Description

RWDBTable is a base class from which a family of classes derive. RWDBTable represents a table of information whose actual location is transparent. The data may reside in a database table or in program memory, or may be an SQL table expression, that is, a derived table or collection of rows returned from a database query. The types of tables to which RWDBTable provides an interface are:

RWDBTable is designed around the Interface/Implementation paradigm. An RWDBTable instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBTable implementation is a base class from which a family of table implementations is derived. Each implementation except that of a derived table and RWDBMemTable is in turn a base class from which a family of database-specific table implementations derive.

Synopsis
#include <rw/db/table.h>
RWDBTable myTable = myDbase.table("tableName");
RWDBTable myMemTable = myDbase.memTable("tableName");
RWDBResult myResult = mySelector.execute();
//or deleter.execute() or updater.execute() or inserter.execute() or
//storedProc.execute()
RWDBTable myResultTable = myResult.table();

Member Enumeration Documentation

A class-scoped enum containing the cache types.

Enumerator
Local 

Clears self's cache. Cached data for an RWDBTable consists of the schema, the state of the exists flag and whether self is a view or not. Note that data about primary keys, foreign keys, referred-to-by keys, check constraints, unique constraints and identity column, if stored in schema, is also cleared.

All 

Clears cached data in self and in the cache manager derived from RWDBCacheManager, if there is one. Cached data for an RWDBTable consists of schema, the state of the exists flag and whether self is a view or not. Note that data about primary keys, foreign keys, referred-to-by keys, check constraints, unique constraints and identity column, if stored in schema, is also cleared.

A class-scoped enum containing the metadata types.

Enumerator
None 

No metadata type.

ColumnList 

List of columns of a table including applicable attributes such as column name, type, storage length, native type, precision, scale and null allowed.

DefaultValues 

Default values associated with columns of a database table.

Note
Applies only to database tables.
IdentityConstraint 

Identity constraint on a database table.

Note
Applies only to database tables.
PrimaryKey 

Primary key of a database table.

Note
Applies only to database tables.

Constructor & Destructor Documentation

RWDBTable::RWDBTable ( )

The default constructor creates an RWDBTable whose status is RWDBStatus::notInitialized. This constructor is provided as a convenience, for example, for declaring an array of RWDBTable objects. Usable RWDBTable objects are obtained from RWDBDatabase and RWDBResult.

RWDBTable::RWDBTable ( const RWDBTable table)

Copy constructor. Self shares an implementation with table.

Member Function Documentation

void RWDBTable::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.

Note
In single-threaded builds, this function evaluates to a no-op.
RWDBStatus RWDBTable::addColumn ( const RWDBColumn column)

Uses a default database connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD COLUMN <column>

where <table> is the database table represented by self, and <column> is defined by the given column. If successful, calls fetchSchema() so that self's schema remains consistent with the database. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::addColumn ( const RWDBColumn column,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD COLUMN <column>

where <table> is the database table represented by self, and <column> is defined by the given column. If successful, calls fetchSchema() so that self's schema remains consistent with the database. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage. 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 RWDBTable::addColumn ( const RWCString name,
RWDBValue::ValueType  type = RWDBValue::NoType,
long  storageLength = 0,
int  nativeType = -1,
int  precision = -1,
int  scale = -1,
bool  nullAllowed = true,
RWDBColumn::ParamType  paramType = RWDBColumn::notAParameter 
)

Uses a default database connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD COLUMN <column>

where <table> is the database table represented by self, and <column> is defined by the supplied arguments. If successful, calls fetchSchema() so that self's schema remains consistent with the database. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::addColumn ( const RWCString name,
const RWDBConnection connection,
RWDBValue::ValueType  type = RWDBValue::NoType,
long  storageLength = 0,
int  nativeType = -1,
int  precision = -1,
int  scale = -1,
bool  nullAllowed = true,
RWDBColumn::ParamType  paramType = RWDBColumn::notAParameter 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD COLUMN <column>

where <table> is the database table represented by self, and <column> is defined by the supplied arguments. If successful, calls fetchSchema() so that self's schema remains consistent with the database. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage. 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 RWDBTable::addConstraint ( const RWDBPrimaryKey pk)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> PRIMARY KEY(<column-list>)

or

1 ALTER TABLE <table> ADD PRIMARY KEY(<column-list>)

where <table> is self's table name, <constraint-name> is the constraint name if supplied, and <column-list> is a list of column names in the primary key. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBPrimaryKey pk,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> PRIMARY KEY(<column-list>)

or

1 ALTER TABLE <table> ADD PRIMARY KEY(<column-list>)

where <table> is self's table name, <constraint-name> is the constraint name if supplied, and <column-list> is a list of column names in the primary key. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBForeignKey fk)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> FOREIGN KEY(<column-list>) REFERENCES <ref-table>(<ref-column-list>)

or

1 ALTER TABLE <table> ADD FOREIGN KEY(<column-list>) REFERENCES <ref-table>(<ref-column-list>)

where <table> is self's table name, <constraint-name> is the constraint name if supplied, <column-list> is a list of column names in the foreign key, <ref-table> is the referenced table, and <ref-column-list> is a list of column names referred to in the referenced table. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBForeignKey fk,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> FOREIGN KEY(<column-list>) REFERENCES <table>(<column-list>)

or

1 ALTER TABLE <table> ADD FOREIGN KEY(<column-list>) REFERENCES <ref-table>(<ref-column-list>)

where <table> is self's table name, <constraint-name> is the constraint name if supplied, <column-list> is a list of column names in the foreign key, <ref-table> is the referenced table, and <ref-column-list> is a list of column names referred to in the referenced table. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBCheckConstraint cc)

Uses a default connection to execute the database=specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> CHECK(<check-condition>)

or

1 ALTER TABLE <table> ADD CHECK(<check-condition>)

where <table> is self's table name, <constraint-name> is the name of the constraint if supplied, and <check-condition> is the check condition. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBCheckConstraint cc,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> CHECK(<check-condition>)

or

1 ALTER TABLE <table> ADD CHECK(<check-condition>)

where <table> is self's table name, <constraint-name> is the name of the constraint if supplied, and <check-condition> is the check condition. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBUniqueConstraint uc)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> UNIQUE(<column-list>)

or

1 ALTER TABLE <table> ADD UNIQUE(<column-list>)

where <table> is self's table name, <constraint-name> is the name of the constraint if supplied, and <column-list> is a list of column names in the unique constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::addConstraint ( const RWDBUniqueConstraint uc,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> ADD CONSTRAINT <constraint-name> UNIQUE(<column-list>)

or

1 ALTER TABLE <table> ADD UNIQUE(<column-list>)

where <table> is self's table name, <constraint-name> is the name of the constraint if supplied, and <column-list> is a list of column names in the unique constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBBulkInserter RWDBTable::bulkInserter ( const RWDBConnection conn) const

Returns an RWDBBulkInserter able to insert values into self. The RWDBBulkInserter executes using the supplied connection.

RWDBBulkReader RWDBTable::bulkReader ( const RWDBConnection conn) const

Returns an RWDBBulkReader able to read the result set associated with the rows of self. If self is a derived table, the RWDBBulkReader produced reads rows of the result set from execution of the SQL self represents. The RWDBBulkReader executes using the supplied connection.

RWDBStatus RWDBTable::checkConstraints ( const RWDBConnection conn,
const RWCString constraintName,
RWDBCheckConstraintList list 
)

Calls RWDBCacheManager::getCheckConstraints() const. If successful, appends the check constraints to list. Otherwise, uses conn to append a list of check constraints to list and, if successful, calls RWDBCacheManager::setCheckConstraints(const RWDBCheckConstraintList&). If constraintName is blank, list will contain all of self's check constraints. If constraintName is not blank, list will contain the check constraint of self whose name is constraintName. A list without appended elements indicates there are no check constraints associated with self. You can check the return value's isValid() method to determine whether the operation succeeded.

Note
This method ensures the schema has already been retrieved before attempting to get the check constraints.
RWDBStatus RWDBTable::checkConstraints ( const RWCString constraintName,
RWDBCheckConstraintList list 
)

Calls RWDBCacheManager::getCheckConstraints() const. If successful, appends the check constraints to list. Otherwise, uses a default connection to append a list of check constraints to list and, if successful, calls RWDBCacheManager::setCheckConstraints(const RWDBCheckConstraintList&). If constraintName is blank, list will contain all of self's check constraints. If constraintName is not blank, list will contain the check constraint of self whose name is constraintName. A list without appended elements indicates there are no check constraints associated with self. You can check the return value's isValid() method to determine whether the operation succeeded.

Note
This method ensures the schema has already been retrieved before attempting to get the check constraints.
void RWDBTable::clearCache ( CacheType  cache = RWDBTable::Local)

Clears cached metadata information. If cache is RWDBTable::Local, clears cache in self. If cache is RWDBTable::All, clears cache in self and in the global cache derived from RWDBCacheManager, if there is one.

RWDBColumn RWDBTable::column ( size_t  index) const

Returns a deep copy of the RWDBColumn in self's schema at the given index. The RWDBColumn returned is associated with self, that is, the table() method of the returned RWDBColumn returns this table. A deep copy is made so that applications can modify the returned RWDBColumn without modifying the associated RWDBTable schema. If index is out of range, returns an RWDBColumn whose status is RWDBStatus::columnNotFound.

RWDBColumn RWDBTable::column ( const RWCString name) const

Returns a deep copy of the first RWDBColumn in self's schema whose name matches the given name. The RWDBColumn returned is associated with self, that is, the table() method of the returned RWDBColumn returns this table. If no matching column is found, returns an RWDBColumn whose status is RWDBStatus::columnNotFound. A deep copy is made so that applications can modify the returned RWDBColumn without modifying the associated RWDBTable schema.

RWDBColumn RWDBTable::column ( const RWCString name,
RWCString::caseCompare  caseCompare 
) const

Returns a deep copy of the first RWDBColumn in self's schema whose name matches the given name, according to caseCompare. The RWDBColumn returned is associated with self, that is, the table() method of the returned RWDBColumn returns this table. If no matching column is found, returns an RWDBColumn whose status is RWDBStatus::columnNotFound. A deep copy is made so that applications can modify the returned RWDBColumn without modifying self's schema.

RWDBStatus RWDBTable::createIndex ( const RWCString name,
const RWDBSchema columns,
bool  unique = true,
bool  clustered = true 
)

Uses a default connection to send the database-specific equivalent of the SQL statement:

1 CREATE [unique] [clustered] INDEX name
2 ON <table> (<columns>)

where name is the name of the index to be created, <table> is the database table represented by self, <columns> is a list of columns defined by columns, and the optional keywords unique and clustered are present or absent according to the supplied values unique and clustered. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::createIndex ( const RWCString name,
const RWDBSchema columns,
const RWDBConnection connection,
bool  unique = true,
bool  clustered = true 
)

Uses the supplied connection to send the database-specific equivalent of the SQL statement:

1 CREATE [unique] [clustered] INDEX name
2 ON <table> (<columns>)

where name is the name of the index to be created, <table> is the database table represented by self, <columns> is a list of columns defined by columns, and the optional keywords unique and clustered are present or absent according to the supplied values unique and clustered. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage. 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.

If self is a database table, produces an RWDBCursor for execution of the SQL statement:

1 SELECT * from <table>

where <table> is the database table represented by self.

If self is a derived table, produces an RWDBCursor for execution of the SQL Select statement self represents.

The cursor is created on a default database connection, using the type and access specifications provided. The connection is held by the RWDBCursor until the RWDBCursor is destroyed. If self is a result table or a memory table, the function produces an RWDBCursor whose status is RWDBStatus::noCursor.

RWDBCursor RWDBTable::cursor ( const RWDBConnection connection,
RWDBCursor::CursorType  type = RWDBCursor::Sequential,
RWDBCursor::CursorAccess  access = RWDBCursor::Read 
) const

If self is a database table, produces an RWDBCursor for execution of the SQL statement:

1 SELECT * from <table>

where <table> is the database table represented by self.

If self is a derived table, produces an RWDBCursor for execution of the SQL Select statement self represents.

The cursor is created on the supplied database connection, using the type and access specifications provided. The connection is held by the RWDBCursor until the RWDBCursor is destroyed. If self is a result table or a memory table, the function produces an RWDBCursor with status RWDBStatus::noCursor. This function can behave asynchronously if executed using an asynchronous connection.

RWDBCursor RWDBTable::cursor ( const RWDBSchema updateCols,
RWDBCursor::CursorType  type = RWDBCursor::Sequential,
RWDBCursor::CursorAccess  access = RWDBCursor::Read 
) const

Produces an RWDBCursor for execution of the SQL statement:

1 SELECT * from <table>

where <table> is the database table represented by self.

If self is a derived table, produces an RWDBCursor for execution of the SQL SELECT statement self represents.

The argument updateCols is used in building a clause:

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

Some SQL dialects require this form. The cursor is created on a default database connection, using the type and access specifications provided. The connection is held by the RWDBCursor until the RWDBCursor is destroyed.

RWDBCursor RWDBTable::cursor ( const RWDBSchema updateCols,
const RWDBConnection connection,
RWDBCursor::CursorType  type = RWDBCursor::Sequential,
RWDBCursor::CursorAccess  access = RWDBCursor::Read 
) const

Produces an RWDBCursor for execution of the SQL statement:

1 SELECT * from <table>

where <table> is the database table represented by self.

If self is a derived table, produces an RWDBCursor for execution of the SQL SELECT statement self represents.

The cursor is created on the supplied database connection, using the type and access specifications provided. The connection is held by the RWDBCursor until the RWDBCursor is destroyed. Some SQL dialects require this form. The argument updateCols is used in building a clause:

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

This function can behave asynchronously if executed using an asynchronous connection.

RWDBDatabase RWDBTable::database ( ) const

Returns the RWDBDatabase that produced this table. If there is no such object, for example, if this table was created by the default constructor, returns an RWDBDatabase with status RWDBStatus::notInitialized. If self is a memory table, this method always returns an RWDBDatabase with a status of RWDBStatus::notInitialized.

RWDBDeleter RWDBTable::deleter ( ) const

Produces an RWDBDeleter that can be used to delete all rows from self. The result is an encapsulation of the SQL statement:

1 DELETE FROM <table>

where <table> is self's table name. If self is not a database table, returns an RWDBDeleter whose status is RWDBStatus::noDeleter.

RWDBDeleter RWDBTable::deleter ( const RWDBCriterion criterion) const

Produces an RWDBDeleter that can be used to delete rows from self based on criterion. An RWDBCriterion is an encapsulated SQL WHERE clause. The result is an encapsulation of the SQL statement:

1 DELETE FROM <table> WHERE criterion

where <table> is self's table name. If self is not a database table, returns an RWDBDeleter whose status is RWDBStatus::noDeleter.

virtual RWDBSchema RWDBTable::describe ( Metadata  md)
virtual

Checks local cache for the metadata types requested in md. If the metadata information is not in the local cache, queries the database using an implicit connection. If successful, returns a shallow copy of self's RWDBSchema. On failure, returns an empty RWDBSchema with error information set on it, if any. Argument md could be a bit-mask of multiple metadata types.

If md is passed as None, no metadata is fetched from the database and a shallow copy of the local RWDBSchema is returned.

Note
RWDBTable::ColumnList will be fetched by all metadata types except RWDBTable::None.
virtual RWDBSchema RWDBTable::describe ( Metadata  md,
const RWDBConnection conn 
)
virtual

Checks local cache for the metadata types requested in md. If the metadata information is not in the local cache, queries the database using the supplied database connection conn. If successful, returns a shallow copy of self's RWDBSchema. On failure, returns an empty RWDBSchema with error information set on it, if any. Argument md could be a bit-mask of multiple metadata types.

If md is passed as None, no metadata is fetched from the database and a shallow copy of the local RWDBSchema is returned.

Note
RWDBTable::ColumnList will be fetched by all metadata types except RWDBTable::None.
RWDBStatus RWDBTable::drop ( )

Uses a default database connection to drop the database table or view represented by self. Sends the database-specific equivalent of either the SQL statement:

1 DROP TABLE <table>

where <table> is the database table represented by self, or:

1 DROP VIEW <view>

where <view> is the database view represented by self. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table or view, the returned status is RWDBStatus::invalidUsage.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::drop ( const RWDBConnection connection)

Uses the supplied connection to drop the database table or view represented by self. Sends the database-specific equivalent of either the SQL statement:

1 DROP TABLE <table>

where <table> is the database table represented by self, or:

1 DROP VIEW <view>

where <view> is the database view represented by self. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table or view, the returned status is RWDBStatus::invalidUsage. 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 RWDBTable::dropColumn ( const RWDBColumn column)

Uses a default database connection to execute the database-specific equivalent of the SQL:

1 ALTER TABLE <table> DROP COLUMN <column>

where <table> is the database table represented by self, and <column> is the column name of the given column. If successful, calls fetchSchema() so that self's schema remains consistent with the database. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::dropColumn ( const RWDBColumn column,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL:

1 ALTER TABLE <table> DROP COLUMN <column>

where <table> is the database table represented by self, and <column> is the column name of the given column. If successful, calls fetchSchema() so that self's schema remains consistent with the database. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage. 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 RWDBTable::dropConstraint ( const RWCString constraintName)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWCString constraintName,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBPrimaryKey pk)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBPrimaryKey pk,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBForeignKey fk)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBForeignKey fk,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBCheckConstraint cc)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBCheckConstraint cc,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBUniqueConstraint uc)

Uses a default connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropConstraint ( const RWDBUniqueConstraint uc,
const RWDBConnection connection 
)

Uses the supplied connection to execute the database-specific equivalent of the SQL statement:

1 ALTER TABLE <table> DROP CONSTRAINT <constraint-name>

where <table> is self's table name and <constraint-name> is the name of the constraint. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

This function can behave asynchronously if executed using an asynchronous connection.

RWDBStatus RWDBTable::dropIndex ( const RWCString name)

Uses a default database connection to send the database-specific equivalent of the SQL:

1 DROP INDEX <table>.name

where <table> is the database table represented by self, and name is the name of the index to be dropped. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::dropIndex ( const RWCString name,
const RWDBConnection connection 
)

Uses the supplied connection to send the database-specific equivalent of the SQL:

1 DROP INDEX <table>.name

where <table> is the database table represented by self, and name is the name of the index to be dropped. You can check the return value's isValid() method to determine whether the operation succeeded. If self is not a database table, the returned status is RWDBStatus::invalidUsage. 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::ErrorHandler RWDBTable::errorHandler ( ) const

Returns the error handler attached to self.

bool RWDBTable::exists ( bool  forceLookup = false)

If self is a database table, returns true if the table exists in the database, otherwise returns false. If self is a derived table, returns true if the schema of the result set of the SQL SELECT statement that self represents can be fetched, otherwise returns false. If self is a memory table, always returns false. If self is a result table, returns true if an RWDBReader has not yet been obtained to read self, otherwise returns false.

To determine whether or not a database table exists, the DB Interface Module uses a default connection to query the database. To determine whether or not a derived table exists, the DB Interface Module uses a default connection to fetch the schema of the encapsulated RWDBSelectorBase instance. If no schema can be obtained, returns false. Otherwise, self's RWDBSchema is populated with the result of the query, and returns true.

By default, multiple calls to a database table's or derived table's exists() method always return the same result; the database is only queried on the first call. This behavior can be overridden by forceLookup, which, if true, forces the database to be queried.

Note
The forceLookup parameter is deprecated. Use clearCache() to clear the metadata from the cache before calling this method.
bool RWDBTable::exists ( const RWDBConnection connection,
bool  forceLookup = false 
)

If self is a database table, returns true if the table exists in the database, otherwise returns false. If self is a derived table, returns true if the schema of the result set of the SQL SELECT statement that self represents can be fetched, otherwise returns false. If self is a memory table, always returns false. If self is a result table, returns true if an RWDBReader has not yet been obtained to read self, otherwise returns false.

To determine whether or not a database table exists, the DB Interface Module uses the supplied connection to query the database. To determine whether or not a derived table exists, the DB Interface Module uses the supplied connection to fetch the schema of the encapsulated RWDBSelectorBase instance. If no schema can be obtained, returns false. Otherwise, self's RWDBSchema is populated with the result of the query, and returns true.

By default, multiple calls to a database table's or derived table's exists() method always return the same result; the database is only queried on the first call. This behavior can be overridden by forceLookup, which forces the database to be queried if true.

Note
The forceLookup parameter is deprecated. Use clearCache() to clear the metadata from the cache before calling this method.
virtual bool RWDBTable::fetchSchema ( )
virtual

If self is a database table, returns true if schema information about the table can be obtained, otherwise returns false. If self is a derived table, returns true if the schema of the result set of the SQL SELECT statement that self represents can be fetched, otherwise returns false. If self is a memory table, always returns true. If self is a result table, returns true if an RWDBReader has not yet been obtained to read self, otherwise returns false.

To obtain schema information, the DB Interface Module uses a default database connection to query the database. If no schema can be obtained, false is returned. Otherwise, self's RWDBSchema is populated with the result of the query and true is returned.

virtual bool RWDBTable::fetchSchema ( const RWDBConnection connection)
virtual

If self is a database table, returns true if the schema information about the table can be obtained, otherwise returns false. If self is a derived table, returns true if the schema of the result set of the SQL SELECT statement that self represents can be fetched, otherwise returns false. If self is a memory table, always returns true. If self is a result table, returns true if an RWDBReader has not yet been obtained to read self, otherwise returns false.

To obtain schema information, the DB Interface Module uses the supplied connection to query the database. If no schema can be obtained, false is returned. Otherwise, self's RWDBSchema is populated with the result of the query and true is returned.

RWDBStatus RWDBTable::foreignKeys ( const RWDBConnection conn,
const RWCString refName,
RWDBForeignKeyList keyList 
)

Calls RWDBCacheManager::getForeignKeys() const. If successful, appends the foreign keys to keyList. Otherwise, uses conn to append a list of foreign keys to keyList. If refName is blank, keyList will contain all self's foreign keys. If refName is not blank, keyList will contain the foreign key of self that refers to refName. An empty list indicates there are no foreign keys associated with self referring to refName. You can check the return value's isValid() method to determine whether the operation succeeded. If successful, calls RWDBCacheManager::setForeignKeys(const RWDBForeignKeyList&).

Note
This method ensures the schema has already been retrieved before attempting to get the foreign keys.
RWDBStatus RWDBTable::foreignKeys ( const RWCString refName,
RWDBForeignKeyList keyList 
)

Calls RWDBCacheManager::getForeignKeys() const. If successful, appends the foreign keys to keyList. Otherwise, uses a default connection to append a list of foreign keys to keyList. If refName is blank, keyList will contain all self's foreign keys. If refName is not blank, keyList will contain the foreign key of self that refers to refName. An empty list indicates there are no foreign keys associated with self referring to refName. You can check the return value's isValid() method to determine whether the operation succeeded. If successful, calls RWDBCacheManager::setForeignKeys(const RWDBForeignKeyList&).

Note
This method ensures the schema has already been retrieved before attempting to get the foreign keys.
RWDBStatus RWDBTable::grant ( const RWCString priv,
const RWCString user 
)

Uses a default database connection to execute the database-specific equivalent of the SQL:

1 GRANT privilege ON <table> TO user

where <table> is self's table name. The DB Interface Module does not validate the supplied arguments. You can check the returned object's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::noPrivilege.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::grant ( const RWCString priv,
const RWCString user,
const RWDBConnection connection 
)

Uses the supplied database connection connection to execute the database-specific equivalent of the SQL:

1 GRANT privilege ON <table> TO user

where <table> is self's table name. The DB Interface Module does not validate the supplied arguments. You can check the returned object's isValid() method to see if the operation succeeded. If self is not a database table, the returned status is RWDBStatus::noPrivilege. 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 RWDBTable::grant ( const RWCString priv,
const RWDBSchema colList,
const RWCString user 
)

Uses a default database connection to execute the database-specific equivalent of the SQL:

1 GRANT privilege ON <table> (<column-list>) TO user

where <table> is self's table name, and <column-list> is a list of column names from self's schema. The DB Interface Module does not validate the supplied arguments. You can check the returned object's isValid() method to see if the operation succeeded. If self is not a database table, the returned object is RWDBStatus::noPrivilege.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::grant ( const RWCString priv,
const RWDBSchema colList,
const RWCString user,
const RWDBConnection connection 
)

Uses the supplied database connection to execute the database-specific equivalent of the SQL:

1 GRANT privilege ON <table> (<column-list>) TO user

where <table> is self's table name, and <column-list> is a list of column names from self's schema. The DB Interface Module does not validate the supplied arguments. You can check the returned object's isValid() method to see if the operation succeeded. If self is not a database table, the returned object is RWDBStatus::noPrivilege. 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.

RWDBColumn RWDBTable::identityColumn ( ) const

Returns a deep copy of self's identity column. If there is no identity column, returns an RWDBColumn whose RWDBStatus is columnNotFound.

size_t RWDBTable::index ( const RWCString name) const

Returns the index in self's schema of the first column with the given name. Returns RW_NPOS if there is no such column.

size_t RWDBTable::index ( const RWCString name,
RWCString::caseCompare  caseCompare 
) const

Returns the index in self's schema of the first column which matches the given name, according to caseCompare. Returns RW_NPOS if there is no such column.

size_t RWDBTable::index ( const RWDBColumn column) const

Returns the index in self's schema of the first column whose name matches the name of the given column. Returns RW_NPOS if there is no such column.

RWDBInserter RWDBTable::inserter ( size_t  cache = 0) const

Produces an RWDBInserter that encapsulates the SQL statement:

1 INSERT INTO <table> VALUES

where <table> is represented by self. The actual values must be added to the inserter later. If self is not a database table, returns an RWDBInserter with a status of RWDBStatus::noInserter.

Note
Specifying cache as 0 or 1 creates a non-cached inserter (the default), while any larger value creates a cache that collects the specified number of rows before placing them in the table. It is important to understand that using a cache means executing an insert does not necessary immediately place the data in the table. The DB Interface Module User Guide includes a discussion of RWDBInserter caching. You should also check your Access Module documentation for limitations and warnings.
RWDBInserter RWDBTable::inserter ( const RWDBSelector selector) const

Produces an RWDBInserter that encapsulates the SQL statement:

1 INSERT INTO <table> select-statement

where <table> is represented by self. The select-statement is encapsulated by the given selector. This method is equivalent to database.inserter(*this, selector). If self is not a database table, returns an RWDBInserter with a status of RWDBStatus::noInserter.

RWDBInserter RWDBTable::inserter ( const RWDBCompoundSelector selector) const

Produces an RWDBInserter that encapsulates the SQL statement:

1 INSERT INTO <table> <select-statement>

where <table> is represented by self. The <select-statement> is encapsulated by the given selector. This method is equivalent to database.inserter(*this, selector). If self is not a database table, returns an RWDBInserter with a status of RWDBStatus::noInserter.

RWDBInserter RWDBTable::inserter ( const RWDBSchema columnList,
size_t  cache = 0 
) const

Produces an RWDBInserter that encapsulates the SQL statement:

1 INSERT INTO <table> (col1, ..., coln)
2 VALUES(val1, ..., valn)

where <table> is represented by self. The names of the column entries in columnList are used to build up the column-name list. If self is not a database table, returns an RWDBInserter with a status of RWDBStatus::noInserter.

Note
Specifying cache as 0 or 1 creates a non-cached inserter (the default), while any larger value creates a cache that collects the specified number of rows before placing them in the table. It is important to understand that using a cache means executing an insert does not necessary immediately place the data in the table. The DB Interface Module User Guide includes a discussion of RWDBInserter caching. You should also check your Access Module documentation for limitations and warnings.
RWDBInserter RWDBTable::inserter ( const RWDBSelector selector,
const RWDBSchema columnList 
) const

Produces an RWDBInserter that encapsulates the SQL statement:

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

where <table> is represented by self. 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. This method is equivalent to database.inserter(*this, selector, columnList). If self is not a database table, returns an RWDBInserter with a status of RWDBStatus::noInserter.

RWDBInserter RWDBTable::inserter ( const RWDBCompoundSelector selector,
const RWDBSchema columnList 
) const

Produces an RWDBInserter that encapsulates the SQL statement:

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

where <table> is represented by self. 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. This method is equivalent to database.inserter(*this, selector, columnList). If self is not a database table, returns an RWDBInserter with a status of RWDBStatus::noInserter.

bool RWDBTable::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 RWDBTable::isValid ( ) const

Returns true if the status of self is RWDBStatus::ok, otherwise returns false.

bool RWDBTable::isView ( ) const

Returns true if self represents a database view, otherwise returns false. More specifically:

  • If self is not a database table, returns false.
  • If self is a database table: If the view information was cached in self, returns it. Otherwise, if the view information was previously cached in the cache manager installed on the RWDBDatabase that produced self, returns the view information found in the cache manager. If the view information was not in either the local cache or cache manager, queries the database using an implicit connection, and the view information is returned and also stored in the internal cache and the cache manager, if there is one.
bool RWDBTable::isView ( const RWDBConnection conn) const

Returns true if self represents a database view, otherwise returns false. More specifically:

  • If self is not a database table, returns false.
  • If self is a database table: If the view information was cached in self, returns it. Otherwise, if the view information was previously cached in the cache manager installed on the RWDBDatabase that produced self, returns the view information found in the cache manager. If the information was not in either the local cache or cache manager, queries the database using the supplied database connection conn, and the view information is returned and also stored in the internal cache and the cache manager, if there is one.
RWCString RWDBTable::name ( ) const

Returns self's name. Returns an empty string if self is unnamed.

RWDBTable& RWDBTable::name ( const RWCString name)

Changes the name of self to name. Returns a reference to self.

size_t RWDBTable::numberOfColumns ( ) const

Returns the number of columns in self's schema.

RWDBTable& RWDBTable::operator= ( const RWDBTable table)

Assignment operator. Self shares an implementation with table.

RWDBColumn RWDBTable::operator[] ( const RWCString name) const

Returns a deep copy of the first RWDBColumn in self's schema whose name matches the given name. The RWDBColumn returned is associated with self, that is, the table() method of the returned RWDBColumn returns this table. If no matching column is found, returns a new RWDBColumn instance whose name is set to name and status is RWDBStatus::ok. This is used with RWDBSelector to build up selectors and criteria without requiring an application to fetch the schema of a table. For example:

1 myselector << table["name"]
See also
RWDBSelector
RWDBColumn RWDBTable::operator[] ( size_t  position) const

Returns a deep copy of the RWDBColumn in self's schema at the given position. The RWDBColumn returned is associated with self. If no matching column is found, returns an RWDBColumn whose status is RWDBStatus::columnNotFound. A deep copy is made so that the application can modify the returned RWDBColumn without modifying self's schema.

RWDBPrimaryKey RWDBTable::primaryKey ( const RWDBConnection conn)

Calls RWDBCacheManager::getPrimaryKey() const. If successful, updates self's schema with the return value. Otherwise, uses conn to fetch the primary key associated with self. If successful, updates self's schema with the return value and calls RWDBCacheManager::setPrimaryKey(const RWDBPrimaryKey&). An empty RWDBPrimaryKey indicates there is no primary key associated with self.

Note
This method ensures the schema has already been retrieved before attempting to get the primary key.
RWDBPrimaryKey RWDBTable::primaryKey ( )

Calls RWDBCacheManager::getPrimaryKey() const. If successful, updates self's schema with the return value. Otherwise, uses a default connection to fetch the primary key associated with self. If successful, updates self's schema with the return value and calls RWDBCacheManager::setPrimaryKey(const RWDBPrimaryKey&). An empty RWDBPrimaryKey indicates there is no primary key associated with self. You can check the status of the returned RWDBPrimaryKey to determine whether the operation succeeded with the method RWDBPrimaryKey::status().isValid().

Note
This method ensures the schema has already been retrieved before attempting to get the primary key.
RWDBReader RWDBTable::reader ( size_t  cacheSize = 0) const

Produces an RWDBReader that can be used to read data from self one row at a time. If self is a derived table, the RWDBReader produced reads rows of the result set from execution of the SQL self represents. If self is an RWDBTPtrMemTable, returns an RWDBReader with a status of RWDBStatus::noReader. RWDBTPtrMemTable does not support readers.

Unless self is a memory table, a query is executed using a default database connection, returning a reader for the contents of the table. The reader holds the connection until the reader is destroyed.

Note
Specifying cacheSize as 0 (the default) results in a Rogue Wave-determined acceptable default cache size for a given access module. Specify a positive numeric value to specify your own cache size. The DB Interface Module User Guide includes a discussion of RWDBReader caching. You should also check your Access Module documentation for limitations and warnings.
RWDBReader RWDBTable::reader ( const RWDBConnection connection,
size_t  cacheSize = 0 
) const

Produces an RWDBReader that can be used to read data from self one row at a time. If self is a derived table, the RWDBReader produced reads rows of the result set from execution of the SQL self represents. If self is an RWDBTPtrMemTable, returns an RWDBReader with a status of RWDBStatus::noReader. RWDBTPtrMemTable does not support readers.

Unless self is a memory table, a query is executed using the supplied connection, returning an RWDBReader for the contents of the table. The RWDBReader holds the connection until the RWDBReader is destroyed. This function can behave asynchronously if executed using an asynchronous connection.

Note
Specifying cacheSize as 0 (the default) results in a Rogue Wave-determined acceptable default cache size for a given access module. Specify a positive numeric value to specify your own cache size. The DB Interface Module User Guide includes a discussion of RWDBReader caching. You should also check your Access Module documentation for limitations and warnings.
RWDBStatus RWDBTable::referredToBy ( const RWDBConnection conn,
RWDBForeignKeyList keyList 
)

Calls RWDBCacheManager::getReferredToBy() const. If successful, appends to keyList all foreign keys that refer to self. Otherwise, uses conn to append to keyList all foreign keys that refer to self. If successful, calls RWDBCacheManager::setReferredToBy(const RWDBForeignKeyList&). You can check the return value's isValid() method to determine whether the operation succeeded.

Note
This method ensures the schema has already been retrieved before attempting to get the foreign keys.
RWDBStatus RWDBTable::referredToBy ( RWDBForeignKeyList keyList)

Calls RWDBCacheManager::getReferredToBy() const. If successful, appends to keyList all foreign keys that refer to self. Otherwise, uses a default connection to append to keyList all foreign keys that refer to self. If successful, calls RWDBCacheManager::setReferredToBy(const RWDBForeignKeyList&). You can check the return value's isValid() method to determine whether the operation succeeded.

Note
This method ensures the schema has already been retrieved before attempting to get the foreign keys.
void RWDBTable::release ( void  ) const

Releases a previously acquired mutex. This function can be called from a const object.

Note
In single-threaded builds, this function evaluates to a no-op.
RWDBStatus RWDBTable::revoke ( const RWCString privilege,
const RWCString user 
)

Uses a default database connection to execute the database-specific equivalent of the SQL statement:

1 REVOKE privilege ON <table> FROM user

where <table> is self's table name. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned object is RWDBStatus::noPrivilege.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::revoke ( const RWCString privilege,
const RWCString user,
const RWDBConnection connection 
)

Uses the supplied database connection to execute the database-specific equivalent of the SQL:

1 REVOKE privilege ON <table> FROM user

where <table> is self's table name. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned object is RWDBStatus::noPrivilege. 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 RWDBTable::revoke ( const RWCString privilege,
const RWDBSchema columnList,
const RWCString user 
)

Uses a default database connection to execute the database-specific equivalent of the SQL:

1 REVOKE privilege ON <table> (<column-list>) FROM user

where <table> is self's table name, and <column-list> is a list of column names from self's schema. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned object is RWDBStatus::noPrivilege.

DB XA Module: May generate a server error. This method can still be used before XA connectivity is established.

RWDBStatus RWDBTable::revoke ( const RWCString privilege,
const RWDBSchema columnList,
const RWCString user,
const RWDBConnection connection 
)

Uses the supplied database connection to execute the database-specific equivalent of the SQL:

1 REVOKE privilege ON <table> (<column-list>) FROM user

where <table> is self's table name, and <column-list> is a list of column names from self's schema. The DB Interface Module does not validate the supplied arguments. You can check the return value's isValid() method to see if the operation succeeded. If self is not a database table, the returned object is RWDBStatus::noPrivilege. 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.

RWDBSchema RWDBTable::schema ( ) const

Returns a shallow copy of self's RWDBSchema.

void RWDBTable::setErrorHandler ( RWDBStatus::ErrorHandler  errorHandler)

Installs errorHandler as self's error handler. The supplied handler is inherited by all objects produced by self. By default an RWDBTable error handler is inherited from the object that produced it. This method overwrites the default.

RWDBStatus RWDBTable::status ( ) const

Returns the status of self.

RWCString RWDBTable::tag ( ) const

Returns self's tag. A table's tag is an alias generated by the DB Interface Module for use in SQL queries.

RWDBTable& RWDBTable::tag ( const RWCString newtag)

Set self's tag to newTag. If newTag is empty, self's table name, instead of table tag, is used to qualify columns associated with self in SQL statements. Returns a reference to self.

RWDBStatus RWDBTable::uniqueConstraints ( const RWDBConnection conn,
const RWCString constraintName,
RWDBUniqueConstraintList list 
)

Calls RWDBCacheManager::getUniqueConstraints() const. If successful, appends the unique constraints to list. Otherwise, uses conn connection to append a list of unique constraints to list and, if successful, calls RWDBCacheManager::setUniqueConstraints(const RWDBUniqueConstraintList&). If constraintName is blank, list will contain all of self's unique constraints. If constraintName is not blank, list will contain the unique constraint of self whose name is constraintName. A list without appended elements indicates there are no unique constraints associated with self. You can check the return value's isValid() method to determine whether the operation succeeded.

Note
This method ensures the schema has already been retrieved before attempting to get the unique constraints.
RWDBStatus RWDBTable::uniqueConstraints ( const RWCString constraintName,
RWDBUniqueConstraintList list 
)

Calls RWDBCacheManager::getUniqueConstraints() const. If successful, appends the unique constraints to list. Otherwise, uses a default connection to append a list of unique constraints to list and, if successful, calls RWDBCacheManager::setUniqueConstraints(const RWDBUniqueConstraintList&). If constraintName is blank, list will contain all of self's unique constraints. If constraintName is not blank, list will contain the unique constraint of self whose name is constraintName. A list without appended elements indicates there are no unique constraints associated with self. You can check the return value's isValid() method to determine whether the operation succeeded.

Note
This method ensures the schema has already been retrieved before attempting to get the unique constraints.
RWDBUpdater RWDBTable::updater ( ) const

Produces an RWDBUpdater. The result encapsulates an SQL UPDATE statement to update all rows in self. If self is not a database table, returns an RWDBUpdater whose status is RWDBStatus::noUpdater.

RWDBUpdater RWDBTable::updater ( const RWDBCriterion criterion) const

Produces an RWDBUpdater. The result can be augmented with one or more RWDBAssignment objects in order to create an encapsulated SQL UPDATE statement to update rows in self specified by criterion. If self is not a database table, returns an RWDBUpdater whose status is RWDBStatus::noUpdater.

Friends And Related Function Documentation

RWDBTable::Metadata operator& ( RWDBTable::Metadata  lhs,
RWDBTable::Metadata  rhs 
)
related

Combines the RWDBTable::Metadata lhs with rhs using a bitwise and operation, and returns the result.

RWDBTable::Metadata & operator&= ( RWDBTable::Metadata lhs,
RWDBTable::Metadata  rhs 
)
related

Combines the RWDBTable::Metadata lhs with rhs using a bitwise and operation, stores the result into lhs, and returns reference to lhs.

RWDBTable::Metadata operator^ ( RWDBTable::Metadata  lhs,
RWDBTable::Metadata  rhs 
)
related

Combines the RWDBTable::Metadata lhs with rhs using a bitwise exclusive or operation, and returns the result.

RWDBTable::Metadata & operator^= ( RWDBTable::Metadata lhs,
RWDBTable::Metadata  rhs 
)
related

Combines the RWDBTable::Metadata lhs with rhs using a bitwise exclusive or operation, stores the result into lhs, and returns reference to lhs.

RWDBTable::Metadata operator| ( RWDBTable::Metadata  lhs,
RWDBTable::Metadata  rhs 
)
related

Combines the RWDBTable::Metadata lhs with rhs using a bitwise or operation, and returns the result.

RWDBTable::Metadata & operator|= ( RWDBTable::Metadata lhs,
RWDBTable::Metadata  rhs 
)
related

Combines the RWDBTable::Metadata lhs with rhs using a bitwise or operation, stores the result into lhs, and returns reference to lhs.

RWDBTable::Metadata operator~ ( RWDBTable::Metadata  md)
related

Inverts the value of the RWDBTable::Metadata md using a bitwise not operation, and returns the result.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.