FireDAC.Comp.DataSet.TFDDataSet.LocateEx
Delphi
function LocateEx(const AKeyFields: string; const AKeyValues: Variant;
AOptions: TFDDataSetLocateOptions = []; ApRecordIndex: PInteger = nil): Boolean; overload; virtual;
function LocateEx(const AExpression: string;
AOptions: TFDDataSetLocateOptions = []; ApRecordIndex: PInteger = nil): Boolean; overload; virtual;
C++
virtual bool __fastcall LocateEx(const System::UnicodeString AKeyFields, const System::Variant &AKeyValues, TFDDataSetLocateOptions AOptions = TFDDataSetLocateOptions() , System::PInteger ApRecordIndex = (System::PInteger)(0x0))/* overload */;
virtual bool __fastcall LocateEx(const System::UnicodeString AExpression, TFDDataSetLocateOptions AOptions = TFDDataSetLocateOptions() , System::PInteger ApRecordIndex = (System::PInteger)(0x0))/* overload */;
Contents
Properties
Type | Visibility | Source | Unit | Parent |
---|---|---|---|---|
function | public | FireDAC.Comp.DataSet.pas FireDAC.Comp.DataSet.hpp |
FireDAC.Comp.DataSet | TFDDataSet |
Description
Searches the dataset for a specified record by its field values or predicate expressions, makes the record focused, and returns its index.
This method is overloaded:
- Use the first LocateEx overloaded method to search a dataset for a record with the specified field values and make it current, if found.
AKeyFields
is a semicolon-separated list of field names through which to search.AKeyValues
is a Variant containing the values to match to the key fields. IfAKeyFields
contains a single field name, thenAKeyValues
is a simple value. IfAKeyFields
contains more field names, thenAKeyValues
is a variant array, where items correspond to the key fields. - Use the second LocateEx overloaded method to search the dataset for a record that meets the predicate expression and makes it current, if found.
AExpression
is a string containing the predicate expression through which to search. The expression cannot contain aggregating functions, likeSUM
,COUNT
, and the predicate must be evaluating to True or to False. FireDAC supports extended expression syntax.
AOptions
is a set that optionally specifies additional search modes:
Option |
Description |
---|---|
|
If included, then LocateEx ignores case when matching string values. |
|
If included, then the expression can specify incomplete strings for string values comparison. |
|
If included, then LocateEx starts searching from the next record in the dataset, otherwise from the beginning. |
|
If included, then LocateEx searches for the record in backward direction, otherwise in forward direction. |
|
If included, then LocateEx does not:
|
|
If included, then FetchAll is not called. The search is performed in already fetched records. |
If a matching record is found, then LocateEx returns True. The found record becomes current if lxoCheckOnly
is not specified. The variable pointed by ApRecordIndex
receives the index of the found record if ApRecordIndex
is not nil.
To optimize record searching, the application can set up a client index. The index is used by LocateEx if the following conditions are met:
- The index field list has as prefix
AKeyFields
fields. - The index is built with the
soNoCase
option andAOptions
includeslxoCaseInsensitive
. Otherwise, the index is built withoutsoNoCase
andAOptions
does not includelxoCaseInsensitive
. - The index is active and is current.
Example
procedure TForm1.BtnFindClick(ASender: TObject);
begin
if not CustTable.LocateEx('COMPANY', 'AMCO', [lxoCaseInsensitive]) then
ShowMessage('The customer from AMCO company is not found');
end;
procedure TForm1.BtnNextClick(ASender: TObject);
begin
if not CustTable.LocateEx('COMPANY', 'AMCO', [lxoCaseInsensitive, lxoFromCurrent]) then
ShowMessage('The customer from AMCO company is not found');
end;