RWDBTable Class Reference
[Databases]

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:

List of all members.

Public Member Functions
	RWDBTable ()
	RWDBTable (const RWDBTable &table)
RWDBTable &	operator= (const RWDBTable &table)
RWDBColumn	column (size_t index) const
RWDBColumn	column (const RWCString &name) const
RWDBColumn	column (const RWCString &name, RWCString::caseCompare caseCompare) const
RWDBColumn	operator[] (const RWCString &name) const
RWDBColumn	operator[] (size_t position) 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
RWDBDatabase	database () const
RWCString	name () const
RWCString	tag () const
RWDBSchema	schema () const
size_t	numberOfColumns () const
RWDBTable &	name (const RWCString &name)
RWDBTable &	tag (const RWCString &newtag)
void	acquire (void) const
void	release (void) const
RWDBSchema	primaryKey (const RWDBConnection &conn)
RWDBSchema	primaryKey ()
RWDBStatus	referredToBy (const RWDBConnection &conn, RWDBForeignKeyList &keyList)
RWDBStatus	referredToBy (RWDBForeignKeyList &keyList)
RWDBStatus	foreignKeys (const RWDBConnection &conn, const RWCString &refName, RWDBForeignKeyList &keyList)
RWDBStatus	foreignKeys (const RWCString &refName, RWDBForeignKeyList &keyList)
bool	exists (bool forceLookup=false)
bool	exists (const RWDBConnection &connection, bool forceLookup=false)
virtual bool	fetchSchema ()
virtual bool	fetchSchema (const RWDBConnection &connection)
bool	isView () const
bool	isView (const RWDBConnection &conn) const
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)
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)
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	dropColumn (const RWDBColumn &column)
RWDBStatus	dropColumn (const RWDBColumn &column, const RWDBConnection &connection)
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)
RWDBStatus	drop ()
RWDBStatus	drop (const RWDBConnection &connection)
RWDBStatus	dropIndex (const RWCString &name)
RWDBStatus	dropIndex (const RWCString &name, const RWDBConnection &connection)
void	setErrorHandler (RWDBStatus::ErrorHandler errorHandler)
RWDBStatus::ErrorHandler	errorHandler () const
bool	isValid () const
bool	isReady () const
RWDBStatus	status () const
RWDBDeleter	deleter () const
RWDBDeleter	deleter (const RWDBCriterion &criterion) const
RWDBUpdater	updater () const
RWDBUpdater	updater (const RWDBCriterion &criterion) 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
RWDBReader	reader (size_t cacheSize=0) const
RWDBReader	reader (const RWDBConnection &connection, size_t cacheSize=0) const
RWDBBulkReader	bulkReader (const RWDBConnection &conn) const
RWDBBulkInserter	bulkInserter (const RWDBConnection &conn) const
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

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:

Database table -- a handle to a table physically stored in the database
Derived table -- representing a SQL query as a table, which can be used in other queries in place of a database table
Result table -- the rows returned as the result of a query
Memory table -- a table stored in program memory

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 = mySelecter.execute();
  //or deleter.execute() or updater.execute() or inserter.execute() or
  //storedProc.execute()
 RWDBTable myResultTable = myResult.table();

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 singlethreaded builds, this function evaluates to a no-op.

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:

 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::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:

 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 RWDBColumn &	column,
		const RWDBConnection &	connection
	)

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

 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 RWDBColumn & column )

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

 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.

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.

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.

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

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:

 CREATE [unique] [clustered] INDEX name
 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.

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:

 CREATE [unique] [clustered] INDEX name
 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.

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:

 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:

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

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:

 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:

 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 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:

 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	(	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:

 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.

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 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:

 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.

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:

 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.

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:

 DROP TABLE <table>

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

 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::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:

 DROP TABLE <table>

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

 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::dropColumn	(	const RWDBColumn &	column,
		const RWDBConnection &	connection
	)

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

 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::dropColumn ( const RWDBColumn & column )

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

 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::dropIndex	(	const RWCString &	name,
		const RWDBConnection &	connection
	)

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

 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 RWDBTable::dropIndex ( const RWCString & name )

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

 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::ErrorHandler RWDBTable::errorHandler ( ) const

Returns the error handler attached to self.

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 for the table's schema. 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, false is returned. Otherwise, self's RWDBSchema is populated with the result of the query and true is returned.

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.

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 for the table's schema. 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, false is returned. Otherwise, self's RWDBSchema is populated with the result of the query, and true is returned.

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.

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.

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.

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

Uses the 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.

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

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.

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:

 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.

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:

 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 RWCString &	user,
		const RWDBConnection &	connection
	)

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

 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 RWCString &	user
	)

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

 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.

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.

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

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

Produces an RWDBInserter that encapsulates the SQL statement:

 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 RWDBSelector &	selector,
		const RWDBSchema &	columnList
	)			const

Produces an RWDBInserter that encapsulates the SQL statement:

 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 RWDBSchema &	columnList,
		size_t	cache = `0`
	)			const

Produces an RWDBInserter that encapsulates the SQL statement:

 INSERT INTO <table> (col1, ..., coln)
 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 RWDBCompoundSelector & selector ) const

Produces an RWDBInserter that encapsulates the SQL statement:

 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 RWDBSelector & selector ) const

Produces an RWDBInserter that encapsulates the SQL statement:

 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 ( size_t cache = 0 ) const

Produces an RWDBInserter that encapsulates the SQL statement:

 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.

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 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, then:
- if exists( conn ) returns false, returns false.
- if exists( conn ) returns true, and self is a database view, returns true, otherwise 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, then:
- if exists() returns false, returns false.
- if exists() returns true, and self is a database view, returns true, otherwise false.

RWDBTable& RWDBTable::name ( const RWCString & name )

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

RWCString RWDBTable::name ( ) const

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

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[] ( 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.

Reimplemented in RWDBMemTable.

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 an RWDBColumn whose 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:

 myselector << table["name"]

See also:: RWDBSelector

Reimplemented in RWDBMemTable.

RWDBSchema RWDBTable::primaryKey ( )

Uses the default connection to fetch the primary key associated with self. Returns the primary key as an RWDBSchema. Updates self's schema with the return value.

RWDBSchema RWDBTable::primaryKey ( const RWDBConnection & conn )

Uses conn to fetch the primary key associated with self. Returns the primary key as an RWDBSchema. Updates self's schema with the return value.

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.

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.

RWDBStatus RWDBTable::referredToBy ( RWDBForeignKeyList & keyList )

Uses the default connection to append to keyList all foreign keys that refer to self. You can check the return value's isValid() method to determine whether the operation succeeded.

RWDBStatus RWDBTable::referredToBy	(	const RWDBConnection &	conn,
		RWDBForeignKeyList &	keyList
	)

Uses conn to append to keyList all foreign keys that refer to self. You can check the return value's isValid() method to determine whether the operation succeeded.

void RWDBTable::release ( void ) const

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

Note:: In singlethreaded builds, this function evaluates to a no-op.

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:

 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.

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:

 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 RWCString &	user,
		const RWDBConnection &	connection
	)

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

 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 RWCString &	user
	)

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

 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.

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.

RWDBTable& RWDBTable::tag ( const RWCString & newtag )

Set self's tag to newTag. If newTag is empty, self's table name, instead of table tag, will be used to qualify columns associated with self in SQL statements. Returns a reference to 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.

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.

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.

SourcePro® C++ API Reference Guide

RWDBTable Class Reference [Databases]

Public Member Functions

Detailed Description

Synopsis

Constructor & Destructor Documentation

Member Function Documentation

RWDBTable Class Reference
[Databases]