CRecordset::Move

[アーティクル]
08/09/2011

レコードセット内の現在のレコードポインターを前方または後方に移動します。

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

パラメーター

nRows
前または後に移動する行数。正の値は、前方、つまりレコードセットの末尾方向に移動します。負の値は、後方つまりレコードセットの先頭方向に移動します。
wFetchType
Move がフェッチする行セットを調べます。詳細については、「解説」を参照してください。

解説

nRows の値として 0 を渡した場合、Move は現在のレコードを再表示します。Move は、AddNew または Edit モードになっていればそれを終了し、現在のレコードを AddNew または Edit が呼び出される前の値に戻します。

注意

レコードセット内を移動するときに、削除したレコードをスキップすることはできません。詳細については、「CRecordset::IsDeleted」を参照してください。 skipDeletedRecords オプションを設定して CRecordset を開く場合、nRows パラメーターが 0 であると Move はアサートします。これにより、同じデータを使っている別のクライアントアプリケーションによって削除されている行を再表示することが防止されます。 skipDeletedRecords の詳細については、「CRecordset::Open」の dwOption パラメーターを参照してください。

Move は、行セットによってレコードセットを再配置します。 nRows と wFetchType の値に基づいて、Move は適切な行セットをフェッチし、行セットの先頭レコードを現在のレコードとします。バルク行フェッチを実装していない場合、行セットサイズは常に 1 です。行セットをフェッチするとき、Move は CheckRowsetError メンバー関数を直接呼び出し、フェッチによるエラーを処理します。

パラメーターに指定した値によって、Move はほかの CRecordset メンバー関数と同等の関数になります。 wFetchType の値を使用するより、メンバー関数を使用する方がわかりやすいため、現在のレコードの移動にはメンバー関数を使用することを推奨します。

次の表は wFetchType の値、wFetchType と nRows の値に基づいて Move がフェッチする行セット、および wFetchType に対応する同等のメンバー関数の一覧です。

wFetchType	フェッチされる行セット	同等のメンバー関数
SQL_FETCH_RELATIVE (既定値)	現在の行セットの先頭行から nRows 行目で始まる行セット。
SQL_FETCH_NEXT	次の行セット。nRows は無視されます。	MoveNext
SQL_FETCH_PRIOR	前の行セット。nRows は無視されます。	MovePrev
SQL_FETCH_FIRST	レコードセット内の先頭行セット。nRows は無視されます。	MoveFirst
SQL_FETCH_LAST	レコードセット内で最終の完全な行セット。nRows は無視されます。	MoveLast
SQL_FETCH_ABSOLUTE	nRows > 0 の場合は、レコードセットの先頭から nRows 行目で始まる行セット。 nRows < 0 の場合は、レコードセットの最後から nRows 行目で始まる行セット。 nRows = 0 の場合は、ファイル先頭 (BOF) 状態が返されます。	SetAbsolutePosition
SQL_FETCH_BOOKMARK	nRows に対応するブックマーク値を持つ行で始まる行セット。	SetBookmark

注意

前方参照だけのレコードセットの場合、Move は wFetchType の値が SQL_FETCH_NEXT の場合だけ有効です。

ヒント

レコードセットがレコードを持たないとき、Move 関数を呼び出すと例外をスローします。レコードセットにレコードが存在するかどうかを調べるには、IsBOF と IsEOF を呼び出します。

注意

レコードセットの先頭または最後 (IsBOF または IsEOF は 0 以外を戻す) を越えてスクロールした場合は、Move 関数を呼び出すと CDBException をスローする場合があります。たとえば、IsEOF が 0 以外を返し IsBOF の戻り値が 0 の場合は、MoveNext を呼び出すと例外をスローしますが、MovePrev ではスローしません。

注意

現在のレコードを更新または追加しているときに Move を呼び出すと、警告なしに更新は破棄されます。

レコードセットの移動の詳細についてを参照してくださいレコードセット：スクロール (ODBC) とレコードセット：ブックマークと絶対位置 (ODBC)。バルク行フェッチの詳細については、資料を参照してくださいレコードセット：一括 (ODBC) 内のレコードをフェッチ。関連情報については、Windows SDK の ODBC API 関数「SQLExtendedFetch」を参照してください。

例外

このメソッドは、CDBException* 型の例外と CMemoryException* 型の例外をスローできます。

使用例

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