Difference between revisions of "locate"
From Lazarus wiki
Jump to navigationJump to search (Added example, layout, tip to use sql) |
m (→See also: Fixed wiki markup) |
||
| (6 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{ | + | {{locate}} |
==Definition== | ==Definition== | ||
| + | |||
Unit: FreePascal, unit '''db''' | Unit: FreePascal, unit '''db''' | ||
| − | <syntaxhighlight> | + | <syntaxhighlight lang=pascal> |
function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean; override; | function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean; override; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 11: | Line 12: | ||
==Description== | ==Description== | ||
| + | |||
'''locate''' looks for a record in the dataset where the specified search values for the specified fields match. If found, the function returns true and the cursor position/current record moves to that record. | '''locate''' looks for a record in the dataset where the specified search values for the specified fields match. If found, the function returns true and the cursor position/current record moves to that record. | ||
| Line 17: | Line 19: | ||
KeyValue can be a variant or a variant array and the number of items must match the number of fields specified in KeyFields. | KeyValue can be a variant or a variant array and the number of items must match the number of fields specified in KeyFields. | ||
| − | Search options can be | + | Search options can be: |
| + | |||
* loCaseInsensitive: ignore upper case/lower case differences when searching | * loCaseInsensitive: ignore upper case/lower case differences when searching | ||
| − | * loPartialKey: match partial finds (instead of the complete key) | + | * loPartialKey: match partial finds (instead of the complete key). Note: this only works for string-type fields, not for number/date/currency etc fields where this option is ignored. |
{{Note|Locate is only implemented in non-unidirectional datasets, i.e. you must be able to move back and forwards through the dataset.}} | {{Note|Locate is only implemented in non-unidirectional datasets, i.e. you must be able to move back and forwards through the dataset.}} | ||
| Line 25: | Line 28: | ||
{{Note|Locate and lookup act at low level inside a dataset to search for records. Often it is more efficient to filter/limit what gets into the dataset in the first place, e.g. using SQL WHERE clauses.}} | {{Note|Locate and lookup act at low level inside a dataset to search for records. Often it is more efficient to filter/limit what gets into the dataset in the first place, e.g. using SQL WHERE clauses.}} | ||
| − | == | + | ==Examples== |
| − | + | ||
| − | + | Using a TDBF dataset and looking for 'di Angelo', 'Di Angelo' etc in a field called | |
| + | LASTNAME: | ||
| + | |||
| + | <syntaxhighlight lang=pascal> | ||
uses dbf, db | uses dbf, db | ||
... | ... | ||
| − | |||
| − | |||
if MyDBF.Locate('LASTNAME','di Angelo',[loCaseInsensitive])then | if MyDBF.Locate('LASTNAME','di Angelo',[loCaseInsensitive])then | ||
writeln('Found record.'); | writeln('Found record.'); | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | Using multiple fields to find a record. | ||
| + | |||
| + | Note: you have to add Variants to the uses clause. | ||
| + | |||
| + | <syntaxhighlight lang=pascal> | ||
| + | uses Variants; | ||
| + | .. | ||
| + | procedure LocateMyRecord; | ||
| + | var | ||
| + | aCityID, aCountryID: integer; | ||
| + | begin | ||
| + | if Locate('city_id;country_id', VarArrayOf([aCityID, aCountryID]), []) then | ||
| + | begin | ||
| + | DoSomething; | ||
| + | end; | ||
| + | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==See also== | ==See also== | ||
| − | * [http://delphi.about.com/od/database/l/aa052901a.htm | + | * [[lookup]] |
| − | + | * [http://delphi.about.com/od/database/l/aa052901a.htm Description of how to use locate with Delphi] | |
| − | |||
| − | |||
Latest revision as of 03:07, 19 February 2020
│
English (en) │
français (fr) │
Definition
Unit: FreePascal, unit db
function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean; override;
Official documentation: none
Description
locate looks for a record in the dataset where the specified search values for the specified fields match. If found, the function returns true and the cursor position/current record moves to that record.
KeyFields can be a single field name or a semicolon-separated list of fields.
KeyValue can be a variant or a variant array and the number of items must match the number of fields specified in KeyFields.
Search options can be:
- loCaseInsensitive: ignore upper case/lower case differences when searching
- loPartialKey: match partial finds (instead of the complete key). Note: this only works for string-type fields, not for number/date/currency etc fields where this option is ignored.
Note: Locate is only implemented in non-unidirectional datasets, i.e. you must be able to move back and forwards through the dataset. Note: Locate and lookup act at low level inside a dataset to search for records. Often it is more efficient to filter/limit what gets into the dataset in the first place, e.g. using SQL WHERE clauses.Examples
Using a TDBF dataset and looking for 'di Angelo', 'Di Angelo' etc in a field called LASTNAME:
uses dbf, db
...
if MyDBF.Locate('LASTNAME','di Angelo',[loCaseInsensitive])then
writeln('Found record.');
Using multiple fields to find a record.
Note: you have to add Variants to the uses clause.
uses Variants;
..
procedure LocateMyRecord;
var
aCityID, aCountryID: integer;
begin
if Locate('city_id;country_id', VarArrayOf([aCityID, aCountryID]), []) then
begin
DoSomething;
end;
end;
