FireDAC.Comp.Client.TFDTable.LookupEx

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

function LookupEx(const AExpression: String; const AResultFields: String;  AOptions: TFDDataSetLocateOptions = []; ApRecordIndex: PInteger = nil): Variant; override;
function LookupEx(const AKeyFields: String; const AKeyValues: Variant;  const AResultFields: String; AOptions: TFDDataSetLocateOptions = []; ApRecordIndex: PInteger = nil): Variant; override;

C++

virtual System::Variant __fastcall LookupEx(const System::UnicodeString AExpression, const System::UnicodeString AResultFields, Firedac::Comp::Dataset::TFDDataSetLocateOptions AOptions = Firedac::Comp::Dataset::TFDDataSetLocateOptions() , System::PInteger ApRecordIndex = (System::PInteger)(0x0))/* overload */;
virtual System::Variant __fastcall LookupEx(const System::UnicodeString AKeyFields, const System::Variant &AKeyValues, const System::UnicodeString AResultFields, Firedac::Comp::Dataset::TFDDataSetLocateOptions AOptions = Firedac::Comp::Dataset::TFDDataSetLocateOptions() , System::PInteger ApRecordIndex = (System::PInteger)(0x0))/* overload */;

Properties

Type Visibility Source Unit Parent
function public
FireDAC.Comp.Client.pas
FireDAC.Comp.Client.hpp
FireDAC.Comp.Client TFDTable

Description

Searches the dataset for a set of specified key field values or a predicate expression for a record and returns the resulted field values.

FireDAC.Comp.Client.TFDTable.LookupEx inherits from FireDAC.Comp.DataSet.TFDDataSet.LookupEx. All content below this line refers to FireDAC.Comp.DataSet.TFDDataSet.LookupEx.

Searches the dataset for a set of specified key field values or a predicate expression for a record and returns the resulted field values.

This method is overloaded:

  • Use the first LookupEx overloaded method to search a dataset for a record with the specified key field values. 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 LookupEx overloaded method to search a dataset for a record in which the specified predicate expression evaluates to True. AExpression is a string containing the predicate expression through which to search. The expression cannot contain aggregating functions such as SUM, COUNT and it is evaluated to True or False. FireDAC supports extended expression syntax.

If a matching record is found,LookupEx returns a variant array containing the values from the fields specified in AResultFields. Otherwise, it returns null. 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 the client index. The index will be used by the LookupEx if the following conditions are met:

  • The index field list has as prefix AKeyFields fields.
  • The index is build without the soNoCase option.
  • The index is active and is the current one.

AOptions is a set that optionally specifies additional search modes:

Option

Description

lxoCaseInsensitive

If included, then LookupEx ignores case when matching string values.

lxoPartialKey

If included, then AKeyValues can specify incomplete strings for string comparison.

lxoFromCurrent

If included, then LookupEx starts searching from the next after current record in the dataset, otherwise from the beginning.

lxoBackward

If included, then LookupEx searches for the record in backward direction, otherwise in forward direction.

lxoCheckOnly

If included, then LookupEx does not:

  • Finish editing mode, if it is the case.

lxoNoFetchAll

If included, then FetchAll is not called. Therefore, the search is performed in the already fetched records.

Example

procedure TForm1.Button1Click(Sender: TObject);
var
  V: Variant;
  C: Integer;
  A: String;
begin
  V := FDQuery1.LookupEx('Company = ''Blue Sports'' and State = ''OR''', 'CustNo;Addr1', [lxoCaseInsensitive]);
  if not VarIsNull(V) then begin
    C := V[0];
    A := V[1];
    ShowMessage(IntToStr(C) + #13#10 + A);
  end
  else
    ShowMessage('The record is not found !');
end;

See Also