FireDAC.Comp.DataSet.TFDDataSet.LocateEx

• Up to Parent: TFDDataSet

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 */;

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. If AKeyFields contains a single field name, then AKeyValues is a simple value. If AKeyFields contains more field names, then AKeyValues 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, like SUM, 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
lxoCaseInsensitive	If included, then LocateEx ignores case when matching string values.
lxoPartialKey	If included, then the expression can specify incomplete strings for string values comparison.
lxoFromCurrent	If included, then LocateEx starts searching from the next record in the dataset, otherwise from the beginning.
lxoBackward	If included, then LocateEx searches for the record in backward direction, otherwise in forward direction.
lxoCheckOnly	If included, then LocateEx does not: Change the current position. Fire BeforeScroll / AfterScroll events. Finish editing mode.
lxoNoFetchAll	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 and AOptions includes lxoCaseInsensitive. Otherwise, the index is built without soNoCase and AOptions does not include lxoCaseInsensitive.
• 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;

See Also

• Finding a Record
• FireDAC.Comp.DataSet.TFDDataSet.Locate
• FireDAC.Comp.DataSet.TFDDataSet.LookupEx
• FireDAC.Comp.DataSet.TFDDataSet.Indexes
• FireDAC.Comp.DataSet.TFDDataSet.IndexFieldNames
• FireDAC.Comp.DataSet.TFDDataSet.IndexName