Delphi Programming
This page is intended as a supplement to the official documentation on Delphi programming. CodeGear is in the process of putting the Delphi documentation on the Web. Once they have done so, this page will link to the relevant page in the official documentation.
This article is a stub.
Please help enhance the Delphi Programming Wiki by expanding it.
see the VCL Documentation Guidelines for an overview on doc pages



Definition (Delphi 6, 2010):

TLocateOptions = set of TLocateOption;

TLocateOptions is a set of TLocateOption.

Locate options are used to control how the TDataset Locate method matches it's results. The two options are:

  • loCaseInsensitive: Matching does not take case-sensitivity into account.
  • loPartialKey: Looks at only part of the database field to match data i.e. looking for "SMO" with this option would return a match for "SMOKED HADDOCK" or SMOTE" or "SMOULDER".

Technical Comments[]

Locate is used to search a dataset (such as a TTable or a TQuery) for a record that corresponds to certain conditions. It returns True if it finds a matching record, and it makes that record the "current" record. Otherwise it returns False.

Delphi's help gives the following syntax for Locate:

function Locate(const KeyFields: string; const KeyValues: Variant; Options: TLocateOptions): Boolean;

KeyFields is a string, containing one field n ame or several field names separated by semicolons.

Suppose that we have a table Products.DB with the following fields:

id   - alfanumeric - size 2 code - alfanumeric - size 2 size - integer KeyFields could be 'id' or 'id;code' or 'id;code;size'.

KeyValues is a "variant", containing the value(s) to search for. A variant can be of any type: string, integer, boolean,...

If there is only one field in KeyFields, then KeyValues simply contains the value to search for. Examples:

  Found := Product.Locate('id', '12', []);   Found := Product.Locate('size', 3,  []); If there are several fields in KeyFields, then KeyValues should be a "variant array". It is allowed to construct that variant array "on the fly" using the VarArrayOf function. Example:

  Product.Locate('id;code', VarArrayOf(['12', 'AB']), []); Options is a "set" that optionally specifies additional search conditions when your condition contains one or more *string* fields: - if Options contains "loCaseInsensitive", then there is no difference between upper case and lower case; - if Options contains "loPartialKey", then also *partial* matches for string fields are located; - if Options is empty, or if KeyFields does not include any string fields, Options is ignored.


To search for all products with an 'id' starting with '2':

  Found := Product.Locate('id',   '2', [loPartialKey]);  

  To search for all products with a 'code' starting with 'a' or 'A':

  Found := Product.Locate('code',   'a', [loCaseInsensitive, loPartialKey]);


[] or [loCaseInsensitive] or [loPartialKey] or [loCaseInsensitive, loPartialKey] :)

See Also[]

(Please provide links to items specifically related to this item.)

User Comments/Tips[]

KateH: ADO Components 2010 only checks for loPartialKey, and will always set loCaseInsensitive in Locate, even if [] is passed through.

(Please leave your name with your comment.)