CRecordset::Move

 

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

Syntax

      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.

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.

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

Exception

Condition

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

See Also

CRecordset Class
Hierarchy Chart
CRecordset::MoveNext
CRecordset::MovePrev
CRecordset::MoveFirst
CRecordset::MoveLast
CRecordset::SetAbsolutePosition
CRecordset::SetBookmark
CRecordset::IsBOF
CRecordset::IsEOF
CRecordset::CheckRowsetError