KEYMATCH( ) Function

See Also

Searches an index tag or index file for an index key.

Syntax

KEYMATCH(eIndexKey [, nIndexNumber [, nWorkArea | cTableAlias]])

Returns

Logical

Arguments

eIndexKey

Specifies the index key that KEYMATCH( ) searches for. The index keys in an index file or index tag are determined by the index expression. An index expression is specified when an index file or index tag is created with INDEX. KEY( ) and SYS(14) can be used to return the index expressions for index files and index tags. For more information on creating index files, index expressions, and index keys, see INDEX.

If you don't include any of the optional parameters, KEYMATCH( ) searches the master index file or master index tag for the index key you specify. If a master index file or index tag isn't in effect (for example, you've issued SET ORDER TO without any parameters to place the table in physical record order), Visual FoxPro generates an error message.

nIndexNumber

Specifies which index file or index tag is searched. nIndexNumber is typically an integer that starts at 1 and is increased by 1 to search additional index tags.

If nIndexNumber is 1, the master single-entry .idx index file or master index tag (if one is present) is searched.

As nIndexNumber increases, subsequent tags in the structural compound index (if one is present) are searched. The tags are searched in the order in which the tags were created in the structural compound index.

As nIndexNumber continues to increase and all the tags in the structural compound index have been searched, tags in any open independent compound indexes are then searched. The tags are searched in the order in which the tags were created in the independent compound indexes.

An error message is generated if nIndexNumber is greater than the total number of open single-entry .idx files and structural compound and independent compound index tags.

nWorkArea | cTableAlias

Searches index files or tags open in another work area. nWorkArea specifies the work area number and cTableAlias specifies the table alias. If you omit the work area and alias, KEYMATCH( ) searches index files or tags open for the table in the current work area.

If no table has the alias you specify, Visual FoxPro generates an error message.

Remarks

KEYMATCH( ) searches an index tag or index file for a specific index key and returns true (.T.) if the index key is found; otherwise, KEYMATCH( ) returns false (.F.). KEYMATCH( ) can be used to prevent duplicate index keys.

KEYMATCH( ) returns the record pointer to the record on which it was originally positioned before KEYMATCH( ) was issued.