CRecordset::Move

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

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.

Remarks

Call this member function to move the current record pointer within the recordset, either forward or backward. 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.

Note When moving through a recordset, deleted records may not be skipped. See the IsDeleted member function for details.

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

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

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

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.

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) in Visual C++ Programmer’s Guide. For more information about bulk row fetching, see the article Recordset: Fetching Records in Bulk (ODBC) in Visual C++ Programmer’s Guide. For related information, see the ODBC API function SQLExtendedFetch in the ODBC SDK Programmer's Reference.

Example

// 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( );

CRecordset Overview | Class Members | Hierarchy Chart