IliSQLTable Class Reference

Table class. More...

#include <ilviews/dataccess/sqltable.h>

Inheritance diagram for IliSQLTable:

Public Member Functions
	IliSQLTable (IlvDisplay *, IL_STDPREF istream &input)
	This constructor initializes an SQL table by reading its definition from an input stream.
	IliSQLTable (const IliSQLTable &)
	This is the copy constructor of the `IliSQLTable` class.
	IliSQLTable (IlvDisplay *display)
	This constructor initializes an SQL table.
IlInt	addJoin (IlInt tblNo1, const char colName1, IlInt tblNo2, const char colName2)
	Adds a join.
IlInt	addJoin (IlInt tblNo1, const IliAttributePath &colName1, IlInt tblNo2, const IliAttributePath &colName2)
	Adds a join.
IlInt	addTable (const IliSQLTableRef &tblRef)
	Adds a table reference to the "from" clause of the query.
IlInt	addTableColumn (const IliSQLTableDef *tblDef, IlInt tblno, IlInt colno)
	Appends a new column.
virtual IlBoolean	allowColumnMove () const
	Returns `IlTrue` if columns can be moved to this schema.
virtual IlBoolean	applyQueryMode (IliTable *queryTable)
	Applies the query specified by the conditions contained in the provided table.
IlBoolean	cancelAsyncCall ()
	Cancels all the asynchronous calls that are not completed.
virtual void	clearRows ()
	Deletes all rows.
IlBoolean	continueAsyncCall ()
	If there is an asynchronous call in progress, this member function again calls the asynchronous-enabled member function that is not completed.
void	deleteConjunct (IlInt cno, IlBoolean wherePart)
	Deletes a conjunct.
void	deleteJoin (IlInt jno)
	Deletes a join.
virtual IlBoolean	deleteRow (IlInt r)
	Deletes a row.
void	enableNoWaitOnLockRow (IlBoolean nowait)
	Specifies whether "waiting on row locking" is enabled.
virtual IlBoolean	exchangeRows (IlInt rowno1, IlInt rowno2)
	Exchanges two rows.
virtual IlInt	fetchAll ()
	Fetches all remaining rows and stores them in the local row cache.
virtual IlBoolean	fetchCompleted () const
	Returns `IlTrue`, if all the rows have been fetched from the database and stored in the local row cache.
virtual IlInt	fetchNext (IlInt cnt=1)
	Fetches up a number of rows from the database and stores them in the local row cache.
IlInt	findJoin (IlInt tblNo1, const IliAttributePath &colName1, IlInt tblNo2, const IliAttributePath &colName2) const
	Returns the position of the join which corresponds to the definition.
IlBoolean	getAutoCommit () const
	Returns `IlTrue` if the SQL table is in auto-commit mode.
IlBoolean	getAutoRefresh () const
	Returns `IlTrue` if the SQL table is in auto-refresh mode.
IliTable *	getCache () const
	Returns the `IliTable` that manages the local row cache.
IliSQLCatalog &	getCatalog ()
	Returns the catalog of the SQL table.
const IliSQLCatalog &	getCatalog () const
	Returns the catalog of the SQL table.
IlInt	getColumnDesignWidth (IlInt colno) const
	Returns the design width, in pixels, of the column.
IliSQLOperation	getColumnOperation (IlInt colno) const
	Returns the operation requested for the column.
IliSQLOrderByType	getColumnOrderBy (IlInt colno) const
	Returns the order requested for the column.
const char *	getColumnPredicat (IlInt colno, IlInt cno, IlBoolean wherePart) const
	Returns the predicate for the column in the conjunct.
const char *	getColumnSQLText (IlInt colno) const
	Returns the text of the SQL expression used to retrieve the column.
IlInt	getColumnTable (IlInt colno) const
	Returns the position of the table reference that the column is mapped to.
IlBoolean	getConcurrencyControl () const
	Returns `IlTrue` if concurrency control is enabled for the SQL table.
IlInt	getConjunctsCount (IlBoolean wherePart) const
	Returns the number of conjuncts defined for the SQL table.
IlInt	getCursorBufferedRowsCount () const
	Returns the number of buffered rows.
IliSQLSession *	getEffectiveSQLSession () const
	Returns the effective SQL session object of the table.
IliFetchPolicy	getFetchPolicy () const
	Returns the fetch policy of the SQL table.
IlBoolean	getJoin (IlInt jno, IlInt &tblNo1, IliAttributePath &colName1, IlInt &tblNo2, IliAttributePath &colName2) const
	Returns the definition of the join.
IlInt	getJoinIndex (IlInt token) const
	Returns the position of a join.
IlInt	getJoinsCount () const
	Returns the number of joins that have been defined for the SQL table.
IlInt	getJoinToken (IlInt jno) const
	Returns the token of the join.
IliSQLJoinType	getJoinType (IlInt jno) const
	Returns the type of the join.
const char *	getQuery () const
	Returns the `SQL SELECT` statement that will be used to query the database.
const char *	getQueryConjunct () const
	Returns the condition that will be combined with the query defined on the SQL table, to derive the effective query that will be submitted to the remote database.
virtual IlInt	getRowsCount () const
	Returns the number of rows in the table.
IlInt	getRowsCountLimit () const
	Returns the maximum number of rows that can be stored in the local memory cache.
IliSQLSession *	getSQLSession () const
	Returns the SQL session object of the table.
const char *	getTableAlias (IlInt tblno) const
	Returns the alias of one table.
IlInt	getTableIndex (IlInt token) const
	Returns the index of the table reference.
IlInt	getTableIndex (const char *alias) const
	Returns the position of the table reference.
const char *	getTableParentDataSourceName (IlInt tblno) const
	Returns the name of the parent data source for the table.
IliAttributePath	getTableParentPath (IlInt tblno) const
	Returns the path to the nested table for the table.
IliRowPtr	getTableParentRow (IlInt tblno) const
	Returns the parent row for the table.
IliSQLTable *	getTableParentSQLTable (IlInt tblno) const
	Returns the parent SQL table for the table.
const char *	getTableParentTableAlias (IlInt tblno) const
	Returns the alias of the database table that identifies the parent row.
IlInt	getTableParentTableIndex (IlInt tblno) const
	Returns the index of the database table that identifies the parent row.
IlvRect	getTableRect (IlInt tblno) const
	Returns the rectangle of the table reference.
const IliSQLTableRef &	getTableRef (IlInt tblno) const
	Returns a table reference.
IlInt	getTablesCount () const
	Returns the number of tables in the "from" clause of the query.
IlInt	getTableToken (IlInt tblno) const
	Returns the token of the table reference.
virtual IlBoolean	getValue (IlInt r, IlInt c, IliValue &) const
	Returns a value.
void	insertConjunct (IlInt cno, IlBoolean wherePart)
	Adds a new conjunct.
void	insertNulls (IlBoolean f)
	Sets the insert-nulls mode for the SQL table.
virtual IlBoolean	insertRow (IlInt r, IliTableBuffer *)
	Inserts a row that is defined by the table buffer.
IlBoolean	isAsyncCallCompleted () const
	Returns `IlTrue` if the last call to one of the asynchronous-enabled member functions (`select`, `fetchNext`, and `fetchAll`) has completed.
IlBoolean	isColumnFetched (IlInt colno) const
	Returns `IlTrue` if the column should be part of the result computed by the query.
IlBoolean	isDistinct () const
	Returns `IlTrue` if the duplicate rows should be removed from the query result.
IlBoolean	isInAsyncMode () const
	Returns `IlTrue` if the SQL table is in asynchronous mode.
IlBoolean	isInsertingNulls () const
	Returns `IlTrue` if the SQL table includes any `NULL` columns when it constructs the INSERT SQL statement required to insert a row into a database.
IlBoolean	isNoWaitOnLockRowEnabled () const
	The return value from this member function is only meaningful when the SQL session connects to an Oracle database server.
IlBoolean	isNoWaitOnLockRowSupported () const
	Returns `IlTrue` if the `enableNoWaitOnLockRow` member function is in effect.
virtual IlBoolean	isQueryModeSupported () const
	Returns `IlTrue` if the table supports query mode.
virtual IlBoolean	isSelectDone () const
	Returns `IlTrue` if the `select` member function has been called since the object was constructed.
IlBoolean	isTableUpdatable (IlInt tblno) const
	Returns `IlTrue` if the table referenced at position `tblno` can be updated through this SQL table object.
IlBoolean	isUsingBoundVariables () const
	Returns `IlTrue` if the bind-vars mode of the SQL table is enabled.
IlBoolean	isUsingDynamicSQL () const
	Returns `IlTrue` if the SQL table is in dynamic-SQL mode.
IlBoolean	makeQuery ()
	Causes the SQL table to compute the `SQL SELECT` statement that will be used to query the database.
virtual IliTable *	makeQueryTable () const
	Returns a memory table having the same number of columns as this table.
virtual IlBoolean	moveRow (IlInt from, IlInt to)
	Moves a row.
virtual IlBoolean	refreshAndLockRow (IlInt rowno)
	Re-reads the row from the remote database.
virtual IlBoolean	refreshRow (IlInt rowno)
	Re-reads the row from the remote database.
IlBoolean	removeTable (IlInt tblno)
	Removes a table reference.
virtual IlBoolean	select ()
	Reads all rows from a remote database.
void	setAutoCommit (IlBoolean f)
	Sets the auto-commit mode for the SQL table.
void	setAutoRefresh (IlBoolean f)
	Sets the auto-refresh mode for the SQL table.
void	setCache (IliTable *cache)
	Sets the `IliTable` used by the `IliSQLTable` to manage the local row cache.
void	setColumnDesignWidth (IlInt colno, IlInt width)
	Sets the design width of the column.
virtual void	setColumnFetched (IlInt colno, IlBoolean f)
	Sets the fetched property of the column.
virtual void	setColumnOperation (IlInt colno, IliSQLOperation op)
	Sets the operation requested for the column.
virtual void	setColumnOrderBy (IlInt colno, IliSQLOrderByType order)
	Sets the order requested for the column.
void	setColumnPredicat (IlInt colno, IlInt cno, const char *predicat, IlBoolean wherePart)
	Sets the predicate of the column in the conjunct.
virtual void	setColumnSQLText (IlInt colno, const char *text)
	Sets the SQL text of the column.
virtual void	setColumnTable (IlInt colno, IlInt tblno)
	Sets the table reference onto which the column should be mapped.
void	setConcurrencyControl (IlBoolean cc)
	Enables/disables concurrency control for the SQL table.
void	setCursorBufferedRowsCount (IlInt count)
	Sets the number of buffered rows to count.
void	setDistinct (IlBoolean f)
	Sets the distinct property of the SQL table.
void	setFetchPolicy (IliFetchPolicy fp)
	Sets the fetch policy of the SQL table.
void	setJoinType (IlInt jno, IliSQLJoinType type)
	Sets the type of the join.
void	setQuery (const char *query)
	Sets the query on the SQL table.
void	setQueryConjunct (const char *condition)
	Sets the condition that will be combined with the query defined on the SQL table, to derive the effective query that will be submitted to the remote database.
IlBoolean	setQueryFrom (const IliSQLTableRef &tblRef)
	Defines the SQL table in such a way that it will map onto the database table indicated.
void	setRowsCountLimit (IlInt size)
	Sets the rows count limit of the SQL table.
void	setSQLSession (IliSQLSession *session)
	Sets the SQL session object of the table.
void	setTableParentDataSourceName (IlInt tblno, const char *name)
	Sets the name of the parent data source for the table.
void	setTableParentPath (IlInt tblno, const IliAttributePath &path)
	Sets the path to the nested table for the table.
void	setTableParentRow (IlInt tblno, const IliRowPtr &row)
	Sets the parent row for the table.
void	setTableParentSQLTable (IlInt tblno, IliSQLTable *sqlTbl)
	Sets the parent SQL table for the table.
void	setTableParentTableAlias (IlInt tblno, const char *name)
	Sets the alias of the database table that identifies the parent row.
void	setTableRect (IlInt tblno, const IlvRect &rect)
	Sets the rectangle of the table reference.
void	setTableRef (IlInt tblno, const IliSQLTableRef &tblRef)
	Replaces a table reference.
void	setTableUpdatable (IlInt tblno, IlBoolean flag)
	Changes the updatable property of the table reference.
virtual IlBoolean	updateRow (IlInt r, IliTableBuffer *)
	Updates a row with the values in the table buffer.
void	useBoundVariables (IlBoolean f)
	Sets the bind-vars mode of the SQL table.
void	useDynamicSQL (IlBoolean f)
	Sets the dynamic-SQL mode for the SQL table.
virtual void	write (IL_STDPREF ostream &output) const
	Writes the definition of the SQL table to an output stream, in a form suitable to be read back by the stream-based constructor.

Detailed Description

Table class.

Library: dbaccess

The IliSQLTable class implements the protocol defined by the IliTable class, by managing the rows on a remote relational database management system. It is defined in terms of an SQL query that calculates a new table from existing database tables.

The SQL query of an IliSQLTable can be defined in two different ways:

literally, by calling the setQuery member function,
or structurally, by calling the member functions described in the "Definition" section below.

When the SQL query is defined literally, the IliSQLTable can only be used to read the results of the query evaluation. This differs from defining the query structurally: while the IliSQLTable is not just used to read values from the database, it can also be used to update the database. Rogue Wave Views Data Access provides an inspector that allows the structural definition of an IliSQLTable, through a graphical user interface that is more convenient than having to code this definition by calling member functions.

About Table Parent The member functions in this section are needed when one of the tables in the FROM clause has a nested table (that is, it has a column whose type is a table) and columns in this nested table are selected.

Suppose a table named PRODUCT has a column PARTS of type TABLE OF PART.

 CREATE TYPE PART AS OBJECT(
        PARTNAME VARCHAR,
        WEIGHT   INTEGER);

 CREATE TABLE PRODUCT(
         PRODNAME VARCHAR PRIMARY KEY
         PARTS    TABLE OF PART);

Suppose an IliSQLTable selects columns PARTNAME from table PRODUCT.PARTS. Since there are as many PARTS tables as there are rows in table PRODUCT, the SQL table needs to know in which row of table PRODUCT it must look for a PARTS table.

Parent Data Source The setTableParentDataSourceName member function lets you specify a data source that is expected to be positioned on a given row in table PRODUCTS. This data source is expected to hold an IliSQLTable that selects at least the primary key columns of table PRODUCT.

Parent SQL Table and Row Index Alternatively, the setTableParentSQLTable and the setTableParentRow member functions can be used to specify the parent SQL table and the row that contains the nested table. These member functions must be called before the select member function is called because the SQL SELECT statement may be dependent upon both of these properties.

Parent Table Alias Since the parent SQL table may have more than one table in its FROM clause, it is necessary to specify which of these tables identifies the row in table PRODUCT. The setParentTableAlias member function can be used for this purpose.

If the SQL table session has been set up through an SQL data source inspector and if an application-wide session has been selected, then the getEffectiveSQLSession member function will return the application-wide session.

About Asynchronous Mode If the SQL session of the SQL table is in asynchronous mode, the SQL table will operate in asynchronous mode.

Asynchronous-disabled member functions- In this mode, the following member functions will fail with an Ili_SQLSessionInAsyncMode error code: insertRow, updateRow, deleteRow, refreshRow, and refreshAndLockRow.
Asynchronous-enabled member functions- The following member functions will operate differently in asynchronous mode than in synchronous mode: select, fetchNext, and fetchAll.

See also:: IliSQLSession, IliSQLTableRef, IliFetchPolicy, IliSQLOperation, IliSQLOrderByType, IliSQLJoinType.

Constructor & Destructor Documentation

IliSQLTable::IliSQLTable ( IlvDisplay * display )

This constructor initializes an SQL table.

Initially, the table definition is empty.

Parameters:

display

The display.

IliSQLTable::IliSQLTable	(	IlvDisplay *	,
		IL_STDPREF istream &	input
	)

This constructor initializes an SQL table by reading its definition from an input stream.

Parameters:

input

The input stream.

Member Function Documentation

IlInt IliSQLTable::addJoin	(	IlInt	tblNo1,
		const char *	colName1,
		IlInt	tblNo2,
		const char *	colName2
	)

Adds a join.

Parameters:

	tblNo1	The table position of the first table.
	colName1	The column name of the first table.
	tblNo2	The table position of the second table.
	colName2	The column name of the second table.

Returns:: The position of the join.

IlInt IliSQLTable::addJoin	(	IlInt	tblNo1,
		const IliAttributePath &	colName1,
		IlInt	tblNo2,
		const IliAttributePath &	colName2
	)

Adds a join.

Parameters:

	tblNo1	The table position of the first table.
	colName1	The column name of the first table.
	tblNo2	The table position of the second table.
	colName2	The column name of the second table.

Returns:: The position of the join.

IlInt IliSQLTable::addTable ( const IliSQLTableRef & tblRef )

Adds a table reference to the "from" clause of the query.

Note that the same table reference can be added many times in a query. Each occurrence of that same table reference will be distinguished by a unique alias. Furthermore, each table referenced in an SQL table is automatically given a token (an integer), which is unique and will always remain constant (as opposed to the position or index of a table reference, which may change without notice, when other table references are removed).

Parameters:

tblRef

The table.

Returns:: The position of this table reference in the ordered set of table references.

IlInt IliSQLTable::addTableColumn	(	const IliSQLTableDef *	tblDef,
		IlInt	tblno,
		IlInt	colno
	)

Appends a new column.

Calling this member function is similar to adding a column to an SQL data source in an Rogue Wave Views Studio inspector by dragging the column from a database table and dropping it over the SELECT area of the data source.

Parameters:

	tblDef	The table definition.
	tblno	The table position in the table definition.
	colno	The column position in the table definition.

Returns:: The index of the newly created column or -1 if the column creation fails.

virtual IlBoolean IliSQLTable::allowColumnMove ( ) const [virtual]

Returns IlTrue if columns can be moved to this schema.

The reason why columns can or cannot be moved depends on the specific subclass of IliSchema that is used.

Returns:: IlTrue if columns can be moved to this schema, and IlFalse otherwise.

Reimplemented from IliMemoryTable.

virtual IlBoolean IliSQLTable::applyQueryMode ( IliTable * queryTable ) [virtual]

Applies the query specified by the conditions contained in the provided table.

If query mode is supported, applies the query specified by the conditions contained in the queryTable parameter, which is expected to be a table obtained by calling the makeQueryTable virtual member function.

Parameters:

queryTable

The table.

Returns:: IlTrue if successful.

Reimplemented from IliTable.

IlBoolean IliSQLTable::cancelAsyncCall ( )

Cancels all the asynchronous calls that are not completed.

Returns:: IlTrue if successful.

virtual void IliSQLTable::clearRows ( ) [virtual]

Deletes all rows.

If the table (or subclass of the table) defines a mapping with a remote database, then only the rows in the IliTable object are deleted. The rows in the remote database are not affected by this operation. This enables the row cache of such a table to be cleared.

Reimplemented from IliMemoryTable.

IlBoolean IliSQLTable::continueAsyncCall ( )

If there is an asynchronous call in progress, this member function again calls the asynchronous-enabled member function that is not completed.

The isAsyncCallCompleted can then be called to check whether the call has been completed.

Returns:: IlTrue if the call is successful and IlFalse otherwise.

void IliSQLTable::deleteConjunct	(	IlInt	cno,
		IlBoolean	wherePart
	)

Deletes a conjunct.

Parameters:

	cno	The conjunct position.
	wherePart	If `IlTrue`, deletes to the `WHERE` clause. If `wherePart` is `IlFalse`, the conjunct is deleted to the `HAVING` clause.

void IliSQLTable::deleteJoin ( IlInt jno )

Deletes a join.

Parameters:

jno

The join position.

virtual IlBoolean IliSQLTable::deleteRow ( IlInt rowno ) [virtual]

Deletes a row.

Parameters:

rowno

The row position.

Returns:: IlTrue if successful and IlFalse if rowno is out of bounds, or if the row could not be deleted. If the table (or subclass of the table) defines a mapping with a remote database, the row is also deleted in the remote database.

Reimplemented from IliMemoryTable.

void IliSQLTable::enableNoWaitOnLockRow ( IlBoolean nowait )

Specifies whether "waiting on row locking" is enabled.

The only database system that supports this feature is Oracle. With other database systems, calling this member function has no effect.

Parameters:

nowait If IlTrue, "waiting on row locking" is enabled.

virtual IlBoolean IliSQLTable::exchangeRows	(	IlInt	rowno1,
		IlInt	rowno2
	)			`[virtual]`

Exchanges two rows.

Parameters:

	rowno1	The first row position.
	rowno2	The second row position.

Returns:: IlTrue if successful. If the table (or subclass of the table) defines a mapping with a remote database, the rows are also exchanged in the remote database (if possible).

Reimplemented from IliMemoryTable.

virtual IlInt IliSQLTable::fetchAll ( ) [virtual]

Fetches all remaining rows and stores them in the local row cache.

Returns:: The number of rows effectively fetched.

Reimplemented from IliTable.

virtual IlBoolean IliSQLTable::fetchCompleted ( ) const [virtual]

Returns IlTrue, if all the rows have been fetched from the database and stored in the local row cache.

The table (or subclass of the table) must define a mapping with a database.

Returns:: IlTrue, if all the rows have been fetched from the database and stored in the local row cache.

Reimplemented from IliTable.

virtual IlInt IliSQLTable::fetchNext ( IlInt count = 1 ) [virtual]

Fetches up a number of rows from the database and stores them in the local row cache.

Parameters:

count

The row count.

Returns:: The number of rows effectively fetched.

Reimplemented from IliTable.

IlInt IliSQLTable::findJoin	(	IlInt	tblNo1,
		const IliAttributePath &	colName1,
		IlInt	tblNo2,
		const IliAttributePath &	colName2
	)			const

Returns the position of the join which corresponds to the definition.

Parameters:

	tblNo1	The table position of the first table.
	colName1	The column name of the first table.
	tblNo2	The table position of the second table.
	colName2	The column name of the second table.

Returns:: The position of the join whose definition or -1 if there is no such join. Note that this member function considers joins to be symmetric, so the order of the table references does not matter.

IlBoolean IliSQLTable::getAutoCommit ( ) const

Returns IlTrue if the SQL table is in auto-commit mode.

In this mode, the SQL table commits the transaction immediately after any INSERT, UPDATE, or DELETE operations. When auto-commit is disabled, the user must commit the transaction (through the effective SQL session), as required. Initially, this property is set to IlTrue.

Returns:: IlTrue if the SQL table is in auto-commit mode.

IlBoolean IliSQLTable::getAutoRefresh ( ) const

Returns IlTrue if the SQL table is in auto-refresh mode.

In this mode, any INSERT or UPDATE operation on the database is immediately followed by a request, to the database, for the inserted or updated row. The row obtained by this request replaces the inserted or updated row, in the SQL table. This is sometimes useful when the database contains triggers which may alter inserted or modified rows. Initially, this property is set to IlFalse.

Returns:: IlTrue if the SQL table is in auto-refresh mode.

IliTable* IliSQLTable::getCache ( ) const

Returns the IliTable that manages the local row cache.

Initially, this property is NULL.

Returns:: The IliTable that manages the local row cache or NULL if the cache is managed by the IliSQLTable itself (through the IliMemoryTable class from which it inherits).

IliSQLCatalog& IliSQLTable::getCatalog ( )

Returns the catalog of the SQL table.

A catalog is a set of database table definitions.

Returns:: The catalog of the SQL table.

const IliSQLCatalog& IliSQLTable::getCatalog ( ) const

Returns the catalog of the SQL table.

A catalog is a set of database table definitions.

Returns:: The catalog of the SQL table.

IlInt IliSQLTable::getColumnDesignWidth ( IlInt colno ) const

Returns the design width, in pixels, of the column.

Parameters:

colno

The column position.

Returns:: The design width, in pixels, of the column. This is the width of the column when it is shown in an IliSQLTable inspector.

IliSQLOperation IliSQLTable::getColumnOperation ( IlInt colno ) const

Returns the operation requested for the column.

Parameters:

colno

The column position.

Returns:: The operation requested for the column. The return value may be one of the following: IliSQLScalar, IliSQLGroupBy, IliSQLCount, IliSQLSum, IliSQLAvg, IliSQLMin, or IliSQLMax. The default is IliSQLScalar.

IliSQLOrderByType IliSQLTable::getColumnOrderBy ( IlInt colno ) const

Returns the order requested for the column.

Parameters:

colno

The column position.

Returns:: The order requested for the column. The return value may be one of the following, IliSQLNoOrder, IliSQLAscending or IliSQLDescending. The default is IliSQLNoOrder.

const char* IliSQLTable::getColumnPredicat	(	IlInt	colno,
		IlInt	cno,
		IlBoolean	wherePart
	)			const

Returns the predicate for the column in the conjunct.

Parameters:

	colno	The column position.
	cno	The conjunct position.
	wherePart	If `IlTrue`, from the `WHERE` clause, otherwise from the `HAVING` clause.

Returns:: The predicate for the column.

const char* IliSQLTable::getColumnSQLText ( IlInt colno ) const

Returns the text of the SQL expression used to retrieve the column.

If this column is mapped onto a column of a database table, the SQL text will be the name of the database table column. If the column is defined as being computed, the SQL text will be the expression that computes the column.

Parameters:

colno

The column position.

Returns:: The text of the SQL expression used to retrieve the column.

IlInt IliSQLTable::getColumnTable ( IlInt colno ) const

Returns the position of the table reference that the column is mapped to.

The default is -1.

Parameters:

colno

The column position.

Returns:: The position of the table reference that the column is mapped to, or -1 if this column is not directly mapped onto a table column.

IlBoolean IliSQLTable::getConcurrencyControl ( ) const

Returns IlTrue if concurrency control is enabled for the SQL table.

When concurrency control is enabled, the updating and deletion of rows in this SQL table will only succeed if the rows concerned have not changed in the database since the last time they were fetched and stored in the local memory cache. In other words, concurrency control obliges the SQL table to protect the work carried out through it from the work of other users on the database. Initially, this property is set to IlFalse.

Returns:: IlTrue if concurrency control is enabled for the SQL table.

IlInt IliSQLTable::getConjunctsCount ( IlBoolean wherePart ) const

Returns the number of conjuncts defined for the SQL table.

Parameters:

wherePart If IlTrue, the conjuncts that constitute the WHERE clause are counted, whereas, if it is IlFalse, the conjuncts that constitute the HAVING clause are counted.

Returns:: The number of conjuncts defined for the SQL table.

IlInt IliSQLTable::getCursorBufferedRowsCount ( ) const

Returns the number of buffered rows.

Returns:: The number of buffered rows. The value of this property is forwarded to any underlying SQL cursor used to select and fetch the result set of the SQL table (by calling its setBufferedRowsCount member function). Note that this property bears no relationship to the local row cache of the SQL table. It refers to a lower-level buffering mechanism.

IliSQLSession* IliSQLTable::getEffectiveSQLSession ( ) const

Returns the effective SQL session object of the table.

This is not necessarily the same as the SQL session object returned by the getSQLSession member function. In any case, all communication between the SQL table and a remote database system goes through the effective SQL session object.

Returns:: The effective SQL session object of the table.

IliFetchPolicy IliSQLTable::getFetchPolicy ( ) const

Returns the fetch policy of the SQL table.

The default for this property is IliFP_AsNeeded.

Returns:: The fetch policy of the SQL table.

IlBoolean IliSQLTable::getJoin	(	IlInt	jno,
		IlInt &	tblNo1,
		IliAttributePath &	colName1,
		IlInt &	tblNo2,
		IliAttributePath &	colName2
	)			const

Returns the definition of the join.

Parameters:

	jno	The join position.
	tblNo1	The table position of the first table.
	colName1	The column name of the first table.
	tblNo2	The table position of the second table.
	colName2	The column name of the second table.

Returns:: IlTrue if successful.

IlInt IliSQLTable::getJoinIndex ( IlInt token ) const

Returns the position of a join.

Parameters:

token

The join token.

Returns:: The position of a join or -1 if no such join exists.

IlInt IliSQLTable::getJoinsCount ( ) const

Returns the number of joins that have been defined for the SQL table.

Returns:: The number of joins that have been defined for the SQL table.

IlInt IliSQLTable::getJoinToken ( IlInt jno ) const

Returns the token of the join.

Tokens are automatically assigned to joins, and will always remain constant (as opposed to the position of a join, which may change without notice when other joins are removed).

Parameters:

jno

The join position.

Returns:: The token of the join or -1 if no such join exists.

IliSQLJoinType IliSQLTable::getJoinType ( IlInt jno ) const

Returns the type of the join.

Parameters:

jno

The join position.

Returns:: The type of the join.

const char* IliSQLTable::getQuery ( ) const

Returns the SQL SELECT statement that will be used to query the database.

Returns:: The SQL SELECT statement that will be used to query the database.

const char* IliSQLTable::getQueryConjunct ( ) const

Returns the condition that will be combined with the query defined on the SQL table, to derive the effective query that will be submitted to the remote database.

Returns:: The condition that will be combined with the query defined on the SQL table, to derive the effective query that will be submitted to the remote database. This condition is combined with the WHERE part of the query, and with an AND Boolean operator. Initially, this property is set to the empty character string.

virtual IlInt IliSQLTable::getRowsCount ( ) const [virtual]

Returns the number of rows in the table.

Returns:: The count.

Reimplemented from IliMemoryTable.

IlInt IliSQLTable::getRowsCountLimit ( ) const

Returns the maximum number of rows that can be stored in the local memory cache.

When this limit is reached, no more rows will be fetched from the database, and no insert operations will be allowed for the IliSQLTable. A value of -1 means that there is no limit. Initially, this property is set to 500.

Returns:: The maximum number of rows that can be stored in the local memory cache.

IliSQLSession* IliSQLTable::getSQLSession ( ) const

Returns the SQL session object of the table.

Returns:: The SQL session object of the table.

const char* IliSQLTable::getTableAlias ( IlInt tblno ) const

Returns the alias of one table.

Parameters:

tblno

The table reference position.

Returns:: The alias.

IlInt IliSQLTable::getTableIndex ( IlInt token ) const

Returns the index of the table reference.

Parameters:

token

The table reference token.

Returns:: The index of the table reference or -1 if no such table reference exists.

IlInt IliSQLTable::getTableIndex ( const char * alias ) const

Returns the position of the table reference.

Parameters:

alias

The table reference alias.

Returns:: The position of the table reference or -1 if no such table reference exists.

const char* IliSQLTable::getTableParentDataSourceName ( IlInt tblno ) const

Returns the name of the parent data source for the table.

Parameters:

tblno

The table reference position.

Returns:: The name of the parent data source for the table.

IliAttributePath IliSQLTable::getTableParentPath ( IlInt tblno ) const

Returns the path to the nested table for the table.

Parameters:

tblno

The table reference position.

Returns:: The path to the nested table for the table.

IliRowPtr IliSQLTable::getTableParentRow ( IlInt tblno ) const

Returns the parent row for the table.

Parameters:

tblno

The table reference position.

Returns:: The parent row for the table.

IliSQLTable* IliSQLTable::getTableParentSQLTable ( IlInt tblno ) const

Returns the parent SQL table for the table.

Parameters:

tblno

The table reference position.

Returns:: The parent SQL table for the table.

const char* IliSQLTable::getTableParentTableAlias ( IlInt tblno ) const

Returns the alias of the database table that identifies the parent row.

Parameters:

tblno

The table reference position.

Returns:: The alias of the database table that identifies the parent row.

IlInt IliSQLTable::getTableParentTableIndex ( IlInt tblno ) const

Returns the index of the database table that identifies the parent row.

This index is relative to the FROM clause of the parent SQL table.

Parameters:

tblno

The table reference position.

Returns:: The index of the database table that identifies the parent row.

IlvRect IliSQLTable::getTableRect ( IlInt tblno ) const

Returns the rectangle of the table reference.

This rectangle is only used at design time by the IliSQLTable inspector.

Parameters:

tblno

The table reference position.

Returns:: The rectangle of the table reference.

const IliSQLTableRef& IliSQLTable::getTableRef ( IlInt tblno ) const

Returns a table reference.

Parameters:

tblno

The table reference position.

Returns:: The table reference.

IlInt IliSQLTable::getTablesCount ( ) const

Returns the number of tables in the "from" clause of the query.

Returns:: The count.

IlInt IliSQLTable::getTableToken ( IlInt tblno ) const

Returns the token of the table reference.

Parameters:

tblno

The table reference position.

Returns:: The token of the table reference.

virtual IlBoolean IliSQLTable::getValue	(	IlInt	rowno,
		IlInt	colno,
		IliValue &	value
	)			const `[virtual]`

Returns a value.

This member function handles the fetching of the row (and all preceding rows) as necessary.

Parameters:

	rowno	The row position.
	colno	The column position.
	value	The value.

Returns:: IlTrue if successful.

Reimplemented from IliMemoryTable.

void IliSQLTable::insertConjunct	(	IlInt	cno,
		IlBoolean	wherePart
	)

Adds a new conjunct.

Parameters:

	cno	The conjunct position.
	wherePart	If `IlTrue`, adds to the `WHERE` clause. If `wherePart` is `IlFalse`, the conjunct is added to the `HAVING` clause.

void IliSQLTable::insertNulls ( IlBoolean f )

Sets the insert-nulls mode for the SQL table.

Parameters:

f If IlTrue, the insert-nulls mode is on.

virtual IlBoolean IliSQLTable::insertRow	(	IlInt	rowno,
		IliTableBuffer *	buff
	)			`[virtual]`

Inserts a row that is defined by the table buffer.

Not all the values are used to insert the row, instead the values for which the isModified are used, the others being replaced by null values. Note that this member function does not check any of the constraints defined in the schema. If the table (or subclass of the table) defines a mapping with a remote database, the row is also inserted in the remote database.

Parameters:

	rowno	The row position.
	buff	The table buffer.

Returns:: IlTrue if successful, and IlFalse if rowno is out of bounds, or if the row could not be inserted.

Reimplemented from IliMemoryTable.

IlBoolean IliSQLTable::isAsyncCallCompleted ( ) const

Returns IlTrue if the last call to one of the asynchronous-enabled member functions (select, fetchNext, and fetchAll) has completed.

Returns:: IlTrue if the last call to one of the asynchronous-enabled member functions (select, fetchNext, and fetchAll) has completed. If this member function returns IlFalse, it is necessary to call the asynchronous-enabled member function (with the same parameter values) periodically until isAsyncCallCompleted returns IlTrue.

IlBoolean IliSQLTable::isColumnFetched ( IlInt colno ) const

Returns IlTrue if the column should be part of the result computed by the query.

The default is IlTrue.

Parameters:

colno

The column position.

Returns:: IlTrue if the column should be part of the result computed by the query. A value of IlFalse means that the column is only used to specify a condition.

IlBoolean IliSQLTable::isDistinct ( ) const

Returns IlTrue if the duplicate rows should be removed from the query result.

This property is referred to as the distinct property, and is initially set to IlFalse. Note that this property is used by the makeQuery member function. It is not taken into account if the query was set with the setQuery member function.

Returns:: IlTrue if the duplicate rows should be removed from the query result.

IlBoolean IliSQLTable::isInAsyncMode ( ) const

Returns IlTrue if the SQL table is in asynchronous mode.

Returns:: IlTrue if the SQL table is in asynchronous mode. This occurs when the SQL session of the SQL table is itself in asynchronous mode.

IlBoolean IliSQLTable::isInsertingNulls ( ) const

Returns IlTrue if the SQL table includes any NULL columns when it constructs the INSERT SQL statement required to insert a row into a database.

When NULL columns are included, any default values defined in the table schema of the database are not taken into account, since a NULL value will be explicitly specified. On the other hand, when no default values are defined in the database, performance may be increased by including NULL columns. This is referred to as the insert-nulls mode. Initially, this property is set to IlTrue.

Returns:: IlTrue if the SQL table includes any NULL columns when it constructs the INSERT SQL statement required to insert a row into a database.

IlBoolean IliSQLTable::isNoWaitOnLockRowEnabled ( ) const

The return value from this member function is only meaningful when the SQL session connects to an Oracle database server.

Returns:: IlTrue if the SQL SELECT statements used to lock rows will include the NOWAIT clause. The effect will be that calls to refreshAndLockRow will immediately fail, if the given row is locked by another session in the database, instead of waiting until the lock is released. This property is useful in implementing the "pessimistic concurrency control" policy. Initially, this property is set to IlFalse.

IlBoolean IliSQLTable::isNoWaitOnLockRowSupported ( ) const

Returns IlTrue if the enableNoWaitOnLockRow member function is in effect.

Returns:: IlTrue if the enableNoWaitOnLockRow member function is in effect.

virtual IlBoolean IliSQLTable::isQueryModeSupported ( ) const [virtual]

Returns IlTrue if the table supports query mode.

Returns:: IlTrue if the table supports query mode.

Reimplemented from IliTable.

virtual IlBoolean IliSQLTable::isSelectDone ( ) const [virtual]

Returns IlTrue if the select member function has been called since the object was constructed.

Returns:: IlTrue if the select member function has been called since the object was constructed.

Reimplemented from IliTable.

IlBoolean IliSQLTable::isTableUpdatable ( IlInt tblno ) const

Returns IlTrue if the table referenced at position tblno can be updated through this SQL table object.

Parameters:

tblno

The table reference position.

Returns:: IlTrue if the table referenced at position tblno can be updated through this SQL table object.

IlBoolean IliSQLTable::isUsingBoundVariables ( ) const

Returns IlTrue if the bind-vars mode of the SQL table is enabled.

In this mode, any column values that need to be sent to the database are packaged in bound variables of the native database call interface, instead of being part of the SQL statements. This setting, combined with the dynamic-SQL mode (disabled) and insert-nulls mode (enabled), enables a dramatic boost in performance, since it allows the IliSQLTable always to use the same statements for the INSERT, UPDATE and DELETE operations. Initially, this property is set to IlTrue.

Returns:: IlTrue if the bind-vars mode of the SQL table is enabled.

IlBoolean IliSQLTable::isUsingDynamicSQL ( ) const

Returns IlTrue if the SQL table is in dynamic-SQL mode.

This mode affects the way in which SQL UPDATE statements are constructed, when a row needs to be modified in the database. Such an UPDATE statement may set the values of all columns of the remote table in the IliSQLTable, or it may only set those columns of the remote table whose values have been changed in IliSQLTable. When dynamic-SQL mode is on, the quantity of data exchanged with the database is reduced, since not all column values need to be sent each time a row is updated. Alternatively, when dynamic-SQL mode is disabled, although the communication overhead is higher, the overall processing time may well be reduced if the bind-vars mode is also enabled, since the SQL UPDATE statement sent to the database remains constant across updates (and therefore the database processing overhead required to parse the statement and select an access path will be dramatically reduced). Initially, this property is set to IlTrue.

Returns:: IlTrue if the SQL table is in dynamic-SQL mode.

IlBoolean IliSQLTable::makeQuery ( )

Causes the SQL table to compute the SQL SELECT statement that will be used to query the database.

It is usually called once after the SQL table has been defined.

Returns:: IlTrue if successful.

virtual IliTable* IliSQLTable::makeQueryTable ( ) const [virtual]

Returns a memory table having the same number of columns as this table.

If query mode is supported, creates and returns a memory table having the same number of columns as this table. The returned memory table columns are all of the String type.

Returns:: The table.

Reimplemented from IliTable.

virtual IlBoolean IliSQLTable::moveRow	(	IlInt	from,
		IlInt	to
	)			`[virtual]`

Moves a row.

Parameters:

	from	The origin row position.
	to	The destination row position.

Returns:: IlTrue if successful. If the table (or subclass of the table) defines a mapping with a remote database, the row is also moved in the remote database (if possible).

Reimplemented from IliMemoryTable.

virtual IlBoolean IliSQLTable::refreshAndLockRow ( IlInt rowno ) [virtual]

Re-reads the row from the remote database.

If concurrency control is enabled, this member function will succeed only if the remote row has not changed since the last time it was fetched. In other words, this member function is sensitive to whether concurrency control is enabled. This contrasts with the refreshRow member function which is not sensitive to whether concurrency control is enabled. In addition, the FOR UPDATE SQL keywords are used in the SQL statement to retrieve the row so that its underlying database row(s) is(are) locked in the database server.

Note that some database systems may impose restrictions on which SQL SELECT statements can be used for the FOR UPDATE keywords. This occurs particularly when there is more than one table in the FROM section. In the case of SYBASE, the holdlock keyword is used instead of FOR UPDATE.

Parameters:

rowno

The row position.

Returns:: IlTrue if successful and IlFalse otherwise.

Reimplemented from IliTable.

virtual IlBoolean IliSQLTable::refreshRow ( IlInt rowno ) [virtual]

Re-reads the row from the remote database.

This member function is not sensitive to whether concurrency control is enabled. In other words, it will always attempt to re-read the remote row.

Parameters:

rowno

The row position.

Returns:: IlTrue if successful and IlFalse otherwise.

Reimplemented from IliTable.

IlBoolean IliSQLTable::removeTable ( IlInt tblno )

Removes a table reference.

Parameters:

tblno

The table reference position.

Returns:: IlTrue if successful.

virtual IlBoolean IliSQLTable::select ( ) [virtual]

Reads all rows from a remote database.

If the table (or subclass of the table) defines a mapping with a remote database, this member function clears the local row cache, and queries the database to obtain a new, up-to-date, set of rows.

Returns:: IlTrue if successful, and IlFalse otherwise.

Reimplemented from IliTable.

void IliSQLTable::setAutoCommit ( IlBoolean f )

Sets the auto-commit mode for the SQL table.

Parameters:

f If IlTrue, the auto-commit mode is on.

void IliSQLTable::setAutoRefresh ( IlBoolean f )

Sets the auto-refresh mode for the SQL table.

Parameters:

f If IlTrue, the auto-refresh mode is on.

void IliSQLTable::setCache ( IliTable * cache )

Sets the IliTable used by the IliSQLTable to manage the local row cache.

Parameters:

cache If NULL, the IliSQLTable will manage the local row cache itself.

void IliSQLTable::setColumnDesignWidth	(	IlInt	colno,
		IlInt	width
	)

Sets the design width of the column.

Parameters:

	colno	The column position.
	width	The width.

virtual void IliSQLTable::setColumnFetched	(	IlInt	colno,
		IlBoolean	f
	)			`[virtual]`

Sets the fetched property of the column.

Parameters:

	colno	The column position.
	f	If `IlTrue`, the fetched property is on.

virtual void IliSQLTable::setColumnOperation	(	IlInt	colno,
		IliSQLOperation	op
	)			`[virtual]`

Sets the operation requested for the column.

Parameters:

	colno	The column position.
	op	The operation.

virtual void IliSQLTable::setColumnOrderBy	(	IlInt	colno,
		IliSQLOrderByType	order
	)			`[virtual]`

Sets the order requested for the column.

Parameters:

	colno	The column position.
	order	The order requested for the column.

void IliSQLTable::setColumnPredicat	(	IlInt	colno,
		IlInt	cno,
		const char *	predicat,
		IlBoolean	wherePart
	)

Sets the predicate of the column in the conjunct.

Parameters:

	colno	The column position.
	cno	The conjunct position
	predicat	The predicate.
	wherePart	If `IlTrue`, from the `WHERE` clause, otherwise from the `HAVING` clause.

virtual void IliSQLTable::setColumnSQLText	(	IlInt	colno,
		const char *	text
	)			`[virtual]`

Sets the SQL text of the column.

Parameters:

	colno	The column position.
	text	The SQL text, that is copied.

virtual void IliSQLTable::setColumnTable	(	IlInt	colno,
		IlInt	tblno
	)			`[virtual]`

Sets the table reference onto which the column should be mapped.

Parameters:

	colno	The column position.
	tblno	The table position or `-1` if the column is not directly mapped onto a table column.

void IliSQLTable::setConcurrencyControl ( IlBoolean cc )

Enables/disables concurrency control for the SQL table.

Parameters:

cc If IlTrue, enables concurrency control for the SQL table.

void IliSQLTable::setCursorBufferedRowsCount ( IlInt count )

Sets the number of buffered rows to count.

Parameters:

count

The count.

void IliSQLTable::setDistinct ( IlBoolean f )

Sets the distinct property of the SQL table.

Parameters:

f If IlTrue, the distinct property is on.

void IliSQLTable::setFetchPolicy ( IliFetchPolicy fp )

Sets the fetch policy of the SQL table.

Parameters:

fp The fetch policy which must be one of the IliFP_AsNeeded or IliFP_Immediate values. A value of IliFP_AsNeeded means that the SQL table should only fetch rows from the database when necessary, whereas, a value of IliFP_Immediate requires that the SQL table fetch all rows resulting from an SQL SELECT statement as soon as possible. Note that the IliFP_AsNeeded setting is only effective when auto-commit is disabled.

void IliSQLTable::setJoinType	(	IlInt	jno,
		IliSQLJoinType	type
	)

Sets the type of the join.

Parameters:

	jno	The join position.
	type	The join type.

void IliSQLTable::setQuery ( const char * query )

Sets the query on the SQL table.

If this member function is called instead of the makeQuery member function, it is assumed that the correct schema (set of columns) has been defined for this SQL table. Note that the query parameter is copied by this member function.

Parameters:

query

The query.

void IliSQLTable::setQueryConjunct ( const char * condition )

Sets the condition that will be combined with the query defined on the SQL table, to derive the effective query that will be submitted to the remote database.

Parameters:

condition

The condition.

IlBoolean IliSQLTable::setQueryFrom ( const IliSQLTableRef & tblRef )

Defines the SQL table in such a way that it will map onto the database table indicated.

When this member function is called, the schema of the designated table is read from the database catalog, and the SQL table is defined as a query that retrieves all columns and all rows from this table. This member function must be called for an SQL table that is not already defined.

Parameters:

tblRef

The database table.

Returns:: IlTrue if successful and IlFalse otherwise.

void IliSQLTable::setRowsCountLimit ( IlInt size )

Sets the rows count limit of the SQL table.

Parameters:

size

The maximum size.

void IliSQLTable::setSQLSession ( IliSQLSession * session )

Sets the SQL session object of the table.

Parameters:

session

The SQL session.

void IliSQLTable::setTableParentDataSourceName	(	IlInt	tblno,
		const char *	name
	)

Sets the name of the parent data source for the table.

Parameters:

	tblno	The table reference position.
	name	The data source name.

void IliSQLTable::setTableParentPath	(	IlInt	tblno,
		const IliAttributePath &	path
	)

Sets the path to the nested table for the table.

Parameters:

	tblno	The table reference position.
	path	The path.

void IliSQLTable::setTableParentRow	(	IlInt	tblno,
		const IliRowPtr &	row
	)

Sets the parent row for the table.

Parameters:

	tblno	The table reference position.
	row	The parent row.

void IliSQLTable::setTableParentSQLTable	(	IlInt	tblno,
		IliSQLTable *	sqlTbl
	)

Sets the parent SQL table for the table.

Parameters:

	tblno	The table reference position.
	sqlTbl	The SQL table.

void IliSQLTable::setTableParentTableAlias	(	IlInt	tblno,
		const char *	name
	)

Sets the alias of the database table that identifies the parent row.

Parameters:

	tblno	The table reference position.
	name	The alias, it should belong to the parent SQL table.

void IliSQLTable::setTableRect	(	IlInt	tblno,
		const IlvRect &	rect
	)

Sets the rectangle of the table reference.

Parameters:

	tblno	The table reference position.
	rect	The rectangle.

void IliSQLTable::setTableRef	(	IlInt	tblno,
		const IliSQLTableRef &	tblRef
	)

Replaces a table reference.

Parameters:

	tblno	The table reference position.
	tblRef	The new table reference.

void IliSQLTable::setTableUpdatable	(	IlInt	tblno,
		IlBoolean	flag
	)

Changes the updatable property of the table reference.

Parameters:

	tblno	The table reference position.
	flag	If `IlTrue`, the table is updatable.

virtual IlBoolean IliSQLTable::updateRow	(	IlInt	rowno,
		IliTableBuffer *	buff
	)			`[virtual]`

Updates a row with the values in the table buffer.

Not all the values are used to update the row. Instead the values for which the isModified member function returns IlTrue , are used. Note that this member function does not check any of the constraints defined in the schema. If the table (or subclass of the table) defines a mapping with a remote database, the row is also changed in the remote database.

Parameters:

	rowno	The row position.
	buff	The table buffer.

Returns:: IlTrue if successful and IlFalse if rowno is out of bounds, or if the row could not be updated.

Reimplemented from IliMemoryTable.

void IliSQLTable::useBoundVariables ( IlBoolean f )

Sets the bind-vars mode of the SQL table.

Parameters:

f If IlTrue, the bind-vars mode is on.

void IliSQLTable::useDynamicSQL ( IlBoolean f )

Sets the dynamic-SQL mode for the SQL table.

Parameters:

f If IlTrue, the dynamic-SQL mode is on.

virtual void IliSQLTable::write ( IL_STDPREF ostream & output ) const [virtual]

Writes the definition of the SQL table to an output stream, in a form suitable to be read back by the stream-based constructor.

Parameters:

output

The output stream.

Reimplemented from IliMemoryTable.

Rogue Wave ViewsData Access Package API Reference Guide

IliSQLTable Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Rogue Wave Views
Data Access Package API Reference Guide