TCustomBufDataset.Lookup function

Declaration

function Lookup(const KeyFields: string; const KeyValues: Variant; 
 const ResultFields: string): Variant; override

Arguments

Function result

Variant array with values for the result fields.

Description

Lookup is an overridden Variant function used to get values from the first record with fields that match the specified search values. Lookup re-implements the method defined in the ancestor class. Lookup allows searching one or more fields for corresponding values, and returning a set of field values from the matching record.

KeyFields is a delimited list of field names searched in the method. The delimiter character is ';' (Semicolon). The following example would represent the fields LASTNAME and FIRSTNAME:

'LASTNAME; FIRSTNAME'
          

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. Using the previous values for KeyFields, the following would represent the values for 'JOHN SMITH':

VarArrayOf([ 'SMITH', 'JOHN' ])
          

ResultFields contains one or more field names which determine the field values to include in the return value for the method. Like KeyFields, it is a delimited list of field names using ';' (Semicolon) as the delimiter character.

The return value is a Variant type that contains a value for each of the field names specified in the ResultFields argument. When a matching record is located, the return value is a Variant array. The return value is Null if a record is not found matching the specified KeyValues in its KeyFields.

var
  AVarValues: Variant;
  ABufDataset: TBufDataset;

// ...

AVarValues := ABufDataset.Lookup('lastname;firstname',
  VarArrayOf(['SMITH', 'JOHN']), 'lastname;firstname;birthdate;emailaddress');

if not VarIsNull(AVarValues) then
  DoSomethingWith(AVarValues)
else
  WriteLn('No records match the search criteria');
          

Lookup does not change the record position in the dataset. A temporary TBookmark is used to record the current record in the dataset. The record position is restored prior to exiting from the method.

Lookup calls the Locate method to search records in the dataset using the KeyFields and KeyValues arguments. The Locate method may raise an Exception if the dataset is configured for UniDirectional access or when it is not Active.

See also

• TCustomBufDataset.Locate
• TDataset.Active
• TCustomBufDataset.UniDirectional