Apollo VCL Components > Apollo VCL Component Reference > TApolloTable > TApolloTable Methods

Declaration

function ApolloLocate( sExpression: String;

bBackwards: WordBool;

bContinue: WordBool ): LongInt;

Description

Initializes or continues a record location command.

$image\tip.gif$ To avoid a naming conflict with the TDataSet.Locate method, the old TApollo.Locate method has been renamed to ApolloLocate in this release.

Parameters

sExpression: An xBase expression that will evaluate to a logical conclusion that describes the data you are looking for. Such as:

'upper(trim(country)) = "GERMANY"'

If you wish to clear the locate expression, pass this parameter as a NULL string ('' or #0).

If starting a new locate sequence, the new expression will overwrite the old. It is not necessary to clear it first.

bBackwards: Pass this parameter as False if you wish to search in the forward direction from the current record position. Pass it as True if you want to search backwards from the current record position.

bContinue: Pass this parameter as False when the locate sequence is initiated. Pass it as True if you are continuing a search. Note that if you are continuing a search you must not pass sExpression as a NULL string ('' or #0). A NULL value in sExpression clears the locate expression contained in the current work area and returns with a zero (not found).

Return Value

The record number of the first record that satisfies the locate expression. If no record is found, a zero is returned and the record pointer in the table is positioned at the record that was active before the locate was attempted.

Delphi Example

// Begin Search for LAST field equaling 'Smith'

ApTbl.ApolloLocate( 'LAST="Smith"', False, False );

// Continue Search for LAST field equaling 'Smith'

ApTbl.ApolloLocate( 'LAST="Smith"', False, True );

// Move back up to last find

ApTbl.ApolloLocate( 'LAST="Smith"', True, True );

C++Builder Example

// Begin Search for LAST field equaling 'Smith'

ApTbl->ApolloLocate( "LAST='Smith'", false, false );

// Continue Search for LAST field equaling 'Smith'

ApTbl->ApolloLocate( "LAST='Smith'", false, true );

// Move back up to last find

ApTbl->ApolloLocate( "LAST='Smith'", true, true );