_DBSeek( ) API Library Routine

Searches an indexed table in the current work area for the first record whose index key matches the value val.

long _DBSeek(Value FAR *val)
Value FAR *val;            /* Sought value. */

Remarks

If _DBSeek( ) finds a matching record, it moves the record pointer to the matching record and returns the record number. The match must be exact unless you SET EXACT is set to OFF. If _DBSeek( ) doesn't find a matching record, it returns 0. If no match is found and SET NEAR is set to ON, the record pointer is positioned immediately after the closest matching record. If SET NEAR is set to OFF, the record pointer is positioned at the end of the file.

If the matching record is an added buffered record that has not been committed, the value returned by _DBSeek( ) differs from the value returned by RECNO( ). RECNO( ) returns a negative value, indicating the record is buffered. The value returned by _DBSeek( ) is one greater than the number of records in the table plus the number of buffered records before the matching record.

If an error occurs, _DBSeek( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

When seeking a numeric field, val must be set to ev_type 'N', even if that field has no decimal digits. If val has an ev_type of 'I', _DBSeek( ) will return the internal error number -302, "Data type mismatch".

For more information on how to create an API library and integrate it with Visual FoxPro, see Accessing the Visual FoxPro API.

Example

The following example performs a seek on whatever index controls the order of the table open in the current work area. Note the "?" in the FoxInfo structure is required because the type of index expression is not known.

Visual FoxPro Code

SET LIBRARY TO DBSEEK  
DO CreateTest

INDEX ON ABC TAG ABC
SET ORDER TO TAG ABC
= DBSEEK("This is record 3")  && seeks ABC = "This is record 3"
LIST NEXT 1
USE

PROCEDURE CreateTest
   CREATE TABLE test (ABC C(20))
   APPEND BLANK
   REPLACE ABC WITH "This is record 1"
   APPEND BLANK
   REPLACE ABC WITH "This is record 2"
   APPEND BLANK
   REPLACE ABC WITH "This is record 3"
   APPEND BLANK
   REPLACE ABC WITH "This is record 4"
   GO TOP
RETURN

C Code

#include <pro_ext.h>

FAR Example(ParamBlk FAR *parm)
{
   _DBSeek(&parm->p[0].val);
}

FoxInfo myFoxInfo[] = {
   {"DBSEEK", (FPFI) Example, 1, "?"},
};
FoxTable _FoxTable = {
   (FoxTable FAR *) 0, sizeof(myFoxInfo)/sizeof(FoxInfo), myFoxInfo
};

See Also

_DBRecCount( ) API Library Routine | _DBRecNo( ) API Library Routine | _DBSkip( ) API Library Routine | SET EXACT Command