KeyMatch()

This function lets you check whether a particular key value already exists in an index. It's sort of a manual way to do what primary and candidate indexes do automatically. KEYMATCH() was one of the functions added for dBASE compatibility in FoxPro 2.6 that's actually somewhat useful.

Usage

lIsItThere = KEYMATCH( uKeyValue [, nWhichKey 
                      [, nWorkArea | cAlias ] ] )

Parameter	Value	Meaning
uKeyValue	Expression	The value to check for.
nWhichKey	Numeric	The index to check. See CANDIDATE() for an explanation of index numbers.
nWorkArea	Numeric	Check the key for the table open in the specified work area.
nWorkArea	Omitted	If cAlias is also omitted, check in the table open in the current work area.
cAlias	Character	Check the key for the table open with the specified alias.
cAlias	Omitted	If nWorkArea is also omitted, check in the table open in the current work area.
lIsItThere	.T.	A record exists with the specified key value for the specified index.
lIsItThere	.F.	No record has the specified key value for the specified index.

This function actually sounds more useful than it is. Two factors keep it from being something we use all the time.First, you have to specify tags by number, not by name. We don't want to know the number of an index—the name of the tag is enough for us. This isn't as limiting as it seems, since you can use TAGNO() to convert from tag name to tag number, but it's just one more step.The second factor is the really important one. Though it sounds like it shouldn't, KEYMATCH() moves the record pointer. The record pointer is restored to the original position at the end of the function call, but the fact that it moves at all makes KEYMATCH() useless in the situation where we want to use it—to check in a row-buffered cursor whether a particular item has been entered already. The movement of the record pointer commits the record we're adding—definitely not what we want to have happen. Fortunately, the INDEXSEEK() function added in VFP 6 does exactly what we want. In older versions, we'll stick to USEing the table again in another work area to check for duplicates.

Example

USE Employee ORDER Last_Name
? KEYMATCH("KING")                        && Returns .T.
? KEYMATCH("    10", TAGNO("Employee_I")) && Returns .T.
SET ORDER TO
? KEYMATCH("KING", 2)                     && Returns .T.
? KEYMATCH("GATES", 2)                    && Returns .F.