_DBSkip( ) API Library Routine

_DBSkip( ) moves the record pointer in the specified work area the specified number of records.

long _DBSkip(int workarea, long distance)
int workarea;               /* Work area. */
long distance;               /* Number of records to skip. */

Remarks

_DBSkip( ) respects the active index and filter expressions, just like the Visual FoxPro SKIP command. The distance may be positive or negative. _DBSkip( ) returns the record number of the new record.

Use _DBStatus( ) to check for end of file and beginning of file conditions. If you try to skip forward from the end of the file, or skip backwards from the beginning of the file, _DBSkip( ) returns a negative integer whose absolute value is a Visual FoxPro error number.

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 works like the Visual FoxPro SKIP command.

Visual FoxPro Code

SET LIBRARY TO DBSKIP  
ON ERROR DO expectError
DO CreateTest
USE
= DBSKIP(1)       && _Error() called: no DBF in use
USE test
GO TOP
= DBSKIP(-1)
= DBSKIP(-1)      && _Error() called: at top of file
GO BOTT
= DBSKIP(1)
= DBSKIP(1)      && _Error() called: at bottom of file
ON ERROR

PROCEDURE expectError
   ? "ERROR: " + MESSAGE()
RETURN

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 *pblk)
{
   int RetCode;

   if ((RetCode = _DBSkip(-1, pblk->p[0].val.ev_long)) < 0) {
      _PutStr("\nError encountered in example program.");
      _Error(-RetCode);  // _DBSkip() returns negative error code
   }
   _RetInt(RetCode, 10);
}

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

See Also

_DBRecCount( ) API Library Routine | _DBRecNo( ) API Library Routine | Accessing the Visual FoxPro API | _DBStatus( ) API Library Routine