TCustomBufDataset.Locate function

Declaration

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

Arguments

Function result

True if a record was found that matches the search condition.

Description

Locate is an overridden Boolean function used to locate the first record with fields that match the specified search values. Locate implements the method defined in the ancestor class.

KeyFields is a delimited list of field names searched in the method. The delimiter character is ';' (Semicolon).

KeyValues is a Variant type with the field values required for the specified KeyFields. When KeyFields contains a single field name, KeyValues can be represented using the same data type as the field value. When KeyFields contains more than one field name, it is a Variant array.

Options is a TLocateOptions parameter that indicates the locate options enabled in the method. Options can contain zero (0) or more values from the TLocateOption enumeration.

Locate calls the inherited method to ensure that the dataset supports bi-directional navigation. An Exception is raised if the UniDirectional property contains True. The value in the Active property is checked to ensure that the dataset has been opened. An Exception is raised if Active contains False. No actions are performed in the method when IsEmpty returns True.

Locate initializes an internal TDBCompareStruct instance that is used when searching field values using the SearchFields and Options arguments. The search is performed by using the Filter feature; the filter fields are set to the values in KeyValues. Each record in the dataset is visited and the OnFilterRecord event is signalled to determine if the record meets the Filter criteria. The search ends when a record is found that matches the search values.

The record position is changed to the marching record, or positioned at the end-of-file when no matching record is found.

The return value is True if a record was located that matched the search values.

See also

• TDataset.Locate
• TCustomBufDataset.UniDirectional
• TDataset.Active
• TDataset.Filter
• TDataset.OnFilterRecord
• TLocateOptions
• TDBCompareStruct