This documentation is archived and is not being maintained.

CRecordset::Move 

Moves the current record pointer within the recordset, either forward or backward.


virtual void Move( 
   long nRows, 
   WORD wFetchType = SQL_FETCH_RELATIVE  
);

Parameters

nRows

The number of rows to move forward or backward. Positive values move forward, toward the end of the recordset. Negative values move backward, toward the beginning.

wFetchType

Determines the rowset that Move will fetch. For details, see Remarks.

If you pass a value of 0 for nRows, Move refreshes the current record; Move will end any current AddNew or Edit mode, and will restore the current record's value before AddNew or Edit was called.

NoteNote

When you move through a recordset, you cannot skip deleted records. See CRecordset::IsDeleted for more information. When you open a CRecordset with the skipDeletedRecords option set, Move asserts if the nRows parameter is 0. This behavior prevents the refresh of rows that are deleted by other client applications using the same data. See the dwOption parameter in Open for a description of skipDeletedRecords.

Move repositions the recordset by rowsets. Based on the values for nRows and wFetchType, Move fetches the appropriate rowset and then makes the first record in that rowset the current record. If you have not implemented bulk row fetching, then the rowset size is always 1. When fetching a rowset, Move directly calls the CheckRowsetError member function to handle any errors resulting from the fetch.

Depending on the values you pass, Move is equivalent to other CRecordset member functions. In particular, the value of wFetchType may indicate a member function that is more intuitive and often the preferred method for moving the current record.

The following table lists the possible values for wFetchType, the rowset that Move will fetch based on wFetchType and nRows, and any equivalent member function corresponding to wFetchType.

wFetchType Fetched rowset Equivalent member function

SQL_FETCH_RELATIVE (the default value)

The rowset starting nRows row(s) from the first row in the current rowset.

 

SQL_FETCH_NEXT

The next rowset; nRows is ignored.

MoveNext

SQL_FETCH_PRIOR

The previous rowset; nRows is ignored.

MovePrev

SQL_FETCH_FIRST

The first rowset in the recordset; nRows is ignored.

MoveFirst

SQL_FETCH_LAST

The last complete rowset in the recordset; nRows is ignored.

MoveLast

SQL_FETCH_ABSOLUTE

If nRows > 0, the rowset starting nRows row(s) from the beginning of the recordset. If nRows < 0, the rowset starting nRows row(s) from the end of the recordset. If nRows = 0, then a beginning-of-file (BOF) condition is returned.

SetAbsolutePosition

SQL_FETCH_BOOKMARK

The rowset starting at the row whose bookmark value corresponds to nRows.

SetBookmark

NoteNote

For foward-only recordsets, Move is only valid with a value of SQL_FETCH_NEXT for wFetchType.

Caution noteCaution

Calling Move throws an exception if the recordset has no records. To determine whether the recordset has any records, call IsBOF and IsEOF.

NoteNote

If you have scrolled past the beginning or end of the recordset (IsBOF or IsEOF returns nonzero), calling a Move function will possibly throw a CDBException. For example, if IsEOF returns nonzero and IsBOF does not, then MoveNext will throw an exception, but MovePrev will not.

NoteNote

If you call Move while the current record is being updated or added, the updates are lost without warning.

For more information about recordset navigation, see the articles Recordset: Scrolling (ODBC) and Recordset: Bookmarks and Absolute Positions (ODBC). For more information about bulk row fetching, see the article Recordset: Fetching Records in Bulk (ODBC). For related information, see the ODBC API function SQLExtendedFetch in the Platform SDK.

This method can throw exceptions of type CDBException* and CMemoryException*.

// rs is a CRecordset or a 
// CRecordset-derived object

// Change the rowset size to 5
rs.SetRowsetSize( 5 );

// Move to the first record
// in the recordset
rs.MoveFirst( );

// Move to the sixth record
rs.Move( 5 );
// Other equivalent ways to
// move to the sixth record:
// rs.Move( 6, SQL_FETCH_ABSOLUTE );
// rs.SetAbsolutePosition( 6 );
// In this case, the sixth record is
// the first record in the next rowset,
// so the following are also equivalent:
// rs.Move( 1, SQL_FETCH_NEXT );
// rs.MoveNext( );
Show: