CRecordset::Move

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

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

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 パラメータを参照してください。

レコードセット内を移動するときに、削除したレコードをスキップすることはできません。詳細については、「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 ではスローしません。

レコードセットの先頭または最後 (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();