TCustomClientDataSet.Locate Method

Searches the dataset for a specified record and makes that record current.

Pascal

function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean; override;

C++

virtual __fastcall Boolean Locate(const AnsiString KeyFields, const Variant KeyValues, TLocateOptions Options);

Description

Call Locate to search a dataset for a specific record and position the cursor on it. KeyFields is a string containing a semicolon-delimited list of field names on which to search.

KeyValues is a Variant containing the values to match in the key fields. If KeyFields lists a single field, KeyValues represents the search value for that field. If KeyFields lists multiple fields, pass a Variant array as the KeyValues parameter. In Delphi, you can construct a variant array on the fly using the VarArrayOf routine. For example:

Copy Code

with CustTable do
  Locate('Company;Contact;Phone', VarArrayOf(['Sight Diver', 'P', '831-431-1000']), [loPartialKey]);

Copy Code

TLocateOptions Opts;
Opts.Clear();
Opts << loPartialKey;
Variant locvalues[3];
locvalues[0] = Variant("Sight Diver");
locvalues[1] = Variant("P");
locvalues[2] = Variant("831-431-1000");

Copy Code

CustTable->Locate("Company;Contact;Phone", VarArrayOf(locvalues, 2), Opts);

Options is a set that optionally specifies additional search latitude when searching on string fields. If Options contains the loCaseInsensitive setting, then Locate ignores case when matching fields. If Options contains the loPartialKey setting, then the KeyValues parameter can specify incomplete strings for field values. (For example, in the previous statement, the Contact field would match any record where Contact begins with 'P'). If Options is an empty set, or if the KeyFields are not string fields, Options is ignored.

Locate returns true if it finds a matching record, and makes that record the current one. Otherwise Locate returns false.