TADDataSet.LookupEx Method (string, Variant, string, TADDataSetLocateOptions, PInteger)

Searches the dataset for a record with specified key field values and returns result field values.

Group

Links

TADDataSet Class, TADDataSet Members, uADCompDataSet Namespace, public, See Also

Parameters	Description
const AKeyFields: string	A list of fields to match.
const AKeyValues: Variant	A variant value / variant array of values to search.
const AResultFields: string	A list of fields which values to return.
AOptions: TADDataSetLocateOptions = []	A set of search modes.
ApRecordIndex: PInteger = nil	An optional pointer to variable, receiving record index. Is nil by default.

Returns

If record is found, the values from the fields specified in AResultFields. Otherwise - Null.

Description

Use Lookup to search the dataset for a record with specified key field values and return result field values without changing the current position in the dataset.

AKeyFields is a semicolon separated list of field names on 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 few field names, then AKeyValues is a variant array, where items correspond to the key fields.

AResultFields is a semicolon separated list of field names, which values to return. If record is found, Lookup returns a variant array containing the values from the fields specified in AResultFields. Otherwise - Null.

AOptions is a set that optionally specifies additional search modes:

Option	Description
lxoCaseInsensitive	If included, then the LookupEx ignores case when matching string values.
lxoPartialKey	If included, then the AKeyValues can specify incomplete strings for string values comparision.
lxoFromCurrent	If included, then the LookupEx starts searching from the next after current record in dataset, otherwise from beginning.
lxoBackward	If included, then the LookupEx searches for record in backward direction, otherwise in forward direction.
lxoCheckOnly	If included, then LookupEx will not: finish editing mode, if it is.
lxoNoFetchAll	If included, then FetchAll will be not called. So, the search is performed in already fetched records.

If matching record is found and ApRecordIndex is not nil, then pointed variable receives index of found record.

To optimize record searching, application can setup client index. The index will be used by the LookupEx, if following conditions are met:

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

Syntax

function LookupEx(const AKeyFields: string; const AKeyValues: Variant; const AResultFields: string; AOptions: TADDataSetLocateOptions = []; ApRecordIndex: PInteger = nil): Variant; virtual; overload;