Accessors for class IliTable

Properties

fetchCompleted
parametersCount
properties
readOnly
rowsCount
selectDone
transactionManager
transactionManagerName

Methods

addErrorSink
appendRow
appendRowInCache
applyQueryMode
at
clearRows
deleteRow
deleteRowInCache
fetchAll
getBuffer
getNamedPropertyManager
getNamedPropertyManagerCount
getParameter
getParameterAt
getPropertyManagerNameAt
insertRow
insertRowInCache
isQueryModeSupported
makeQueryTable
moveRow
moveRowInCache
newNamedPropertyManager
refreshAndLockRow
refreshRow
removeErrorSink
removeNamedPropertyManager
select
updateRow
updateRowInCache

Description

The IliTable class defines objects capable of managing an ordered collection of rows. Each of these rows conforms to the same schema. The IliTable class is abstract in the sense that each time you will have a table, its class will be a subclass of IliTable.

One- and Two-Tier Tables

Some subclasses of IliTable, such as IliMemoryTable, 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.
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 that the table is mapped to at any particular time. The purpose of this cache is to reduce communication overhead with the remote 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.
With a two-tier table, remote rows may be fetched and stored in the row cache, as follows:

At select time
This is called the "immediate fetch policy". In this case, the row cache always contains all the rows that result from calling the select method and the rowsCount property is always accurate.
Later, as rows are needed
This is called the "as needed fetch policy". The rows are either fetched explicitly by calling the fetchAll method or implicitly by referencing a row whose index is greater than the last row in the local row cache.

The exact policy that a two-tier will implement ("immediate" or "as needed" fetch) depends on the subclass of IliTable that you are using. The IliSQLTable class, for example, can implement both policies.

Row Locking

When using a two-tier table, it may occur that remote rows are changed in the database server by other users between the time they were fetched and the current time.
The refreshRow allows you to re-fetch a given row so that the values in the row cache become more up-to-date.
Two-tier tables may support a remote locking facility. In such cases, the refreshAndLockRow method allows you to re-read a given row and simultaneously lock it in the remote database so that other users cannot modify or delete anymore.
Note that one-tier table objects, such as the IliMemoryTable class, do not support the notion of remote rows, neither do they let you lock rows.

Table Buffer and Row Management

The row management methods are based on the concept of a table buffer. (See the IliTableBuffer class). A table buffer is an object that has the same structure as a table's row. It contains one value for each column of the schema.
When you want to insert a new row into a table, you first obtain a table buffer, fill in the values in the table buffer, and call one the insertRow or the appendRow methods:

	// inserting a row in a table
	var buffer = table.getBuffer();
	buffer.ENAME.value = "Smith";
	buffer.DEPT.value = "Marketing";
	table.appendRow(buffer);

You change the values in an existing row as follows:

	// updating a row in a table
	var buffer = table.getBuffer();
	var rowno = 10;
	buffer.rowToBuffer(rowno);
	buffer.SALARY.value = buffer.SALARY.value + bonus;
	table.updateRow(rowno, buffer);

Alternatively, it is possible to change the value in a row using the set method defined by the IliTableColumn class:

	// updating a row in a table
	var rowno = 10;
	table.SALARY.set(rowno, table.SALARY.at(rowno) + bonus);

Error Catching

Any errors that may occur when a row management method is called are forwarded to error sinks. An error sink is either a Rogue Wave Views Script function that you provide or an IliErrorList object. It lets you catch errors as they occur.
Here is an example that shows how errors are caught:

	// catching errors
	function MyErrorHandler(msg) {
	   writlen(msg.prettyMessage);
	}
	
	function DoIt(table) {
	   var sink = new IliObserver(MyErrorHandler);
	   table.addErrorSink(sink);
	   var last = table.rowsCount - 1;
	   var rowno;
	   for (rowo = last; --rowno; rowno >= 0) {
	      if (table.QTY.at(rowno) < 0) 
	        table.deleteRow(rowno);
	   }
	   table.removeErrorSink(sink);
	}

Row Indices

Many row management methods take a rowno parameter. This parameter designates a row by giving its position (starting from 0) in the local row cache. In effect, the notion of row position is relative to the local row cache and it usually has no meaning with regard to the remote database.

Row Cache Explicit Management

Some of the methods that manipulate rows exist in two versions, for example updateRow and updateRowInCache.
With a one-tier table, both of these methods have the same effect: the row managed by the table is updated. But with a two-tier table, the updateRow method updates the row in the remote database as well as in the local row cache. Whereas the updateRowInCache method only updates the local row cache leaving the remote row unaffected. This can be useful to manage locally computed columns along with columns retrieved from a database.

Query Mode

Some IliTable subclasses support a query mode in which the table is replaced by a special memory table where the end user can enter conditions. When query mode is applied, the IliTable synthesizes a query that retrieves rows matching the conditions entered by the user in query mode.

Type Name Description Notes

Boolean fetchCompleted If this is a two-tier table, this property contains true if all remote rows that resulted from the execution of the last call to the select method have been fetched and stored in the local row cache. read-only

Int parametersCount Contains the number of parameters defined for this table. read-only

IliTablePropertyManager properties Contains the default property manager for this table. read-only

Boolean readOnly Contains true if the table is read-only.

Int rowsCount Contains the number of rows in the local row cache. For a one-tier table, this is the total rows count. For a two-tier table, this is the number of rows that have been fetched from the remote database until now. It may be less than the total rows count, which is unknown unless the fetchAll method is called or all rows have otherwise been fetched. read-only

Boolean selectDone If this is a two-tier table, this property contains true if the select method was called at least once since the table was created or read (recreated) from a resource file. Otherwise, for a one-tier table, this property is always false. read-only

IliTransactionManager transactionManager Contains the transaction manager managing this table or null if the table is not managed by a transaction manager. Initially, this property is null. Read-only

String transactionManagerName Contains the name of the transaction manager that manages the table. It contains null if the table is not managed by a transaction manager or if it is managed by an anonymous transaction manager. A new transaction manager is implicitly created when a name is assigned to this property and no existing transaction manager has this name.

Void addErrorSink(Object sink) Adds an error sink to the table. When an error occurs, it will be forwarded to this error sink.
The sink parameter can be either:

An IliErrorList object
var errList = new IliErrorList table.addErrorSink(errList);

An IliObserver object whose func property contains a Rogue Wave Views Script function having the following signature: fct(IliErrorMessage msg)
function OnError(errorMsg) { writeln(errorMsg.prettyMessage); } table.addErrorSink(new IliObserver(OnError));

Int appendRow(IliTableBuffer buffer) Inserts a new row whose values are given in the buffer parameter. The row is inserted after the last existing row and its index is returned if successful. The value of -1 is returned if it fails. See the insertRow method for more information on inserting into a table.

Int appendRowInCache(IliTableBuffer buffer) This method is similar to the appendRow method except that it only appends the row in the local row cache.

Variant at(Int rowno, Int colno) Returns the value in the row positioned at rowno for the column positioned at colno. The exact type of the return value depends on the column data type. The following expressions are equivalent:

table.at(rowno, table.EMPNAME.index) table.EMPNAME.at(rowno)

Boolean applyQueryMode(IliTable queryTable) If query mode is supported, this method applies the query specified by the conditions contained in the =queryTable= parameter, which is expected to be a table obtained by calling the makeQueryTable method. This method returns true if successful.

Void clearRows() Deletes all rows in the local row cache.

Boolean deleteRow(Int rowno) Deletes the row at position rowno. Returns true if successful and false if for any reason the row could not be deleted.
With a two-tier table, the row is deleted from the remote database as well as from the local row cache.

Boolean deleteRowInCache(Int rowno) This method is similar to the deleteRow method except that it only deletes the row from the local row cache.

Int fetchAll() Fetches all remaining rows and stores them in the local row cache. This method returns the number of rows effectively fetched.

IliTableBuffer getBuffer() Returns a new table buffer suitable to be used in conjunction with the updateRow, insertRow, updateRowInCache, and insertRowInCache methods.

IliTablePropertyManager getNamedPropertyManager(String name) Returns the property manager named name if it exists and null otherwise.

Int getNamedPropertyManagerCount() Returns the number of named property managers.

IliParameter getParameter(String paramname) Returns the parameter named paramname. The null value is returned if no such object exists.

IliParameter getParameterAt(Int paramno) Returns the parameter positioned at paramno which must be >= 0 and < parametersCount. The null value is returned if paramno is out of bounds.

String getPropertyManagerNameAt(Int idx) Returns the name of the named property manager positioned at idx or null if idx < 0 or idx >= getNamedPropertyManagerCount().

Boolean insertRow(Int rowno, IliTableBuffer buffer) Inserts a new row at position rowno with values taken from the buffer parameter. Only the modified values in buffer are used to initialize the row. (See IliTableBufferValue::isModified method.) The other values are replaced by null values. With a two-tier table, the row is inserted in the remote database as well as in the local cache. Constraints such as non nullable columns and primary key columns are first checked and the insert is carried out only if these constraints are satisfied. This method returns true if the row was successfully inserted and false otherwise.

Boolean insertRowInCache(Int rowno, IliTableBuffer buffer) This method is similar to the insertRow method except that it only inserts the row in the local row cache.

Boolean isQueryModeSupported() Returns true if the table supports query mode.

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

Boolean moveRow(Int from, Int to) Moves the row at position from to the position to. This method returns true if the row was successfully moved and false otherwise. With a two-tier table, the row is deleted from the remote database as well as from the local row cache.

Boolean moveRowInCache(Int from, Int to) This method is similar to the moveRow method except that it moves only the row in the local row cache.

IliTablePropertyManager newNamedPropertyManager(String name) Creates and returns a new named property manager.

Boolean refreshAndLockRow(Int rowno) If this is a two-tier table, this method re-reads the row positioned at rowno 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 the IliTable class. It is left to the discretion of subclasses (see the IliSQLTable class).This method returns true if the row was successfully refreshed and remotely locked.

Boolean refreshRow(Int rowno) If this is a two-tier table, this method re-reads the row positioned at rowno from the remote database. Returns true if successful and false otherwise.

Void removeErrorSink(Object sink) Removes an error sink.

Void removeNamedPropertyManager(String name) Removes the property manager named name.

Boolean select() If for a two-tier table, this method first clears the local row cache and queries the database to obtain a new set of rows. Whether these rows are immediately fetched and stored in the local row cache or if they are kept in the remote database for later retrieval is left to the discretion of the subclass of IliTable being used. It then returns true if successful and false otherwise. If for a one-tier table, this method does nothing and returns false.

Boolean updateRow(Int rowno, IliTableBuffer buffer) Changes the row at position rowno to the values in the buffer parameter. Only the modified values in the buffer are used to change the row, other values are left unchanged. (See IliTableBufferValue::isModified method.) With a two-tier table, the remote row is updated as well as the row in the local cache. Constraints such as non nullable columns and primary key columns are first checked and the update is carried out only if these constraints are satisfied. This method returns true if the row was successfully updated and false otherwise.

Boolean updateRowInCache(Int rowno, IliTableBuffer buffer) This method is similar to the updateRow method except that it only updates the row in the local row cache.

Type	Name	Description	Notes
`Boolean`	`fetchCompleted`	If this is a two-tier table, this property contains `true` if all remote rows that resulted from the execution of the last call to the `select` method have been fetched and stored in the local row cache.	read-only
`Int`	`parametersCount`	Contains the number of parameters defined for this table.	read-only
`IliTablePropertyManager`	`properties`	Contains the default property manager for this table.	read-only
`Boolean`	`readOnly`	Contains `true` if the table is read-only.
`Int`	`rowsCount`	Contains the number of rows in the local row cache. For a one-tier table, this is the total rows count. For a two-tier table, this is the number of rows that have been fetched from the remote database until now. It may be less than the total rows count, which is unknown unless the `fetchAll` method is called or all rows have otherwise been fetched.	read-only
`Boolean`	`selectDone`	If this is a two-tier table, this property contains `true` if the `select` method was called at least once since the table was created or read (recreated) from a resource file. Otherwise, for a one-tier table, this property is always `false`.	read-only
`IliTransactionManager`	`transactionManager`	Contains the transaction manager managing this table or `null` if the table is not managed by a transaction manager. Initially, this property is `null`.	Read-only
`String`	`transactionManagerName`	Contains the name of the transaction manager that manages the table. It contains `null` if the table is not managed by a transaction manager or if it is managed by an anonymous transaction manager. A new transaction manager is implicitly created when a name is assigned to this property and no existing transaction manager has this name.
`Void`	`addErrorSink(Object sink)`	Adds an error sink to the table. When an error occurs, it will be forwarded to this error sink. The `sink` parameter can be either: An `IliErrorList` object var errList = new IliErrorList table.addErrorSink(errList); An `IliObserver` object whose `func` property contains a Rogue Wave Views Script function having the following signature: `fct(IliErrorMessage msg`) function OnError(errorMsg) { writeln(errorMsg.prettyMessage); } table.addErrorSink(new IliObserver(OnError));
`Int`	`appendRow(IliTableBuffer buffer)`	Inserts a new row whose values are given in the `buffer` parameter. The row is inserted after the last existing row and its index is returned if successful. The value of `-1` is returned if it fails. See the `insertRow` method for more information on inserting into a table.
`Int`	`appendRowInCache(IliTableBuffer buffer)`	This method is similar to the `appendRow` method except that it only appends the row in the local row cache.
`Variant`	`at(Int rowno, Int colno)`	Returns the value in the row positioned at `rowno` for the column positioned at `colno`. The exact type of the return value depends on the column data type. The following expressions are equivalent: table.at(rowno, table.EMPNAME.index) table.EMPNAME.at(rowno)
`Boolean`	`applyQueryMode(IliTable queryTable)`	If query mode is supported, this method applies the query specified by the conditions contained in the =queryTable= parameter, which is expected to be a table obtained by calling the `makeQueryTable` method. This method returns `true` if successful.
`Void`	`clearRows()`	Deletes all rows in the local row cache.
`Boolean`	`deleteRow(Int rowno)`	Deletes the row at position `rowno`. Returns `true` if successful and `false` if for any reason the row could not be deleted. With a two-tier table, the row is deleted from the remote database as well as from the local row cache.
`Boolean`	`deleteRowInCache(Int rowno)`	This method is similar to the `deleteRow` method except that it only deletes the row from the local row cache.
`Int`	`fetchAll()`	Fetches all remaining rows and stores them in the local row cache. This method returns the number of rows effectively fetched.
`IliTableBuffer`	`getBuffer()`	Returns a new table buffer suitable to be used in conjunction with the `updateRow`, `insertRow`, `updateRowInCache,` and `insertRowInCache` methods.
`IliTablePropertyManager`	`getNamedPropertyManager(String name)`	Returns the property manager named `name` if it exists and `null` otherwise.
`Int`	`getNamedPropertyManagerCount()`	Returns the number of named property managers.
`IliParameter`	`getParameter(String paramname)`	Returns the parameter named `paramname`. The `null` value is returned if no such object exists.
`IliParameter`	`getParameterAt(Int paramno)`	Returns the parameter positioned at `paramno` which must be `>= 0` and `< parametersCount`. The `null` value is returned if `paramno` is out of bounds.
`String`	`getPropertyManagerNameAt(Int idx)`	Returns the name of the named property manager positioned at `idx` or `null` if `idx < 0` or `idx >= getNamedPropertyManagerCount()`.
`Boolean`	`insertRow(Int rowno, IliTableBuffer buffer)`	Inserts a new row at position `rowno` with values taken from the `buffer` parameter. Only the modified values in buffer are used to initialize the row. (See `IliTableBufferValue::isModified` method.) The other values are replaced by `null` values. With a two-tier table, the row is inserted in the remote database as well as in the local cache. Constraints such as non nullable columns and primary key columns are first checked and the insert is carried out only if these constraints are satisfied. This method returns `true` if the row was successfully inserted and `false` otherwise.
`Boolean`	`insertRowInCache(Int rowno, IliTableBuffer buffer)`	This method is similar to the `insertRow` method except that it only inserts the row in the local row cache.
`Boolean`	`isQueryModeSupported()`	Returns `true` if the table supports query mode.
`IliTable`	`makeQueryTable()`	If query mode is supported, this method creates and returns a memory table having the same number of columns as the original table. The returned memory table columns are all of the String type.
`Boolean`	`moveRow(Int from, Int to)`	Moves the row at position `from` to the position `to`. This method returns `true` if the row was successfully moved and `false` otherwise. With a two-tier table, the row is deleted from the remote database as well as from the local row cache.
`Boolean`	`moveRowInCache(Int from, Int to)`	This method is similar to the `moveRow` method except that it moves only the row in the local row cache.
`IliTablePropertyManager`	`newNamedPropertyManager(String name)`	Creates and returns a new named property manager.
`Boolean`	`refreshAndLockRow(Int rowno)`	If this is a two-tier table, this method re-reads the row positioned at `rowno` 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 the `IliTable` class. It is left to the discretion of subclasses (see the `IliSQLTable` class).This method returns `true` if the row was successfully refreshed and remotely locked.
`Boolean`	`refreshRow(Int rowno)`	If this is a two-tier table, this method re-reads the row positioned at `rowno` from the remote database. Returns `true` if successful and `false` otherwise.
`Void`	`removeErrorSink(Object sink)`	Removes an error sink.
`Void`	`removeNamedPropertyManager(String name)`	Removes the property manager named `name`.
`Boolean`	`select()`	If for a two-tier table, this method first clears the local row cache and queries the database to obtain a new set of rows. Whether these rows are immediately fetched and stored in the local row cache or if they are kept in the remote database for later retrieval is left to the discretion of the subclass of `IliTable` being used. It then returns `true` if successful and `false` otherwise. If for a one-tier table, this method does nothing and returns `false`.
`Boolean`	`updateRow(Int rowno, IliTableBuffer buffer)`	Changes the row at position `rowno` to the values in the `buffer` parameter. Only the modified values in the buffer are used to change the row, other values are left unchanged. (See `IliTableBufferValue::isModified` method.) With a two-tier table, the remote row is updated as well as the row in the local cache. Constraints such as non nullable columns and primary key columns are first checked and the update is carried out only if these constraints are satisfied. This method returns `true` if the row was successfully updated and `false` otherwise.
`Boolean`	`updateRowInCache(Int rowno, IliTableBuffer buffer)`	This method is similar to the `updateRow` method except that it only updates the row in the local row cache.