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

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

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.