class Rowset

The data that results from an SQL statement in a Query object.

Syntax

These objects are created automatically by the query.

Properties

The following tables list the properties, events, and methods of the Rowset class. For details on each property, click on the property below.

Property	Default	Description
autoEdit	true	Whether the rowset automatically switches to Edit mode when a change is made in a dataLinked component.
autoLockChildRows	true	Whether locking a parent row also automatically locks its child rows.
autoNullFields	true	Whether empty fields will assume a null value, or be filled with blanks, zero or, in the case of logical fields, false.
baseClassName	ROWSET	Identifies the object as an instance of the Rowset class
className	(ROWSET)	Identifies the object as an instance of a custom class. When no custom class exists, defaults to baseClassName
codePage	0	Returns a number indicating the current code page associated with a table
endOfSet		Whether the row cursor is at either end of the set
exactMatch	true	Whether rowset searches use a partial string match or an exact string match
fields	Object	Array of field objects in row
filter	Empty string	Filter SQL expression
filterOptions	Match length and case	Enum designating how the filter expression should be applied
handle		BDE cursor handle
indexName	Empty string	Active index tag
languageDriver	Empty string	Returns a character string indicating the name of the language driver currently being used
live	true	Whether the data can be modified
locateOptions	Match length and case	Enum designating how the locate expression should be applied
lockType	0 - Automatic	Enum determinating whether or not explicit locks can be released by a call to rowset.save()
masterChild	Constrained	In a master-detail link, enum specifying whether or not the child table’s rowset is constrained.
masterFields	Empty string	Field list for master-detail link
masterRowset	null	Reference to master Rowset object
modified	false	Whether the row has changed
name	Empty string	The name of custom object
navigateByMaster	false	Whether to syncronize movement in a linked-detail rowset to match that of it's master.
navigateMaster	false	Whether to move the row position in a master rowset when a linked-detail rowset reaches endofSet.
notifyControls	true	Whether to automatically update dataLinked controls
parent	null	Query object that contains the Rowset object
state	0	Enum that indicates the rowset's current mode
tableDriver	Empty string	Returns a character string indicating the name of the driver currently being used to access a table
tableLevel	0	Returns an integer indicating the version of the current local table
tableName	Empty string	Returns a character string indicating the name of the table the current rowset is based on
tempTable	false	Returns a logical (True/.T.) when the current table (referenced by tableName) is a temporary table
Event	Parameters	Description
beforeRelease		Before the object is released
canAbandon		When abandon( ) is called; return value allows or disallows abandoning of row
canAppend		When beginAppend( ) is called; return value allows or disallows start of append
canDelete		When delete( ) is called; return value allows or disallows deletion
canEdit		When beginEdit( ) is called; return value allows or disallows switch to Edit mode
canGetRow		When attempting to read row; return value acts as an additional filter
canNavigate		When attempting row navigation; return value allows or disallows navigation
canSave		When save( ) is called; return value allows or disallows saving of row
onAbandon		After successful abandon( )
onAppend		After successful beginAppend( )
onDelete		After successful delete( )
onEdit		After successful beginEdit( )
onNavigate	<method expN>, <rows expN>	After rowset navigation
onSave		After successful save( )
Method	Parameters	Description
abandon( )		Abandons pending changes to current row
applyFilter( )		Applies filter set during rowset’s Filter mode
applyLocate( )	[<locate expC>]	Finds first row that matches specified criteria
atFirst( )		Returns true if current row is first row in rowset
atLast( )		Returns true if current row is last row in rowset
beginAppend( )		Starts append of new row
beginEdit( )		Puts rowset in Edit mode, allowing changes to fields
beginFilter( )		Puts rowset in Filter mode, allowing entry of filter criteria
beginLocate( )		Puts rowset in Locate mode, allowing entry of search criteria
bookmark( )		Returns bookmark for current row
bookmarksEqual( )	<bookmark 1> [,<bookmark 2>]	Compares two bookmarks or one bookmark with current row to see if they refer to same row
clearFilter( )		Disables filter created by applyFilter( ) and clears filter property
clearRange( )		Disables constraint created by setRange( )
count( )		Returns number of rows in rowset, honoring filters
delete( )		Deletes current row
findKey( )	<key exp>	Finds the row with the exact matching key value
findKeyNearest( )	<key exp>	Finds the row with the nearest matching key value
first( )		Moves row cursor to first row in set
flush( )		Commits the rowset buffer to disk
goto( )	<bookmark>	Moves row cursor to specified row
isRowLocked( )		Determines if the current row, in the current session, is locked
isSetLocked( )		Determines if the current rowset, in the current session, is locked
last( )		Moves row cursor to last row in set
locateNext( )	[<rows expN>]	Finds other rows that match search criteria
lockRow( )		Locks current row
lockSet( )		Locks entire set
next( )	[<rows expN>]	Navigates to adjacent rows
refresh( )		Refreshes entire rowset
refreshControls( )		Refreshes dataLinked controls
refreshRow( )		Refreshes current row only
rowCount ( )		Returns logical row count if known
rowNo( )		Returns logical row number if known
save( )		Saves current row
setRange( )	<key exp> or <startKey exp> \| null ,<endKey exp> \| null	Constrains the rowset to those rows whose key field values falls within a range
unlock( )		Releases locks set by lockRow( ) and lockSet( )

Description

A Rowset object represents a set of rows that results from a query. It maintains a cursor that points to one of the rows in the set, which is considered the current row, and a buffer to manage the contents of that row. The row cursor may also point outside the set, either before the first row or after the last row, in which case it is considered to be at the end-of-set. Each row contains fields from one or more tables. These fields are represented by an array of Field objects that is represented by the rowset’s fields property. For a simple query like the following, which selects all the fields from a single table with no conditions, the rowset represents all the data in the table:

select * from CUSTOMER

As the cursor moves from row to row, you can access the fields in that row.

A Query object always has a rowset property, but that rowset is not open and usable and does not contain any fields until the query has been successfully activated. Setting the Query object’s active property to true opens the query and executes the SQL statement stored in the sql property. If the SQL statement fails, for example the statement is misspelled or the named table is missing, an error is generated and the active property remains false. If the SQL statement executes but does not generate any rows, the active property is true and the endOfSet property of the query’s rowset is true. Otherwise the endOfSet property is false, and the rowset contains the resulting rows.

Once the rowset has been opened, you can do any of the following:

Navigate the rowset; that is, move the row cursor

Filter and search for rows

Add, modify, and delete rows

Explicitly lock individual rows or the entire set

Get information about the rowset, including row cursor’s current position

The individual Field objects in a rowset’s fields array property may be dataLinked to controls on a form. As the row cursor is navigated from row to row, the controls will be updated with the current row’s values, unless the rowset’s notifyControls property is set to false. Changing the values shown in the controls will change the value property of the dataLinked Field objects. You may also directly modify the value property of the Field objects. All of the values are maintained in the row buffer.

Rowset objects support master-detail linking. Navigation and updates in the master rowset change the set of rows in the detail rowset. The detail rowset is controlled by changing the key range of an existing index in the detail rowset. The masterRowset and masterFields properties are set in the detail rowset. This allows a single master rowset to control any number of detail rowsets.

When a query opens, its rowset is in Browse mode. By default, a rowset’s autoEdit property is true, which means that its fields are changeable through dataLinked controls. Typing a destructive key in a dataLinked control automatically attempts to switch the rowset into Edit mode. By setting autoEdit to false, the rowset is read-only, and the beginEdit( ) method must be called to switch to Edit mode and allow editing. autoEdit has no effect on assignments to the value of a field; they are always allowed.

The rowset’s modified property indicates whether any changes have been made to the current row. Changes made to the row buffer are not written until the save( ) method is called. However, even after save( ) has been called, no attempt is made to save data if the rowset’s modified property is false. This architecture lets you define row-validation code once in the canSave event handler that is called whenever it is needed and only when it is needed.

In addition to normal data access through Browse and Edit modes, the rowset supports three other modes: Append, Filter, and Locate, which are initiated by beginAppend( ), beginFilter( ), and beginLocate( ) respectively. At the beginning of all three modes, the row buffer is disassociated from whatever row it was buffering and cleared. This allows the entry of field values typed into dataLinked controls or assigned directly to the value property. In Append mode, these new values are saved as a new row if the row buffer is written. In Filter mode, executing an applyFilter( ) causes the non-blank field values to be used as criteria for filtering rows, showing only those that match. In Locate mode, calling applyLocate( ) causes the non-blank field values to be used as criteria to search for matching rows. In all three modes, using the field values cancels that mode. Also, calling the abandon( ) method causes the rowset to revert back to Browse mode without using the values.

You can easily implement filter-by-form and locate-by-form features with the Filter and Locate modes. Instead of using Filter mode, you can assign an SQL expression directly to the rowset’s filter property. The rowset’s canGetRow event will filter rows based on any dBL code, not just an SQL expression, and can be used instead of or in addition to Filter mode and the filter property. You can also use applyLocate( ) without starting Locate mode first by passing an SQL expression to find the first row for which the expression is true.

Any row-selection criteria—from the WHERE clause of the query’s SQL SELECT statement, the key range enforced by a master-detail link, or a filter—is actively enforced. applyLocate( ) will not find a row that does not match the criteria. When appending a new row or changing an existing row, if the fields in the row are written such that the row no longer matches the selection criteria, that row becomes out-of-set, and the row cursor moves to the next row, or to the end-of-set if there are no more matching rows. To see the out-of-set row, you must remove or modify the selection criteria to allow that row.

Row and set locking support varies among different table types. The Standard (DBF and DB) tables fully support locking, as do some SQL servers. For servers that do not support true locks, the Borland Database Engine emulates optimistic locking. Any lock request is assumed to succeed. Later, when the actual attempt to change the data occurs, if the data has changed since the lock attempt, an error occurs.

Any attempt to change the data in a row, like typing a letter in a dataLinked Entryfield control, causes an automatic row lock to be attempted. If that row is already locked, the lock is retried up to the number of times specified by the session’s lockRetryCount property; if after those attempts the lock is unsuccessful, the change does not take. If the automatic lock is successful, the lock remains until navigation off the locked row occurs or the row is saved or abandoned; then the lock is automatically removed.