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.
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.
Note
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. |
|
SQL_FETCH_PRIOR |
The previous rowset; nRows is ignored. |
|
SQL_FETCH_FIRST |
The first rowset in the recordset; nRows is ignored. |
|
SQL_FETCH_LAST |
The last complete rowset in the recordset; nRows is ignored. |
|
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. |
|
SQL_FETCH_BOOKMARK |
The rowset starting at the row whose bookmark value corresponds to nRows. |
Note
For foward-only recordsets, Move is only valid with a value of SQL_FETCH_NEXT for wFetchType.
Warning
Calling Move throws an exception if the recordset has no records. To determine whether the recordset has any records, call IsBOF and IsEOF.
Note
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.
Note
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 Windows SDK.
Exceptions
This method can throw exceptions of type CDBException* and CMemoryException*.
Example
// rs is a CRecordset or a CRecordset-derived object
// Change the rowset size to 5
rs.SetRowsetSize(5);
// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);
// 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.MoveFirst();
rs.Move(1, SQL_FETCH_NEXT);
rs.MoveFirst();
rs.MoveNext();
Requirements
Header: afxdb.h