applyLocate( )

Topic group Related topics Example

Finds the first row that matches specified criteria.

Syntax

<oRef>.applyLocate([<SQL condition expC>])

<oRef>

The rowset you want to search for the specified criteria.

<SQL condition expC>

An SQL condition expression.

Property of

Rowset

Description

Rowset objects support a Locate mode in which values can be assigned to Field objects and then used to find rows in a rowset that contains matching values. beginLocate( ) puts the rowset in Locate mode and applyLocate( ) finds the first matching row. locateNext( ) finds other matching rows. Because dataLinked controls on forms write to the value properties of Field objects, a call to those three methods are all you need to implement a search-by-form feature in your application.

applyLocate( ) moves the row cursor to the first row that matches the criteria set during the rowset’s Locate mode.

You may also use applyLocate( ) without calling beginLocate( ) first to put the rowset in Locate mode: call applyLocate( ) with a parameter string that contains an SQL condition expression. Doing so finds the first row that matches the condition. (Calling applyLocate( ) with a parameter when the rowset is in Locate mode discards any field values entered during Locate mode and uses the specified condition expression only to find a match.)

Calling applyLocate( ) with a parameter will attempt an implicit save if the rowset is not in Locate mode and the rowset’s modified property is true. If the implicit save fails, because the canSave returns false or any other reason, the search is not attempted.

If a search is attempted, applyLocate( ) returns true or false to indicate if a match is found. onNavigate always fires after a search attempt, either on the first matching row, or the current row if the search failed.

applyLocate( ) will use available indexes to find a match more quickly. When searching on the current index specified by the rowset’s indexName property, you may find the findKey( ) and findKeyNearest( ) methods more convenient and direct.