FireDAC.Comp.DataSet.TFDDataSet.Locate

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

function Locate(const AKeyFields: string; const AKeyValues: Variant;
AOptions: TLocateOptions = []): Boolean; override;

C++

virtual bool __fastcall Locate(const System::UnicodeString AKeyFields, const System::Variant &AKeyValues, Data::Db::TLocateOptions AOptions = Data::Db::TLocateOptions() );

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 record with the specified field values and makes it current.

Use Locate to search the 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 that contains the values to match 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. 

AOptions is a set of search modes for string fields. If AOptions contains loCaseInsensitive, then Locate ignores case when matching fields. If AOptions contains loPartialKey, then the AKeyValues parameter can contain partial strings. 

If a matching record is found, then this record becomes current and Locate returns True

To optimize record searching, the application can set up a client index. The index will be used by Locate 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 loCaseInsensitive, or the index is build without soNoCase and AOptions does not include loCaseInsensitive.
  • The index is active and is current.

Example

CustTable.IndexFieldNames := 'ID';
if CustTable.Locate('ID', 1001, []) then
  CustTable.Delete
else
  ShowMessage('The customer with ID=1001 is not found');

See Also