Navigating data in client datasets
If an application uses standard data-aware controls, then a user can navigate through a client dataset's records using the built-in behavior of those controls. You can also navigate programmatically through records using standard dataset methods such as First, Last, Next, and Prior. For more information about these methods, see "Navigating datasets" on page 16-8.
Also inherited from TDataSet are the Locate and Lookup methods, which search for a particular record based on the values of specified fields. These methods are described in "Searching datasets" on page 16-14.
Client datasets implement the standard bookmark capabilities introduced in TDataSet for marking and navigating to specific records. For more information about bookmarking, see "Marking and returning to records" on page 16-12.
In addition to these methods introduced by TDataSet, client datasets introduce a number of additional navigation methods that take advantage of the way they store and index in-memory records.
For example, instead of using bookmarks, with the overhead of allocating and freeing the memory to store them, client datasets can position the cursor at any specific record using the RecNo property. While other datasets may use RecNo to determine the record number of the current record, client datasets can also set RecNo to a particular record number to make that record the current one.
However, the most powerful method introduced by TClientDataSet is the Goto and Find search methods that search for a record based on indexed fields. By explicitly using indexes that you define for the client dataset, client datasets can improve over the searching performance provided by the Locate and Lookup methods.
The following table summarizes the six related Goto and Find methods an application can use to search for a record:
Table 20.1 Index-based search methods
Method Purpose
EditKey Preserves the current contents of the search key buffer and puts the dataset into dsSetKey state so your application can modify existing search criteria prior to executing a search.
FindKey Combines the SetKey and GotoKey methods in a single method.
FindNearest Combines the SetKey and GotoNearest methods in a single method.
GotoKey Searches for the first record in a dataset that exactly matches the search criteria, and moves the cursor to that record if one is found.
GotoNearest Searches on string-based fields for the closest match to a record based on partial key values, and moves the cursor to that record.
SetKey Clears the search key buffer and puts the dataset into dsSetKey state so your application can specify new search criteria prior to executing a search.
GotoKey and FindKey are boolean functions that, if successful, move the cursor to a matching record and return True. If the search is unsuccessful, the cursor is not moved, and these functions return False.
GotoNearest and FindNearest always reposition the cursor either on the first exact match found or, if no match is found, on the first record that is greater than the specified search criteria.
Specifying the index to use for searching
Before using the Goto and Find search methods, you must define the index, or key, that is used to speed the search. If the index has already been created for your client dataset, you must make that index current using the IndexName property. For example, if a client dataset has an index named "CityIndex" on which you want to search for a value, you must set the IndexName property to "CityIndex":
ClientDataSet1.Close; ClientDataSet1.IndexName := 'Citylndex'; ClientDataSet1.Open; ClientDataSet1.SetKey; ClientDataSet1['City'] := Edit1.Text; ClientDataSet1.GotoNearest;
Instead of specifying an index name, you can list fields to use as a key in the IndexFieldNames property.
For more information on creating and using indexes in client datasets, see "Sorting and indexing" on page 20-16.
Executing a search with Goto methods
To execute a search using Goto methods, follow these general steps:
1 Specify the index to use for the search (as described above).
2 Open the client dataset.
3 Put the dataset in dsSetKey state with SetKey.
4 Specify the value(s) to search on in the Fields property. Fields is a TFields object, which maintains an indexed list of field components you can access by specifying ordinal numbers corresponding to columns. The first column number in a dataset is 0.
5 Search for and move to the first matching record found with GotoKey or GotoNearest.
For example, the following code, attached to a button's OnClick event, moves to the first record where the first field in the index has a value that exactly matches the text in an edit box:
procedure TSearchDemo.SearchExactClick(Sender: TObject); begin
- SetKey;
- Fields[0].AsString := Editl.Text; if not ClientDataSetl.GotoKey then ShowMessage('Record not found');
end;
GotoNearest is similar. It searches for the nearest match to a partial field value. It can be used only for string fields. For example,
ClientDataSetl.SetKey; ClientDataSetl.Fields[0].AsString := 'Sm'; ClientDataSetl.GotoNearest;
If a record exists with "Sm" as the first two characters of the first indexed field's value, the cursor is positioned on that record. Otherwise, the position of the cursor does not change and GotoNearest returns False.
Executing a search with Find methods
The Find methods do the same thing as the Goto methods, except that you do not need to explicitly put the dataset in dsSetKey state to specify the key field values on which to search. To execute a search using Find methods, follow these general steps:
1 Specify the index to use for the search (as described above).
2 Open the client dataset.
3 Search for and move to the first or nearest record with FindKey or FindNearest. Both methods take a single parameter, a comma-delimited list of field values, where each value corresponds to an indexed column in the underlying table.
Note FindNearest can only be used for string fields.
Specifying the current record after a successful search
By default, a successful search positions the cursor on the first record that matches the search criteria. If you prefer, you can set the KeyExclusive property to True to position the cursor on the next record after the first matching record.
By default, KeyExclusive is False, meaning that successful searches position the cursor on the first matching record.
Searching on partial keys
If a client dataset has more than one key column, and you want to search for values in a subset of that key, set KeyFieldCount to the number of columns on which you are searching. For example, if the client dataset's current index has three columns, and you want to search for values using just the first column, set KeyFieldCount to 1.
For client datasets with multiple-column keys, you can search only for values in contiguous columns, beginning with the first. For example, for a three-column key you can search for values in the first column, the first and second, or the first, second, and third, but not just the first and third.
Repeating or extending a search
Each time you call SetKey or FindKey it clears any previous values in the Fields property. If you want to repeat a search using previously set fields, or you want to add to the fields used in a search, call EditKey in place of SetKey and FindKey. For example, suppose you have already executed a search based on the City field of the "CityIndex" index. Suppose further that "CityIndex" includes both the City and Company fields. To find a record with a specified company name in a specified city, use the following code:
ClientDataSet1.KeyFieldCount := 2; ClientDataSet1.EditKey; ClientDataSet1['Company'] := Edit2.Text; ClientDataSet1.GotoNearest;
Post a comment