IliTable Class Reference

Table class. More...

#include <ilviews/dataccess/table.h>

Inheritance diagram for IliTable:

Public Member Functions
void	addErrorSink (IliErrorSink *sink)
	Adds an error sink.
virtual IlBoolean	allowRowMove () const
	Returns `IlTrue` if the table (or subclass of the table) allows row move operations.
IlInt	appendParameter (const char paramName, const IliDatatype type, IlInt maxlen=-1)
	Appends a new parameter to the table parameters.
IlInt	appendRow (IliTableBuffer *tblBuf)
	Appends a new row defined by the table buffer.
IlInt	appendRowInCache (IliTableBuffer *tblBuf)
	Appends a new row defined by the table buffer.
virtual IlBoolean	applyQueryMode (IliTable *queryTable)
	Applies the query specified by the conditions contained in the provided table.
IliValue	at (IlInt rowno, IliName colname) const
	Returns a value.
IliValue	at (IlInt rowno, IlInt colno) const
	Returns a value.
virtual IlBoolean	checkConstraints (IlInt rowno, IliTableBuffer *buff) const
	Validates the table buffer data.
virtual void	clearRows ()
	Deletes all rows.
IliTable *	copyTable () const
	Returns a copy of the table.
void	deleteParameter (IlInt paramno)
	Deletes a parameter.
virtual IlBoolean	deleteRow (IlInt rowno)
	Deletes a row.
virtual IlBoolean	deleteRowInCache (IlInt rowno)
	Deletes a row.
void	enableColumnCompletion (IlInt colno, IlBoolean flag)
	Specifies whether completion is enabled for the column.
virtual IlBoolean	exchangeRows (IlInt rowno1, IlInt rowno2)
	Exchanges two rows.
virtual IlBoolean	exchangeRowsInCache (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 count=1)
	Fetches up a number of rows from the database and stores them in the local row cache.
IlInt	findFirstRow (const IliValue &value, IlInt colno, IlBoolean complete, IlInt fromRow=0, IlInt toRow=-1) const
	Searches for a row located between two positions.
IlInt	findRow (const IliValue &value, IlInt colno, IlBoolean complete, IlInt fromRow=0, IlInt toRow=-1) const
	Searches for a row located between two positions.
IliTableBuffer *	getBuffer ()
	Returns a table buffer for the table.
IlBoolean	getColumnDisplayValue (IlInt colno, const IliValue &value, IliValue &displayValue, IlvGraphicHolder *=NULL)
	Returns the display value for a value.
IliTable *	getColumnEffectiveForeignTable (IlInt colno, IlvGraphicHolder *h=NULL) const
	Returns the effective foreign table.
const char *	getColumnForeignDataSourceName (IlInt colno) const
	Returns the name of the data source that will provide a foreign table for one column.
const char *	getColumnForeignDisplayColumn (IlInt colno) const
	Returns the name of the display column in the foreign table.
IliTable *	getColumnForeignTable (IlInt colno) const
	Returns the foreign table of one column.
const char *	getColumnForeignValueColumn (IlInt colno) const
	Returns the name of the value column in the foreign table.
IlAny	getCompareData () const
	Returns the user data that can be used to compare two rows.
IliCompareFunction	getCompareFunction () const
	Returns the function that is used to compare two rows.
IliTablePropertyManager *	getDefaultPropertyManager ()
	Returns the default property manager.
const IliTablePropertyManager *	getDefaultPropertyManager () const
	Returns the default property manager.
IlvGadgetHolder *	getGadgetHolder () const
	Returns the gadget holder to which the table is attached.
IliTablePropertyManager *	getNamedPropertyManager (const char *name) const
	Returns a property manager from its name.
IlInt	getNamedPropertyManagerCount () const
	Returns the number of named property managers.
const char *	getParameterColumnName (IlInt paramno) const
	Returns the name of the column, which the parameter is attached to.
const char *	getParameterDataSourceName (IlInt paramno) const
	Returns the name of the data source which the parameter is attached to.
IliValue	getParameterDataSourceValue (IlInt paramno) const
	Returns the current value of one parameter.
IlInt	getParameterIndex (const char *name) const
	Returns the position of one parameter.
IlInt	getParameterMaxLength (IlInt paramno) const
	Returns the maximum length allowed for one parameter.
const char *	getParameterName (IlInt paramno) const
	Returns a parameter name.
IlInt	getParametersCount () const
	Returns the number of parameters defined for this table.
const IliDatatype *	getParameterType (IlInt paramno) const
	Returns the parameter type.
IliValue	getParameterValue (IliName paramName) const
	Returns the current value of one parameter.
IliValue	getParameterValue (IlInt paramno) const
	Returns the current value of one parameter.
IlBoolean	getProperty (IlInt rowno, IlInt colno, const IlvSymbol *propName, IliValue &propVal) const
	Returns a property value attached to the part of the table.
IlInt	getPropertyCount (IlInt rowno, IlInt colno) const
	Returns the property count attached to the part of the table.
const char *	getPropertyManagerNameAt (IlInt idx) const
	Returns the name of the named property manager.
const IlvSymbol *	getPropertyNameAt (IlInt rowno, IlInt colno, IlInt propIndex) const
	Returns a property name attached to the part of the table.
IliRowPtr	getRowPtr (IlInt rowno=-1) const
	Returns an `IliRowPtr` that points to one row.
virtual IlInt	getRowsCount () const
	Returns the number of rows in the table.
virtual IliRowStatus	getRowStatus (IlInt rowno) const
	Returns the status of one row.
IliTransactionManager *	getTransactionManager () const
	Returns the transaction manager managing the table.
const char *	getTransactionManagerName () const
	Returns the name of the transaction manager that manages the table.
virtual IlBoolean	getValue (IlInt rowno, IlInt colno, IliValue &value) const
	Returns a value.
virtual IlBoolean	insertRow (IlInt rowno, IliTableBuffer *buff)
	Inserts a row that is defined by the table buffer.
virtual IlBoolean	insertRowInCache (IlInt rowno, IliTableBuffer *buff)
	Inserts a row that is defined by the table buffer.
virtual IlBoolean	insertRowsFrom (const IliTable *src, IlInt srcFromRow=0, IlInt srcToRow=-1, IlBoolean stopAtFirstError=IlTrue, IlInt insertAt=-1)
	Inserts rows into this table by copying them from another table.
IlBoolean	isColumnCompletionEnabled (IlInt colno) const
	Returns `IlTrue` if completion is enabled for the column.
IlBoolean	isColumnValueConstrained (IlInt colno) const
	Returns `IlTrue` if the column is constrained to taking its values from the domain of the value column of the foreign table.
IlBoolean	isModified () const
	Returns `IlTrue` if the rows of the table have been modified since the last time.
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.
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	moveRowInCache (IlInt from, IlInt to)
	Moves a row.
IliTablePropertyManager *	newNamedPropertyManager (const char *name)
	Creates and returns a new named property manager.
virtual IliTablePropertyManager *	newPropertyManager ()
	Creates and returns a new anonymous property manager.
virtual IlBoolean	refreshAndLockRow (IlInt rowno)
	Refreshes and lock a row.
virtual IlBoolean	refreshRow (IlInt rowno)
	Refreshes a row.
void	releaseBuffer (IliTableBuffer *buff)
	Releases a table buffer.
void	removeErrorSink (IliErrorSink *sink)
	Removes an error sink from this table.
void	removeNamedPropertyManager (const char *name)
	Removes a property manager.
void	removeProperty (IlInt rowno, IlInt colno, const IlvSymbol *propName)
	Removes a property from the part of the table.
virtual IlBoolean	select ()
	Reads all rows from a remote database.
IlBoolean	set (IlInt rowno, IliName colname, const IliValue &value)
	Sets a value.
IlBoolean	set (IlInt rowno, IlInt colno, const IliValue &value)
	Sets a value.
void	setColumnForeignDataSourceName (IlInt colno, const char *dsname)
	Sets the name of the foreign data source for one column.
void	setColumnForeignDisplayColumn (IlInt colno, const char *name)
	Sets the name of the display column in the foreign table.
void	setColumnForeignTable (IlInt colno, IliTable *table)
	Sets the foreign table of one column.
void	setColumnForeignValueColumn (IlInt colno, const char *name)
	Sets the name of the value column in the foreign table.
void	setColumnValueConstrained (IlInt colno, IlBoolean flag)
	Specifies that the column is constrained to take its values from the domain of the value column of the foreign table.
void	setCompareFunction (IliCompareFunction fct, IlAny arg=0)
	Defines the function and user data that must be used to compare two rows.
void	setGadgetHolder (IlvGadgetHolder *gadHold)
	Attaches the table to a gadget holder.
IlBoolean	setInCache (IlInt rowno, IlInt colno, const IliValue &value)
	Sets a value.
virtual void	setModified (IlBoolean flag)
	Sets the value of the modified property of the table.
void	setParameterColumnName (IlInt paramno, const char *colname)
	Attaches a parameter to one column.
void	setParameterDataSourceName (IlInt paramno, const char *dsname)
	Attaches one parameter to one data source.
void	setParameterMaxLength (IlInt paramno, IlInt maxlen)
	Sets the maximum length allowed for the parameter.
void	setParameterName (IlInt paramno, const char *name)
	Sets a parameter name.
void	setParameterType (IlInt paramno, const IliDatatype *type)
	Sets the type of one parameter.
void	setParameterValue (IliName paramName, const IliValue &value)
	Sets the value of one parameter.
void	setParameterValue (IlInt paramno, const IliValue &value)
	Sets the value of one parameter.
void	setProperty (IlInt rowno, IlInt colno, const IlvSymbol *propName, const IliValue &propVal)
	Sets a property value to a part of the table.
void	setTransactionManager (IliTransactionManager *tm)
	Changes the transaction that manages this table.
void	setTransactionManagerName (const char *name)
	Changes the transaction that manages this table.
void	sortRows (const IlInt *colnoArray, IlInt columnsCount, IlInt fromRow=0, IlInt toRow=-1, IliCompareFunction fct=0, IlAny data=0)
	Sorts a set of rows.
virtual IlBoolean	updateRow (IlInt rowno, IliTableBuffer *buff)
	Updates a row with the values in the table buffer.
virtual IlBoolean	updateRowInCache (IlInt rowno, IliTableBuffer *buff)
	Updates a row.
virtual void	write (IL_STDPREF ostream &) const
	Writes the definition of a schema to an output stream in a form suitable to be read back by the stream-based constructor.
void	writeTable (IL_STDPREF ostream &output) const
	Writes the definition of the table to an output stream, in a form suitable to be read back by the `ReadTable` static member function.
Static Public Member Functions
static IliTable *	ReadTable (IlvDisplay *disp, IL_STDPREF istream &input)
	Constructs and returns an instance of a subclass of `IliTable` by reading its definition from an input stream.
Protected Member Functions
virtual void	cellChanged (IlInt rowno, IlInt colno)
	Called just after a cell has changed.
virtual void	raiseError (const IliErrorMessage &msg) const
	Called each time an error occurs.
virtual void	rowChanged (IlInt rowno)
	Called just after the row at position `rowno` has changed (that is, when one or more values in the row have changed).
virtual void	rowDeleted (IlInt rowno)
	Called just after a row has been removed from the table.
virtual void	rowFetched (IlInt rowno)
	Called just after a new row has been fetched from a remote database and inserted.
virtual void	rowInserted (IlInt rowno)
	Called just after a new row has been inserted.
virtual void	rowMoved (IlInt src, IlInt dest)
	Called just after a row has moved.
virtual void	rowToBeChanged (IlInt rowno)
	Called just before the row is changed.
virtual void	rowToBeDeleted (IlInt rowno)
	Called just before a row is removed from the table.
virtual void	tableChanged ()
	Called when the `IliTable` object has undergone a significant number of changes.
Friends
class	IliMemoryTable
class	IliTransactionManager

Detailed Description

Table class.

Library: dataccess

The IliTable class is an abstract class that defines objects capable of managing an ordered collection of rows. Each of these rows conforms to the same schema. Since the IliTable class is abstract, it defines a protocol for creating, editing, and inspecting a table object. This protocol is implemented in subclasses of the IliTable class. In addition to having a schema, a table has a set of parameters. A table also manages a set of rows. Some of the IliTable subclasses, such as IliMemoryTable or IliStringsTable, manage rows themselves. They are called one-tier tables. Other subclasses, such as IliSQLTable, manage rows located in a remote database. They are called two-tier tables. Some of the member functions of the IliTable class, behave differently in these two types of tables. It should be noted that a two-tier table implements a local row cache, where it stores a copy of some of the remote rows to which the table is mapped at any particular time. The purpose of this cache is to reduce communication overheads with the remote database engine, and to allow you to overcome the fact that many database systems do not provide random access to their data. In this situation, a subset of the database rows is copied and stored in the local row cache allowing the table object to provide random access to these rows. The IliTable class does not support the concept of a current row. This is due to the fact that such a concept would not allow many users to simultaneously access the table, each with their own current row. Instead, a companion class, IliTableBuffer, is provided. This class implements the notion of current row, allowing many simultaneous users of an IliTable object.

See also:: IliDataSource, IliErrorList, IliErrorMessage, IliErrorSink, IliName, IliRowPtr, IliTableBuffer, IliTableGadget, IliTableHook, IliTablePropertyManager, IliTransactionManager, IlvGadgetHolder

Member Function Documentation

void IliTable::addErrorSink ( IliErrorSink * sink )

Adds an error sink.

All errors that are thrown by one of the raiseError member functions will be forwarded to this error sink. Note that the table will not delete the error sink at destruction time, so the same error sink may be safely shared among many tables.

Parameters:

sink

The error sink.

virtual IlBoolean IliTable::allowRowMove ( ) const [virtual]

Returns IlTrue if the table (or subclass of the table) allows row move operations.

Returns:: IlTrue if the table (or subclass of the table) allows row move operations.

Reimplemented in IliMemoryTable, and IliStringsTable.

IlInt IliTable::appendParameter	(	const char *	paramName,
		const IliDatatype *	type,
		IlInt	maxlen = `-1`
	)

Appends a new parameter to the table parameters.

Parameters:

	paramName	The parameter name, it is copied.
	type	The parameter type.
	maxlen	The maximum length.

Returns:: The position of the newly created parameter.

IlInt IliTable::appendRow ( IliTableBuffer * tblBuf )

Appends a new row defined by the table buffer.

Parameters:

tblBuf

The table buffer.

Returns:: The position of the new row, or -1 if it fails. If the table (or subclass of the table) defines a mapping with a remote database, the row is also inserted in the remote database.

IlInt IliTable::appendRowInCache ( IliTableBuffer * tblBuf )

Appends a new row defined by the table buffer.

This member function is similar to the appendRow member function except that it appends only the row in the local row cache if this table is a two-tier table.

Parameters:

tblBuf

The table buffer.

Returns:: The position of the new row, or -1 if it fails. If the table (or subclass of the table) defines a mapping with a remote database, the row is also inserted in the remote database.

virtual IlBoolean IliTable::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 in IliSQLTable.

IliValue IliTable::at	(	IlInt	rowno,
		IliName	colname
	)			const

Returns a value.

Parameters:

	rowno	The row position.
	colno	The column position.

Returns:: The value in the row positioned at rowno for the column named colname.

IliValue IliTable::at	(	IlInt	rowno,
		IlInt	colno
	)			const

Returns a value.

Parameters:

	rowno	The row position.
	colno	The column position.

Returns:: The value in the row positioned at rowno for the column positioned at colno. This member function is similar to the getValue member function, except that it does not report any errors that may have occurred.

virtual void IliTable::cellChanged	(	IlInt	rowno,
		IlInt	colno
	)			`[protected, virtual]`

Called just after a cell has changed.

If more than one value has changed in a row, it is preferable to call the rowChanged member function once, instead of calling cellChanged many times.

Parameters:

	rowno	The row position.
	colno	The column position.

virtual IlBoolean IliTable::checkConstraints	(	IlInt	rowno,
		IliTableBuffer *	buff
	)			const `[virtual]`

Validates the table buffer data.

Parameters:

	rowno	The row position.
	buff	The table buffer.

Returns:: IlTrue if the buff table buffer contains a valid row as defined by the constraints specified in the schema of the table. If the rowno parameter is equal to -1, the buff parameter is assumed to contain a row that will be inserted into the table. Otherwise, rowno must designate an existing row, and buff is assumed to contain a replacement for that row. The constraints that are checked by this member function are the primary key constraint, the NOT NULL constraint, and the maximum length column constraint.

virtual void IliTable::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 in IliMemoryTable, IliSQLTable, and IliStringsTable.

IliTable* IliTable::copyTable ( ) const

Returns a copy of the table.

This member function can copy any subclass of IliTable.

Returns:: The table.

void IliTable::deleteParameter ( IlInt paramno )

Deletes a parameter.

Parameters:

paramno

The parameter position.

virtual IlBoolean IliTable::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 in IliMemoryTable, IliSQLTable, and IliStringsTable.

virtual IlBoolean IliTable::deleteRowInCache ( IlInt rowno ) [virtual]

Deletes a row.

This virtual member function is similar to the deleteRow member function except that it only deletes the row in the local row cache if this table is a two-tier table.

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

void IliTable::enableColumnCompletion	(	IlInt	colno,
		IlBoolean	flag
	)

Specifies whether completion is enabled for the column.

Parameters:

	colno	The column name.
	flag	The completion flags.

virtual IlBoolean IliTable::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 in IliMemoryTable, and IliSQLTable.

virtual IlBoolean IliTable::exchangeRowsInCache	(	IlInt	rowno1,
		IlInt	rowno2
	)			`[virtual]`

Exchanges two rows.

This virtual member function is similar to the exchangeRows member function except that it exchanges only the rows in the local row cache.

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

virtual IlInt IliTable::fetchAll ( ) [virtual]

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

Returns:: The number of rows effectively fetched.

Reimplemented in IliSQLTable.

virtual IlBoolean IliTable::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 in IliSQLTable.

virtual IlInt IliTable::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 in IliSQLTable.

IlInt IliTable::findFirstRow	(	const IliValue &	value,
		IlInt	colno,
		IlBoolean	complete,
		IlInt	fromRow = `0`,
		IlInt	toRow = `-1`
	)			const

Searches for a row located between two positions.

Parameters:

	value	The value.
	colno	The column position.
	complete	The complete flag. To make a match when the parameter is `IlTrue`, the character string representation of the `value` parameter may be a prefix of the character string representation of the value contained in the `colno` column of the row. In this case, if several rows correspond to the prefix, the function returns the position of the first row to which it corresponds.
	fromRow	The start position.
	toRow	The last row position. If equals `-1` then all rows starting at `fromRow` are located. The first of these rows that contains a value equal to the value in the column is the match.

Returns:: The row position if successful. Otherwise returns -1.

IlInt IliTable::findRow	(	const IliValue &	value,
		IlInt	colno,
		IlBoolean	complete,
		IlInt	fromRow = `0`,
		IlInt	toRow = `-1`
	)			const

Searches for a row located between two positions.

Parameters:

	value	The value.
	colno	The column position.
	complete	The complete flag. To make a match when the parameter is `IlTrue`, the character string representation of the `value` parameter may be a prefix of the character string representation of the value contained in the `colno` column of the row. In this case, if several rows correspond to the prefix, the function returns `-1`.
	fromRow	The start position.
	toRow	The last row position. If equals `-1` then all rows starting at `fromRow` are located. The first of these rows that contains a value equal to the value in the column is a match.

Returns:: The row position if successful. Otherwise returns -1.

IliTableBuffer* IliTable::getBuffer ( )

Returns a table buffer for the table.

A table buffer is used to inspect, alter or add rows into the table. Any table buffer obtained through this member function should be returned to the table when finished, using the releaseBuffer member function.

Returns:: The table buffer.

IlBoolean IliTable::getColumnDisplayValue	(	IlInt	colno,
		const IliValue &	value,
		IliValue &	displayValue,
		IlvGraphicHolder *	= `NULL`
	)

Returns the display value for a value.

If the column has an effective foreign table, this member function attempts to map the value parameter through the effective foreign table yielding a display value. If the column does not have an effective foreign table, the value is copied into the display value.

Parameters:

	colno	The column name.
	value	The value.
	displayValue	The display value.
	h	The holder. It is used to resolve the foreign data source.

Returns:: IlTrue if successful.

IliTable* IliTable::getColumnEffectiveForeignTable	(	IlInt	colno,
		IlvGraphicHolder *	h = `NULL`
	)			const

Returns the effective foreign table.

If a foreign table has been specified with the getColumnForeignTable member function for one column, this table is returned. Otherwise, if a foreign data source name has been specified with the getColumnForeignDataSourceName, this name is resolved to a data source (by way of the IliRepository object and the holder) and if a data source with that name is found, it is returned. Otherwise, NULL is returned.

Parameters:

	colno	The column name.
	h	The holder.

Returns:: The foreign table.

const char* IliTable::getColumnForeignDataSourceName ( IlInt colno ) const

Returns the name of the data source that will provide a foreign table for one column.

Parameters:

colno

The column position.

Returns:: NULL if position is out of bounds, and an empty string if no foreign data source is defined for the column.

const char* IliTable::getColumnForeignDisplayColumn ( IlInt colno ) const

Returns the name of the display column in the foreign table.

The column which is used to find a replacement value for the column.

Parameters:

colno

The column name.

Returns:: The name.

IliTable* IliTable::getColumnForeignTable ( IlInt colno ) const

Returns the foreign table of one column.

Returns:: The foreign table or NULL if this column does not have a foreign table.

const char* IliTable::getColumnForeignValueColumn ( IlInt colno ) const

Returns the name of the value column in the foreign table.

The column which the value in the column must be matched with, to yield a display value.

Parameters:

colno

The column position.

Returns:: The name of the value column in the foreign table.

IlAny IliTable::getCompareData ( ) const

Returns the user data that can be used to compare two rows.

Returns:: The user data.

IliCompareFunction IliTable::getCompareFunction ( ) const

Returns the function that is used to compare two rows.

Returns:: The function.

IliTablePropertyManager* IliTable::getDefaultPropertyManager ( )

Returns the default property manager.

Returns:: The default property manager of the IliTable object.

const IliTablePropertyManager* IliTable::getDefaultPropertyManager ( ) const

Returns the default property manager.

Returns:: The default property manager of the IliTable object.

IlvGadgetHolder* IliTable::getGadgetHolder ( ) const

Returns the gadget holder to which the table is attached.

A table must be attached to a gadget holder for the getParameterDataSourceValue member function to work correctly.

Returns:: The gadget holder to which the table is attached, or NULL if the table is not attached to a gadget holder.

IliTablePropertyManager* IliTable::getNamedPropertyManager ( const char * name ) const

Returns a property manager from its name.

Parameters:

name

The property manager name.

Returns:: The property manager named name if it exists and NULL otherwise.

IlInt IliTable::getNamedPropertyManagerCount ( ) const

Returns the number of named property managers.

Returns:: The count.

const char* IliTable::getParameterColumnName ( IlInt paramno ) const

Returns the name of the column, which the parameter is attached to.

Parameters:

paramno

The parameter position.

Returns:: The name or NULL if position is out of bounds, and an empty string if the parameter is not attached to a column.

const char* IliTable::getParameterDataSourceName ( IlInt paramno ) const

Returns the name of the data source which the parameter is attached to.

Parameters:

paramno

The parameter position.

Returns:: The data source name or NULL if position is out of bounds, and an empty character string if the parameter is not attached to a data source.

IliValue IliTable::getParameterDataSourceValue ( IlInt paramno ) const

Returns the current value of one parameter.

This member function takes into account any data source or column that the parameter may be attached to.

Parameters:

paramno

The parameter position.

Returns:: The value.

IlInt IliTable::getParameterIndex ( const char * name ) const

Returns the position of one parameter.

Parameters:

name

The parameter name.

Returns:: The position, otherwise -1 if no such parameter is found.

IlInt IliTable::getParameterMaxLength ( IlInt paramno ) const

Returns the maximum length allowed for one parameter.

A value of -1 means that the length is not constrained.

Parameters:

paramno

The parameter position.

Returns:: The maximum length.

const char* IliTable::getParameterName ( IlInt paramno ) const

Returns a parameter name.

Parameters:

paramno

The parameter position.

Returns:: The name otherwise NULL if position is out of bounds.

IlInt IliTable::getParametersCount ( ) const

Returns the number of parameters defined for this table.

Returns:: The count.

const IliDatatype* IliTable::getParameterType ( IlInt paramno ) const

Returns the parameter type.

Parameters:

paramno

The parameter position.

Returns:: The type, otherwise NULL if position is out of bounds.

IliValue IliTable::getParameterValue ( IliName paramName ) const

Returns the current value of one parameter.

This member function does not take into account any data source or column which the parameter may be attached to.

Parameters:

paramName

The parameter name.

Returns:: The value.

IliValue IliTable::getParameterValue ( IlInt paramno ) const

Returns the current value of one parameter.

This member function does not take into account any data source or column which the parameter may be attached to.

Parameters:

paramno

The parameter position.

Returns:: The value.

IlBoolean IliTable::getProperty	(	IlInt	rowno,
		IlInt	colno,
		const IlvSymbol *	propName,
		IliValue &	propVal
	)			const

Returns a property value attached to the part of the table.

Note: Accesses the default property manager.

Parameters:

	rowno	The row position.
	colno	The column position.
	propName	The property name.
	propVal	The value.

Returns:: IlTrue if successful.

IlInt IliTable::getPropertyCount	(	IlInt	rowno,
		IlInt	colno
	)			const

Returns the property count attached to the part of the table.

Note: Accesses the default property manager.

Parameters:

	rowno	The row position.
	colno	The column position.

Returns:: The number of properties attached.

const char* IliTable::getPropertyManagerNameAt ( IlInt idx ) const

Returns the name of the named property manager.

Parameters:

idx The property manager position. It must be between 0 and getNamedPropertyManagerCount().

Returns:: The name.

const IlvSymbol* IliTable::getPropertyNameAt	(	IlInt	rowno,
		IlInt	colno,
		IlInt	propIndex
	)			const

Returns a property name attached to the part of the table.

Note: Accesses the default property manager.

Parameters:

	rowno	The row position.
	colno	The column position.
	propIndex	The property index. The value must be between `0` and `getPropertyCount()`.

Returns:: The name of the property of the part identified by rowno and colno positioned at propIndex.

IliRowPtr IliTable::getRowPtr ( IlInt rowno = -1 ) const

Returns an IliRowPtr that points to one row.

Parameters:

rowno

The row position.

Returns:: An IliRowPtr that points to the row at position rowno (or to no row if rowno is -1 or if it is out of bounds).

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

Returns the number of rows in the table.

Returns:: The count.

Reimplemented in IliMapTable, IliMemoryTable, IliSQLTable, and IliStringsTable.

virtual IliRowStatus IliTable::getRowStatus ( IlInt rowno ) const [virtual]

Returns the status of one row.

This is useful when a transaction manager manages the table. The row status can be one of the following:

IliNotARow The row index is out of bounds.
IliRegularRow The row has not been touched in the current local transaction.
IliInsertedRow The row has been inserted in the current local transaction.
IliUpdatedRow The row has been updated in the current local transaction.
IliDeletedRow The row has been deleted in the current local transaction.

The "current local transaction" refers to the changes that have occurred since the most recent call to one of the following member functions (assuming the transaction manager is currently started):

Note that the IliDeletedRow tag is never returned since a deleted row has no row index. This exists and is mentioned here for your information only.

Parameters:

rowno

The row position.

Returns:: The status.

Reimplemented in IliMemoryTable.

IliTransactionManager* IliTable::getTransactionManager ( ) const

Returns the transaction manager managing the table.

Initially, this property is NULL.

Returns:: The transaction manager managing the table or NULL if the table is not managed by a transaction manager.

const char* IliTable::getTransactionManagerName ( ) const

Returns the name of the transaction manager that manages the table.

Returns:: The name of the transaction manager that manages the table. It returns NULL if the table is not managed by a transaction manager or if it is managed by an anonymous transaction manager.

virtual IlBoolean IliTable::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 in IliMapTable, IliMemoryTable, IliSQLTable, and IliStringsTable.

virtual IlBoolean IliTable::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 in IliMemoryTable, IliSQLTable, and IliStringsTable.

virtual IlBoolean IliTable::insertRowInCache	(	IlInt	rowno,
		IliTableBuffer *	buff
	)			`[virtual]`

Inserts a row that is defined by the table buffer.

This virtual member function is similar to the insertRow member function except that it only inserts the row in the local row cache if this table is a two-tier table.

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

virtual IlBoolean IliTable::insertRowsFrom	(	const IliTable *	src,
		IlInt	srcFromRow = `0`,
		IlInt	srcToRow = `-1`,
		IlBoolean	stopAtFirstError = `IlTrue`,
		IlInt	insertAt = `-1`
	)			`[virtual]`

Inserts rows into this table by copying them from another table.

The rows are taken from the src parameter, starting from srcFromRow up to srcToRow (or up to the end of src if srcToRow is less than 0). The only constraint on table src is that it must have a schema identical to that of this table. In other words, it must have the same number of columns and the columns must have compatible data types.

Parameters:

	src	The source table.
	srcFromRow	The first row position of the source table.
	srcToRow	The last row position of the source table.
	stopAtFirstError	If `IlTrue`, the process of inserting rows will stop as soon as an error is caught. Otherwise, the maximum possible number of rows will be copied.
	insertAt	The insertion position.

Returns:: IlTrue if it is successful and IlFalse otherwise.

IlBoolean IliTable::isColumnCompletionEnabled ( IlInt colno ) const

Returns IlTrue if completion is enabled for the column.

Parameters:

colno

The column name.

Returns:: IlTrue if completion is enabled for the column.

IlBoolean IliTable::isColumnValueConstrained ( IlInt colno ) const

Returns IlTrue if the column is constrained to taking its values from the domain of the value column of the foreign table.

Parameters:

colno

The column name.

Returns:: The constraint flags.

IlBoolean IliTable::isModified ( ) const

Returns IlTrue if the rows of the table have been modified since the last time.

Returns:: IlTrue if the rows of the table have been modified since the last time.

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

Returns IlTrue if the table supports query mode.

Returns:: IlTrue if the table supports query mode.

Reimplemented in IliSQLTable.

virtual IlBoolean IliTable::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 in IliSQLTable.

virtual IliTable* IliTable::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 in IliSQLTable.

virtual IlBoolean IliTable::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 in IliMemoryTable, IliSQLTable, and IliStringsTable.

virtual IlBoolean IliTable::moveRowInCache	(	IlInt	from,
		IlInt	to
	)			`[virtual]`

Moves a row.

This virtual member function is similar to the moveRow member function except that it moves only the row in the local row cache.

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

IliTablePropertyManager* IliTable::newNamedPropertyManager ( const char * name )

Creates and returns a new named property manager.

Returns:: A new named property manager.

virtual IliTablePropertyManager* IliTable::newPropertyManager ( ) [virtual]

Creates and returns a new anonymous property manager.

Returns:: A new anonymous property manager for the IliTable object.

virtual void IliTable::raiseError ( const IliErrorMessage & msg ) const [protected, virtual]

Called each time an error occurs.

Parameters:

msg

The error message.

static IliTable* IliTable::ReadTable	(	IlvDisplay *	disp,
		IL_STDPREF istream &	input
	)			`[static]`

Constructs and returns an instance of a subclass of IliTable by reading its definition from an input stream.

Parameters:

	disp	The display.
	input	The input stream.

Returns:: The table.

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

Refreshes and lock a row.

If this is a two-tier table, this member function re-reads the row from the remote database. In addition, if the remote database supports it, the remote row is locked so that other users cannot modify or delete it as long as the lock is held. The means by which the lock can be released is not specified by class IliTable. It is left to the discretion of subclasses (see class IliSQLTable).

Parameters:

rowno

The row position.

Returns:: IlTrue if the row was successfully refreshed and remotely locked. If this is a one-tier table, this member function returns IlTrue without having any side effects.

Reimplemented in IliSQLTable.

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

Refreshes a row.

If this is a two-tier table, this member function re-reads the row from the remote database.

Parameters:

rowno

The row position.

Returns:: IlTrue in case of success and IlFalse otherwise. If this is a one-tier table, this member function returns IlTrue without having any side effects.

Reimplemented in IliSQLTable.

void IliTable::releaseBuffer ( IliTableBuffer * buff )

Releases a table buffer.

Releases a table buffer that has been obtained with the getBuffer member function.

Parameters:

buff

The table buffer.

void IliTable::removeErrorSink ( IliErrorSink * sink )

Removes an error sink from this table.

Here is an example showing how errors can be trapped:

 IliTable* table = ...;
 IliErrorList errors;
 table->addErrorSink(&amp;errors);
 if (!table->deleteRow(10)) {
    IlvPrint("First error: %s", errors.getErrorAt(0).getMessage());
    ...
 }
 table->removeErrorSink(&amp;errors);

Parameters:

sink

The error sink.

void IliTable::removeNamedPropertyManager ( const char * name )

Removes a property manager.

Parameters:

name

The property manager name.

void IliTable::removeProperty	(	IlInt	rowno,
		IlInt	colno,
		const IlvSymbol *	propName
	)

Removes a property from the part of the table.

Note: Accesses the default property manager.

Parameters:

	rowno	The row position.
	colno	The column position.
	propName	The property name.

virtual void IliTable::rowChanged ( IlInt rowno ) [protected, virtual]

Called just after the row at position rowno has changed (that is, when one or more values in the row have changed).

If only one value in the row has changed, it is preferable to call the cellChanged member function instead of rowChanged.

Parameters:

rowno

The row position.

virtual void IliTable::rowDeleted ( IlInt rowno ) [protected, virtual]

Called just after a row has been removed from the table.

Parameters:

rowno

The row position.

virtual void IliTable::rowFetched ( IlInt rowno ) [protected, virtual]

Called just after a new row has been fetched from a remote database and inserted.

In this case the rowInserted member function must also be called.

Parameters:

rowno

The row position.

virtual void IliTable::rowInserted ( IlInt rowno ) [protected, virtual]

Called just after a new row has been inserted.

Parameters:

rowno

The row position.

virtual void IliTable::rowMoved	(	IlInt	src,
		IlInt	dest
	)			`[protected, virtual]`

Called just after a row has moved.

Parameters:

	src	The origin row position.
	dest	The destination row position.

virtual void IliTable::rowToBeChanged ( IlInt rowno ) [protected, virtual]

Called just before the row is changed.

Parameters:

rowno

The row position.

virtual void IliTable::rowToBeDeleted ( IlInt rowno ) [protected, virtual]

Called just before a row is removed from the table.

Parameters:

rowno

The row position.

virtual IlBoolean IliTable::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 in IliSQLTable.

IlBoolean IliTable::set	(	IlInt	rowno,
		IliName	colname,
		const IliValue &	value
	)

Sets a value.

Changes the value in the column named colname of the row positioned at rowno to value.

Parameters:

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

Returns:: IlTrue if successful.

IlBoolean IliTable::set	(	IlInt	rowno,
		IlInt	colno,
		const IliValue &	value
	)

Sets a value.

Changes the value in the column positioned at colno of the row positioned at rowno to value. This member function calls the updateRow member function. Note that if the table is a two-tier table (such as an IliSQLTable object) and if more than one column must be changed at once, calling the set member function twice (once for each column) does not necessarily have the same effect as using a table buffer, assigning the two columns in the table buffer, and calling the updateRow member function once with that table buffer.

Parameters:

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

Returns:: IlTrue if successful.

void IliTable::setColumnForeignDataSourceName	(	IlInt	colno,
		const char *	dsname
	)

Sets the name of the foreign data source for one column.

Parameters:

	colno	The column position.
	dsname	The data source name. If it is an empty string, the column has no defined foreign data source.

void IliTable::setColumnForeignDisplayColumn	(	IlInt	colno,
		const char *	name
	)

Sets the name of the display column in the foreign table.

The column which is used to find a replacement value for the column. The column name is set to a copy.

Parameters:

colno

The column name.

Returns:: The name.

void IliTable::setColumnForeignTable	(	IlInt	colno,
		IliTable *	table
	)

Sets the foreign table of one column.

Parameters:

	colno	The column position.
	table	The foreign table.

void IliTable::setColumnForeignValueColumn	(	IlInt	colno,
		const char *	name
	)

Sets the name of the value column in the foreign table.

The column which the value of the column must be matched with, to yield a display value. The column name is set to a copy.

Parameters:

	colno	The column position.
	name	The column name.

void IliTable::setColumnValueConstrained	(	IlInt	colno,
		IlBoolean	flag
	)

Specifies that the column is constrained to take its values from the domain of the value column of the foreign table.

Parameters:

	colno	The column name.
	flag	The constraint flags.

void IliTable::setCompareFunction	(	IliCompareFunction	fct,
		IlAny	arg = `0`
	)

Defines the function and user data that must be used to compare two rows.

Parameters:

	fct	The function to compare.
	arg	The user data that can be used to compare two rows.

void IliTable::setGadgetHolder ( IlvGadgetHolder * gadHold )

Attaches the table to a gadget holder.

Parameters:

gadHold The gadget holder. If NULL, the table is detached from any gadget holder.

IlBoolean IliTable::setInCache	(	IlInt	rowno,
		IlInt	colno,
		const IliValue &	value
	)

Sets a value.

This member function is similar to the set member function except that it calls updateRowInCache instead of updateRow. The effect is that if this is a two-tier table, the value is changed in the local row cache only.

Parameters:

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

Returns:: IlTrue if successful.

virtual void IliTable::setModified ( IlBoolean flag ) [virtual]

Sets the value of the modified property of the table.

Parameters:

flag

The modified property of the table.

void IliTable::setParameterColumnName	(	IlInt	paramno,
		const char *	colname
	)

Attaches a parameter to one column.

Parameters:

	paramno	The parameter position.
	colname	The column name. If `NULL` or an empty string, the parameter is detached from any column it may be attached to. Value is copied by this member function.

void IliTable::setParameterDataSourceName	(	IlInt	paramno,
		const char *	dsname
	)

Attaches one parameter to one data source.

Parameters:

	paramno	The parameter position.
	dsname	The data source name. If `NULL` or an empty string, the parameter is detached from a data source. The value is copied.

void IliTable::setParameterMaxLength	(	IlInt	paramno,
		IlInt	maxlen
	)

Sets the maximum length allowed for the parameter.

Parameters:

	paramno	The parameter position.
	maxlen	The maximum length allowed.

void IliTable::setParameterName	(	IlInt	paramno,
		const char *	name
	)

Sets a parameter name.

Parameters:

	paramno	The parameter position.
	name	The parameter name.

void IliTable::setParameterType	(	IlInt	paramno,
		const IliDatatype *	type
	)

Sets the type of one parameter.

Parameters:

	paramno	The parameter position.
	type	The parameter type.

void IliTable::setParameterValue	(	IliName	paramName,
		const IliValue &	value
	)

Sets the value of one parameter.

Parameters:

	paramName	The parameter name.
	value	The value.

void IliTable::setParameterValue	(	IlInt	paramno,
		const IliValue &	value
	)

Sets the value of one parameter.

Parameters:

	paramno	The parameter position.
	value	The value.

void IliTable::setProperty	(	IlInt	rowno,
		IlInt	colno,
		const IlvSymbol *	propName,
		const IliValue &	propVal
	)

Sets a property value to a part of the table.

Note: Accesses the default property manager.

Parameters:

	rowno	The row position.
	colno	The column position.
	propName	The property name.
	propVal	The value. `propVal`.

void IliTable::setTransactionManager ( IliTransactionManager * tm )

Changes the transaction that manages this table.

Parameters:

tm The transaction manager. If it is NULL, the table will not be managed by a transaction manager.

void IliTable::setTransactionManagerName ( const char * name )

Changes the transaction that manages this table.

Parameters:

name

The transaction manager name, it is created if it does not already exist.

void IliTable::sortRows	(	const IlInt *	colnoArray,
		IlInt	columnsCount,
		IlInt	fromRow = `0`,
		IlInt	toRow = `-1`,
		IliCompareFunction	fct = `0`,
		IlAny	data = `0`
	)

Sorts a set of rows.

Sorts all rows between position fromRow and position toRow. If toRow equals -1, all rows starting at fromRow are sorted. The sorting order is defined by the colnoArray parameter, which designates an array of columnsCount column positions. Each given column is sorted in the ascending or descending order of the values. The global functions IliAscOrder and IliDescOrder are used to indicate the type of sort. Example:

 // Sorts in the ascending order of column 2
 // Sorts in the descending order of column 3
 static const IlInt columns[] =
 {IliAscOrder (2),
 IliDescOrder (3)  };
 tbl->sortRows(columns, 2);
 void sortRows(IlInt fromRow = 0, IlInt toRow = -1,
          IliCompareFunction fct = 0,
          IlAny userdata = 0);

Parameters:

	colnoArray	The column list.
	columnscount	The column count.
	fromRow	The first row position.
	toRow	The last row position.
	fct	The function to compare. It uses to provide its own function to sort the rows.
	data	The user data that can be used to compare two rows.

virtual void IliTable::tableChanged ( ) [protected, virtual]

Called when the IliTable object has undergone a significant number of changes.

It is much more efficient to call this member function after a number of changes, instead of calling one of the specific member functions (described below) after each change.

virtual IlBoolean IliTable::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 in IliMemoryTable, IliSQLTable, and IliStringsTable.

virtual IlBoolean IliTable::updateRowInCache	(	IlInt	rowno,
		IliTableBuffer *	buff
	)			`[virtual]`

Updates a row.

This virtual member function is similar to the updateRow member function except that it only updates the row in the local row cache if this table is a two-tier table.

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

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

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

Parameters:

output

The output stream.

Reimplemented from IliSchema.

Reimplemented in IliMapTable, IliMemoryTable, IliSQLTable, and IliStringsTable.

void IliTable::writeTable ( IL_STDPREF ostream & output ) const

Writes the definition of the table to an output stream, in a form suitable to be read back by the ReadTable static member function.

This member function can write any subclass of IliTable.

Parameters:

output

The output stream.

Rogue Wave ViewsData Access Package API Reference Guide

IliTable Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Function Documentation

Rogue Wave Views
Data Access Package API Reference Guide