次の方法で共有

CRecordset クラス

  • [アーティクル]

データ ソースから選択された 1 組のレコードセットを表現します。

構文

class CRecordset : public CObject

メンバー

パブリック コンストラクター

名前 説明
CRecordset::CRecordset CRecordset オブジェクトを構築します。 派生クラスは、これを呼び出すコンストラクターを提供する必要があります。

パブリック メソッド

名前 説明
CRecordset::AddNew 新しいレコードを追加する準備をします。 Updateを呼び出して追加を完了します。
CRecordset::CanAppend AddNew メンバー関数を使用してレコードセットに新しいレコードを追加できる場合は、0 以外の値を返します。
CRecordset::CanBookmark レコードセットがブックマークをサポートしている場合は、0 以外の値を返します。
CRecordset::Cancel 非同期操作または 2 番目のスレッドからのプロセスを取り消します。
CRecordset::CancelUpdate AddNewまたはEdit操作のために保留中の更新を取り消します。
CRecordset::CanRestart レコードセットのクエリを再度実行するために Requery を呼び出すことができる場合は、0 以外の値を返します。
CRecordset::CanScroll レコードをスクロールできる場合は、0 以外の値を返します。
CRecordset::CanTransact データ ソースがトランザクションをサポートしている場合は、0 以外の値を返します。
CRecordset::CanUpdate レコードセットを更新できる (レコードを追加、更新、または削除できる) 場合は、0 以外の値を返します。
CRecordset::CheckRowsetError レコードのフェッチ中に生成されたエラーを処理するために呼び出されます。
CRecordset::Close レコードセットと、それに関連付けられている ODBC HSTMT を閉じます。
CRecordset::Delete レコードセットから現在のレコードを削除します。 削除後、別のレコードまで明示的にスクロールする必要があります。
CRecordset::DoBulkFieldExchange データ ソースからレコードセットにデータの一括行を交換するために呼び出されます。 一括レコード フィールド交換 (Bulk RFX) を実装します。
CRecordset::DoFieldExchange レコードセットのフィールド データ メンバーとデータ ソース上の対応するレコードの間でデータを (双方向に) 交換するために呼び出されます。 レコード フィールド交換 (RFX) を実装します。
CRecordset::Edit 現在のレコードに対する変更を準備します。 Updateを呼び出して編集を完了します。
CRecordset::FlushResultSet 定義済みのクエリを使用するときに、取得する別の結果セットがある場合は 0 以外の値を返します。
CRecordset::GetBookmark レコードのブックマーク値をパラメーター オブジェクトに割り当てます。
CRecordset::GetDefaultConnect 既定の接続文字列を取得するために呼び出されます。
CRecordset::GetDefaultSQL 実行する既定の SQL 文字列を取得するために呼び出されます。
CRecordset::GetFieldValue レコードセット内のフィールドの値を返します。
CRecordset::GetODBCFieldCount レコードセット内のフィールドの数を返します。
CRecordset::GetODBCFieldInfo レコードセット内のフィールドに関する特定の種類の情報を返します。
CRecordset::GetRecordCount レコードセット内のレコードの数を返します。
CRecordset::GetRowsetSize 1 回のフェッチ中に取得するレコードの数を返します。
CRecordset::GetRowsFetched フェッチ中に取得された行の実際の数を返します。
CRecordset::GetRowStatus フェッチ後の行の状態を返します。
CRecordset::GetSQL レコードセットのレコードを選択するために使用する SQL 文字列を取得します。
CRecordset::GetStatus レコードセットの状態 (現在のレコードのインデックス、およびレコードの最終カウントが取得されたかどうかを示す) を取得します。
CRecordset::GetTableName レコードセットの基になるテーブルの名前を取得します。
CRecordset::IsBOF レコードセットが最初のレコードの前に配置されている場合は、0 以外の値を返します。 現在のレコードはありません。
CRecordset::IsDeleted レコードセットが削除されたレコードに配置されている場合は、0 以外の値を返します。
CRecordset::IsEOF レコードセットが最後のレコードの後に配置されている場合は、0 以外の値を返します。 現在のレコードはありません。
CRecordset::IsFieldDirty 現在のレコード内の指定したフィールドが変更された場合は、0 以外の値を返します。
CRecordset::IsFieldNull 現在のレコード内の指定したフィールドが null (値なし) の場合は、0 以外の値を返します。
CRecordset::IsFieldNullable 現在のレコード内の指定したフィールドを null (値を持たない) に設定できる場合は、0 以外の値を返します。
CRecordset::IsOpen Openが以前に呼び出された場合は、0 以外の値を返します。
CRecordset::Move レコードセットを、現在のレコードの指定された数のレコードに、どちらの方向にも配置します。
CRecordset::MoveFirst レコードセットの最初のレコードに現在のレコードを配置します。 最初に IsBOF をテストします。
CRecordset::MoveLast 現在のレコードを最後のレコードまたは最後の行セットに配置します。 最初に IsEOF をテストします。
CRecordset::MoveNext 現在のレコードを次のレコードまたは次の行セットに配置します。 最初に IsEOF をテストします。
CRecordset::MovePrev 現在のレコードを前のレコードまたは前の行セットに配置します。 最初に IsBOF をテストします。
CRecordset::OnSetOptions 指定した ODBC ステートメントのオプション (選択時に使用) を設定するために呼び出されます。
CRecordset::OnSetUpdateOptions 指定した ODBC ステートメントのオプション (更新時に使用) を設定するために呼び出されます。
CRecordset::Open テーブルを取得するか、レコードセットが表すクエリを実行して、レコードセットを開きます。
CRecordset::RefreshRowset 指定した行のデータと状態を更新します。
CRecordset::Requery レコードセットのクエリをもう一度実行して、選択したレコードを更新します。
CRecordset::SetAbsolutePosition 指定したレコード番号に対応するレコードにレコードセットを配置します。
CRecordset::SetBookmark ブックマークで指定されたレコードにレコードセットを配置します。
CRecordset::SetFieldDirty 現在のレコード内の指定したフィールドを変更としてマークします。
CRecordset::SetFieldNull 現在のレコード内の指定したフィールドの値を null (値なし) に設定します。
CRecordset::SetLockingMode ロック モードを "オプティミスティック" ロック (既定) または "ペシミスティック" ロックに設定します。 更新プログラムのレコードのロック方法を決定します。
CRecordset::SetParamNull 指定したパラメーターを null (値なし) に設定します。
CRecordset::SetRowsetCursorPosition 行セット内の指定した行にカーソルを置きます。
CRecordset::SetRowsetSize フェッチ中に取得するレコードの数を指定します。
CRecordset::Update 新しいデータまたは編集されたデータをデータ ソースに保存して、 AddNew または Edit 操作を完了します。

パブリック データ メンバー

名前 説明
CRecordset::m_hstmt レコードセットの ODBC ステートメント ハンドルを格納します。 「HSTMT」と入力します。
CRecordset::m_nFields レコードセット内のフィールド データ メンバーの数を格納します。 「UINT」と入力します。
CRecordset::m_nParams レコードセット内のパラメーター データ メンバーの数を格納します。 「UINT」と入力します。
CRecordset::m_pDatabase レコードセットがデータ ソースに接続されている CDatabase オブジェクトへのポインターを格納します。
CRecordset::m_strFilter 構造化照会言語 (SQL) WHERE句を指定するCStringが含まれています。 特定の条件を満たすレコードのみを選択するフィルターとして使用されます。
CRecordset::m_strSort SQL ORDER BY句を指定するCStringが含まれています。 レコードの並べ替え方法を制御するために使用されます。

解説

"レコードセット" と呼ばれる CRecordset オブジェクトは、通常、ダイナセットとスナップショットの 2 つの形式で使用されます。 ダイナセットは、他のユーザーによって行われたデータ更新と同期された状態を維持します。 スナップショットは、データの静的ビューです。 各フォームは、レコードセットを開いた時点で固定されたレコードのセットを表します。 ダイナセット内のレコードまでスクロールすると、他のユーザーまたはアプリケーション内の他のレコードセットによってレコードに加えられた変更が反映されます。

Note

Open Database Connectivity (ODBC) クラスではなく、データ アクセス オブジェクト (DAO) クラスを使用している場合は、代わりにクラス CDaoRecordset を使用します。 詳細については、「 Overview: データベース プログラミング」を参照してください。

いずれかの種類のレコードセットを操作するには、通常、 CRecordsetからアプリケーション固有のレコードセット クラスを派生させます。 レコードセットはデータ ソースからレコードを選択し、次の操作を行うことができます。

  • レコードをスクロールします。

  • レコードを更新し、ロック モードを指定します。

  • レコードセットをフィルター処理して、データ ソースで使用可能なレコードから選択するレコードを制限します。

  • レコードセットを並べ替えます。

  • 実行時まで不明な情報でレコードセットの選択をカスタマイズするには、パラメーター化します。

クラスを使用するには、データベースを開き、レコードセット オブジェクトを構築し、コンストラクターに CDatabase オブジェクトへのポインターを渡します。 次に、レコードセットの Open メンバー関数を呼び出します。ここで、オブジェクトがダイナセットかスナップショットかを指定できます。 Openを呼び出すと、データ ソースからデータが選択されます。 レコードセット オブジェクトを開いた後、そのメンバー関数とデータ メンバーを使用してレコードをスクロールして操作します。 使用できる操作は、オブジェクトがダイナセットかスナップショットか、更新可能か読み取り専用か (これは Open Database Connectivity (ODBC) データ ソースの機能によって異なります)、一括行フェッチを実装しているかどうかによって異なります。 Open呼び出し以降に変更または追加された可能性のあるレコードを更新するには、オブジェクトのRequeryメンバー関数を呼び出します。 オブジェクトの Close メンバー関数を呼び出し、終了したらオブジェクトを破棄します。

派生 CRecordset クラスでは、レコード フィールドの読み取りと更新をサポートするために、レコード フィールド交換 (RFX) または一括レコード フィールド交換 (Bulk RFX) が使用されます。

レコードセットとレコード フィールド交換の詳細については、「 Overview: データベース プログラミング、 Recordset (ODBC)、 Recordset: Fetching Records in Bulk (ODBC)、および Record Field Exchange (RFX)に関する記事を参照してください。 ダイナセットとスナップショットに焦点を当てるには、 Dynaset と Snapshotに関する記事を参照してください。

継承階層

CObject

CRecordset

要件

ヘッダー: afxdb.h

CRecordset::AddNew

テーブルに新しいレコードを追加する準備をします。

virtual void AddNew();

解説

新しく追加されたレコードを表示するには、 Requery メンバー関数を呼び出す必要があります。 レコードのフィールドは最初は Null です。 (データベースの用語では、Null は "値を持たない" ことを意味し、C++ の NULL と同じではありません)。操作を完了するには、 Update メンバー関数を呼び出す必要があります。 Update は、変更をデータ ソースに保存します。

Note

一括行フェッチを実装している場合は、 AddNewを呼び出すことはできません。 これにより、アサーションが失敗します。 クラス CRecordset には、データの一括行を更新するためのメカニズムは用意されていませんが、ODBC API 関数 SQLSetPosを使用して独自の関数を記述できます。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

AddNew は、レコードセットのフィールド データ メンバーを使用して、新しい空のレコードを準備します。 AddNewを呼び出した後、レコードセットのフィールド データ メンバーに必要な値を設定します。 ( を呼び出す必要はありません編集 この目的のメンバー関数。既存のレコードにのみ Edit を使用します。 Updateを呼び出すと、フィールド データ メンバーの変更された値がデータ ソースに保存されます。

注意事項

Updateを呼び出す前に新しいレコードまでスクロールすると、新しいレコードは失われ、警告は表示されません。

データ ソースがトランザクションをサポートしている場合は、 AddNew 呼び出しをトランザクションの一部にすることができます。 トランザクションの詳細については、クラスの CDatabaseを参照してください。 AddNewを呼び出す前にCDatabase::BeginTransを呼び出します。

Note

ダイナセットの場合、レコードセットに最後のレコードとして新しいレコードが追加されます。 追加されたレコードはスナップショットに追加されません。レコードセットを更新するには、 Requery を呼び出す必要があります。

Open メンバー関数が呼び出されていないレコードセットのAddNewを呼び出すことはできません。 追加できないレコードセットのAddNewを呼び出すと、CDBExceptionがスローされます。 レコードセットが更新可能かどうかを確認するには、 CanAppendを呼び出します。

詳細については、「 Recordset: レコードセットのレコード更新方法 (ODBC)、 Recordset: レコードの追加、更新、および削除 (ODBC)、および Transaction (ODBC)を参照してください。

例

「 トランザクション: レコードセット (ODBC) でのトランザクションの実行」を参照してください。

CRecordset::CanAppend

以前に開いたレコードセットで新しいレコードを追加できるかどうかを決定します。

BOOL CanAppend() const;

戻り値

レコードセットで新しいレコードを追加できる場合は 0 以外。それ以外の場合は 0。 CanAppend レコードセットを読み取り専用として開いた場合、0 が返されます。

CRecordset::CanBookmark

レコードセットでブックマークを使用してレコードをマークできるかどうかを決定します。

BOOL CanBookmark() const;

戻り値

レコードセットがブックマークをサポートしている場合は 0 以外。それ以外の場合は 0。

解説

この関数は、Open メンバー関数の dwOptions パラメーターのCRecordset::useBookmarks オプションとは無関係です。 CanBookmark は、指定された ODBC ドライバーとカーソルの種類がブックマークをサポートするかどうかを示します。 CRecordset::useBookmarks は、ブックマークがサポートされている場合に、ブックマークを使用できるかどうかを示します。

Note

ブックマークは、前方専用レコードセットではサポートされていません。

ブックマークとレコードセットのナビゲーションの詳細については、「レコードセット: ブックマークと絶対位置 (ODBC)」およびRecordset: Scrolling (ODBC)に関する記事を参照してください。

CRecordset::Cancel

データ ソースが進行中の非同期操作または 2 番目のスレッドからのプロセスを取り消すように要求します。

void Cancel();

解説

MFC ODBC クラスでは、非同期処理は使用されなくなりました。非同期操作を実行するには、ODBC API 関数 SQLSetConnectOptionを直接呼び出す必要があります。 詳細については、「 ODBC SDK プログラマ ガイドの「関数の非同期実行」を参照してください。

CRecordset::CancelUpdate

Updateが呼び出される前に、EditまたはAddNew操作によって引き起こされる保留中の更新を取り消します。

void CancelUpdate();

解説

Note

このようなレコードセットは Edit、 AddNew、または Updateを呼び出すことができるため、このメンバー関数は、一括行フェッチを使用しているレコードセットには適用できません。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

ダーティ フィールドの自動チェックが有効になっている場合、 CancelUpdate はメンバー変数を、 Edit または AddNew が呼び出される前の値に復元します。それ以外の場合は、値の変更はそのまま残ります。 既定では、レコードセットを開くと、フィールドの自動チェックが有効になります。 無効にするには、Open メンバー関数の dwOptions パラメーターにCRecordset::noDirtyFieldCheckを指定する必要があります。

データの更新の詳細については、「 Recordset: レコードの追加、更新、および削除 (ODBC)」を参照してください。

CRecordset::CanRestart

Requery メンバー関数を呼び出して、レコードセットがクエリを再開できるかどうかを判断します (レコードを更新するため)。

BOOL CanRestart() const;

戻り値

再クエリが許可されている場合は 0 以外。それ以外の場合は 0。

CRecordset::CanScroll

レコードセットでスクロールを許可するかどうかを指定します。

BOOL CanScroll() const;

戻り値

レコードセットでスクロールが許可されている場合は 0 以外。それ以外の場合は 0。

解説

スクロールの詳細については、「 Recordset: Scrolling (ODBC)」を参照してください。

CRecordset::CanTransact

レコードセットがトランザクションを許可するかどうかを決定します。

BOOL CanTransact() const;

戻り値

レコードセットがトランザクションを許可する場合は 0 以外。それ以外の場合は 0。

解説

詳細については、「 Transaction (ODBC)」を参照してください。

CRecordset::CanUpdate

レコードセットを更新できるかどうかを決定します。

BOOL CanUpdate() const;

戻り値

レコードセットを更新できる場合は 0 以外。それ以外の場合は 0。

解説

基になるデータ ソースが読み取り専用の場合、またはレコードセットを開いたときに dwOptions パラメーターにCRecordset::readOnlyを指定した場合、レコードセットは読み取り専用になることがあります。

CRecordset::CheckRowsetError

レコードのフェッチ中に生成されたエラーを処理するために呼び出されます。

virtual void CheckRowsetError(RETCODE nRetCode);

パラメーター

nRetCode
ODBC API 関数のリターン コード。 詳細については、「解説」を参照してください。

解説

この仮想メンバー関数は、レコードがフェッチされるときに発生するエラーを処理し、一括行フェッチ中に役立ちます。 独自のエラー処理を実装するために、 CheckRowsetError をオーバーライドすることを検討してください。

CheckRowsetError は、カーソル ナビゲーション操作 ( Open、 Requery、 Move 操作など) で自動的に呼び出されます。 ODBC API 関数の戻り値が渡されます。 次の表に、 nRetCode パラメーターに指定できる値を示します。

nRetCode 説明
SQL_SUCCESS 関数が正常に完了しました。追加情報はありません。
SQL_SUCCESS_WITH_INFO 関数が正常に完了し、致命的でないエラーが発生した可能性があります。 追加情報は、 SQLErrorを呼び出すことによって取得できます。
SQL_NO_DATA_FOUND 結果セットのすべての行がフェッチされました。
SQL_ERROR 関数が失敗しました。 追加情報は、 SQLErrorを呼び出すことによって取得できます。
SQL_INVALID_HANDLE 無効な環境ハンドル、接続ハンドル、またはステートメント ハンドルが原因で関数が失敗しました。 これは、プログラミング エラーを示します。 SQLErrorから追加情報を入手できません。
SQL_STILL_EXECUTING 非同期的に開始された関数は、まだ実行中です。 既定では、MFC はこの値をCheckRowsetErrorに渡しません。MFC は、SQL_STILL_EXECUTINGを返さない限り、SQLExtendedFetchの呼び出しを続行します。

SQLErrorの詳細については、Windows SDK を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::Close

レコードセットを閉じます。

virtual void Close();

解説

ODBC HSTMT と、レコードセットに割り当てられたフレームワークのすべてのメモリが割り当て解除されます。 通常、 Closeを呼び出した後、 newで割り当てられた C++ レコードセット オブジェクトを削除します。

Closeを呼び出した後、Openをもう一度呼び出すことができます。 これにより、レコードセット オブジェクトを再利用できます。 代わりに、 Requeryを呼び出します。

例

// Construct a snapshot object
CCustomer rsCustSet(NULL);

if (!rsCustSet.Open())
return;

// Use the snapshot ...

// Close the snapshot
rsCustSet.Close();

// Destructor is called when the function exits

CRecordset::CRecordset

CRecordset オブジェクトを構築します。

CRecordset(CDatabase* pDatabase = NULL);

パラメーター

pDatabase
CDatabase オブジェクトまたはNULL値へのポインターを格納します。 NULLされず、データ ソースに接続するためにCDatabase オブジェクトのOpen メンバー関数が呼び出されていない場合、レコードセットは独自のOpen呼び出し中に開こうとします。 NULL渡すと、classWizard でレコードセット クラスを派生したときに指定したデータ ソース情報を使用して、CDatabase オブジェクトが構築され、接続されます。

解説

CRecordsetを直接使用するか、CRecordsetからアプリケーション固有のクラスを派生させることができます。 ClassWizard を使用して、レコードセット クラスを派生させることができます。

Note

派生クラス must 独自のコンストラクターを提供します。 派生クラスのコンストラクターで、コンストラクター CRecordset::CRecordsetを呼び出し、適切なパラメーターを渡します。

NULLをレコードセット コンストラクターに渡して、CDatabase オブジェクトを自動的に構築して接続します。 これは便利な短縮形であり、レコードセットを構築する前に CDatabase オブジェクトを構築して接続する必要はありません。

例

詳細については、「 Recordset: テーブルのクラスの宣言 (ODBC)」を参照してください。

CRecordset::Delete

現在のレコードを削除します。

virtual void Delete();

解説

削除が成功すると、レコードセットのフィールド データ メンバーは Null 値に設定され、削除されたレコードから移動するには、 Move 関数のいずれかを明示的に呼び出す必要があります。 削除されたレコードから移動すると、そのレコードに戻ることはできません。 データ ソースがトランザクションをサポートしている場合は、 Delete 呼び出しをトランザクションの一部にすることができます。 詳細については、「 Transaction (ODBC)」を参照してください。

Note

一括行フェッチを実装している場合は、 Deleteを呼び出すことはできません。 これにより、アサーションが失敗します。 クラス CRecordset には、データの一括行を更新するためのメカニズムは用意されていませんが、ODBC API 関数 SQLSetPosを使用して独自の関数を記述できます。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

注意事項

レコードセットは更新可能で、 Deleteを呼び出すときにレコードセットに有効なレコードが存在する必要があります。それ以外の場合は、エラーが発生します。 たとえば、レコードを削除しても、 Delete を再度呼び出す前に新しいレコードまでスクロールしない場合、 Delete は CDBException をスローします。

AddNewやEditとは異なり、Deleteの呼び出しの後にUpdateの呼び出しは行われません。 Delete呼び出しが失敗した場合、フィールド データ メンバーは変更されません。

例

この例では、関数のフレームに作成されたレコードセットを示します。 この例では、データ ソースに既に接続CDatabase型のメンバー変数であるm_dbCustが存在することを前提としています。

// Create a derived CRecordset object
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if (rsCustSet.IsEOF() || !rsCustSet.CanUpdate() ||
   !rsCustSet.CanTransact())
{
   return;
}

m_dbCust.BeginTrans();

// Perhaps scroll to a new record...
// Delete the current record
rsCustSet.Delete();

// Finished commands for this transaction
if (IDYES == AfxMessageBox(_T("Commit transaction?"), MB_YESNO))
m_dbCust.CommitTrans();
else // User changed mind
m_dbCust.Rollback();

CRecordset::DoBulkFieldExchange

データ ソースからレコードセットにデータの一括行を交換するために呼び出されます。 一括レコード フィールド交換 (Bulk RFX) を実装します。

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

パラメーター

pFX
CFieldExchange オブジェクトを指すポインターです。 フレームワークでは、フィールド交換操作のコンテキストを指定するために、このオブジェクトが既に設定されています。

解説

一括行フェッチが実装されると、フレームワークはこのメンバー関数を呼び出して、データ ソースからレコードセット オブジェクトにデータを自動的に転送します。 DoBulkFieldExchange また、パラメーター データ メンバー (存在する場合) を、レコードセットの選択の SQL ステートメント文字列内のパラメーター プレースホルダーにバインドします。

一括行フェッチが実装されていない場合、フレームワークは DoFieldExchangeを呼び出します。 一括行フェッチを実装するには、Open メンバー関数で dwOptions パラメーターのCRecordset::useMultiRowFetch オプションを指定する必要があります。

Note

DoBulkFieldExchange は、 CRecordsetから派生したクラスを使用している場合にのみ使用できます。 CRecordsetから直接レコードセット オブジェクトを作成した場合は、GetFieldValue メンバー関数を呼び出してデータを取得する必要があります。

一括レコード フィールド交換 (Bulk RFX) は、レコード フィールド交換 (RFX) に似ています。 データは、データ ソースからレコードセット オブジェクトに自動的に転送されます。 ただし、変更をデータ ソースに転送するために、 AddNew、 Edit、 Delete、または Update を呼び出すことはできません。 現在、クラス CRecordset には、データの一括行を更新するためのメカニズムは用意されていませんが、ODBC API 関数 SQLSetPosを使用して独自の関数を記述できます。

ClassWizard では、一括レコード フィールド交換はサポートされていません。そのため、Bulk RFX 関数への呼び出しを記述して、 DoBulkFieldExchange を手動でオーバーライドする必要があります。 これらの関数の詳細については、「 レコード フィールド Exchange 関数を参照してください。

バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。 関連情報については、「 Record Field Exchange (RFX)」を参照してください。

CRecordset::DoFieldExchange

レコードセットのフィールド データ メンバーとデータ ソース上の対応するレコードの間でデータを (双方向に) 交換するために呼び出されます。 レコード フィールド交換 (RFX) を実装します。

virtual void DoFieldExchange(CFieldExchange* pFX);

パラメーター

pFX
CFieldExchange オブジェクトを指すポインターです。 フレームワークでは、フィールド交換操作のコンテキストを指定するために、このオブジェクトが既に設定されています。

解説

一括行フェッチが実装されていない場合、フレームワークはこのメンバー関数を呼び出して、レコードセット オブジェクトのフィールド データ メンバーとデータ ソース上の現在のレコードの対応する列の間でデータを自動的に交換します。 DoFieldExchange また、パラメーター データ メンバー (存在する場合) を、レコードセットの選択の SQL ステートメント文字列内のパラメーター プレースホルダーにバインドします。

一括行フェッチが実装されている場合、フレームワークは DoBulkFieldExchangeを呼び出します。 一括行フェッチを実装するには、Open メンバー関数で dwOptions パラメーターのCRecordset::useMultiRowFetch オプションを指定する必要があります。

Note

DoFieldExchange は、 CRecordsetから派生したクラスを使用している場合にのみ使用できます。 レコードセット オブジェクトを CRecordsetから直接作成した場合は、 GetFieldValue メンバー関数を呼び出してデータを取得する必要があります。

レコード フィールド交換 (RFX) と呼ばれるフィールド データの交換は、レコードセット オブジェクトのフィールド データ メンバーからデータ ソースのレコードのフィールド、およびデータ ソースのレコードからレコード セット オブジェクトへの双方向で機能します。

派生レコードセット クラスの DoFieldExchange を実装するために通常実行する必要がある唯一のアクションは、ClassWizard を使用してクラスを作成し、フィールド データ メンバーの名前とデータ型を指定することです。 ClassWizard が書き込むコードを追加して、パラメーター データ メンバーを指定したり、動的にバインドする列を処理したりすることもできます。 詳細については、「レコードセット: データ列を動的に結びつける方法 (ODBC)」を参照してください。

ClassWizard を使用して派生レコードセット クラスを宣言すると、ウィザードによって DoFieldExchange のオーバーライドが書き込まれます。これは次の例のようになります。

void CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputColumn);
   // Macros such as RFX_Text() and RFX_Int() are dependent on the
   // type of the member variable, not the type of the field in the database.
   // ODBC will try to automatically convert the column value to the requested type
   RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
   RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
   RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
   RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
   RFX_Long(pFX, _T("[BillingID]"), m_BillingID);

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param"), m_strParam);
}

RFX 関数の詳細については、「 Record Field Exchange Functionsを参照してください。

DoFieldExchangeに関するその他の例と詳細については、「Record Field Exchange: How RFX Works」を参照してください。 RFX の一般的な情報については、「 Record Field Exchange」を参照してください。

CRecordset::Edit

現在のレコードに対する変更を許可します。

virtual void Edit();

解説

Editを呼び出した後、フィールド データ メンバーの値を直接リセットすることで変更できます。 Update メンバー関数を呼び出して変更をデータ ソースに保存すると、操作が完了します。

Note

一括行フェッチを実装している場合は、 Editを呼び出すことはできません。 これにより、アサーションが失敗します。 クラス CRecordset には、データの一括行を更新するためのメカニズムは用意されていませんが、ODBC API 関数 SQLSetPosを使用して独自の関数を記述できます。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

Edit は、レコードセットのデータ メンバーの値を保存します。 Editを呼び出し、変更を加えた後、Editをもう一度呼び出すと、レコードの値は最初のEdit呼び出しの前の値に復元されます。

場合によっては、列を Null (データを含まない) にして更新することが必要になる場合があります。 これを行うには、パラメーター true を指定して SetFieldNull を呼び出してフィールド Null をマークします。これにより、列も更新されます。 値が変更されていない場合でもフィールドをデータ ソースに書き込む場合は、true のパラメーターを指定して SetFieldDirty を呼び出します。 これは、フィールドの値が Null の場合でも機能します。

データ ソースがトランザクションをサポートしている場合は、 Edit 呼び出しをトランザクションの一部にすることができます。 Editを呼び出す前とレコードセットを開いた後に、CDatabase::BeginTransを呼び出します。 また、CDatabase::CommitTransの呼び出しは、Edit操作を完了するためのUpdateの呼び出しの代わりではありません。 トランザクションの詳細については、クラスの CDatabaseを参照してください。

現在のロック モードによっては、Updateを呼び出すか、別のレコードまでスクロールするまで、更新されるレコードがEditによってロックされるか、Edit呼び出し中にのみロックされる場合があります。 ロック モードは、 SetLockingModeで変更できます。

Updateを呼び出す前に新しいレコードまでスクロールすると、現在のレコードの前の値が復元されます。 更新できないレコードセットのEditを呼び出した場合、または現在のレコードがない場合は、CDBExceptionがスローされます。

詳細については、「 Transaction (ODBC) 」および「 Recordset: レコードのロック (ODBC)」を参照してください。

例

// To edit a record, first set up the edit buffer
rsCustSet.Edit();

// Then edit field data members for the record
rsCustSet.m_BillingID = 2795;
rsCustSet.m_ContactFirstName = _T("Jones Mfg");

// Finally, complete the operation
if (!rsCustSet.Update())
{
   // Handle the failure to update
   AfxMessageBox(_T("Couldn't update record!"));
}

CRecordset::FlushResultSet

複数の結果セットがある場合は、定義済みのクエリ (ストアド プロシージャ) の次の結果セットを取得します。

BOOL FlushResultSet();

戻り値

取得する結果セットがそれ以上ある場合は 0 以外。それ以外の場合は 0。

解説

FlushResultSetは、現在の結果セットのカーソルが終了した場合にのみ呼び出す必要があります。 FlushResultSetを呼び出して次の結果セットを取得すると、その結果セットでカーソルが無効になります。FlushResultSetを呼び出した後、MoveNextメンバー関数を呼び出す必要があります。

定義済みのクエリで出力パラメーターまたは入力/出力パラメーターを使用する場合、これらのパラメーター値を取得するには、FALSE (値 0) が返されるまでFlushResultSetを呼び出す必要があります。

FlushResultSet は ODBC API 関数 SQLMoreResultsを呼び出します。 SQLMoreResultsがSQL_ERRORまたはSQL_INVALID_HANDLEを返した場合、FlushResultSetは例外をスローします。 SQLMoreResultsの詳細については、Windows SDK を参照してください。

FlushResultSetを呼び出す場合は、ストアド プロシージャにバインドされたフィールドが必要です。

例

次のコードでは、 COutParamRecordset は、入力パラメーターと出力パラメーターを持つ定義済みのクエリに基づく CRecordset派生オブジェクトであり、複数の結果セットがあることを前提としています。 DoFieldExchangeオーバーライドの構造に注意してください。

// DoFieldExchange override
//
// Only necessary to handle parameter bindings.
// Don't use CRecordset-derived class with bound
// fields unless all result sets have same schema
// OR there is conditional binding code.
void CCourses::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputParam);
   RFX_Long(pFX, _T("Param1"), m_nCountParam);
   // The "Param1" name here is a dummy name 
   // that is never used

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param2"), m_strNameParam);
   // The "Param2" name here is a dummy name 
   // that is never used
}

 

// Assume db is an already open CDatabase object
CCourses rs(&m_dbCust);
rs.m_strNameParam = _T("History");

// Get the first result set
// NOTE: SQL Server requires forwardOnly cursor 
//       type for multiple rowset returning stored 
//       procedures
rs.Open(CRecordset::forwardOnly,
   _T("{? = CALL GetCourses( ? )}"),
   CRecordset::readOnly);

// Loop through all the data in the first result set
while (!rs.IsEOF())
{
   CString strFieldValue;
   for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
   {
      rs.GetFieldValue(nIndex, strFieldValue);

      // TO DO: Use field value string.
   }
   rs.MoveNext();
}

// Retrieve other result sets...
while (rs.FlushResultSet())
{
   // must call MoveNext because cursor is invalid
   rs.MoveNext();

   while (!rs.IsEOF())
   {
      CString strFieldValue;
      for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
      {
         rs.GetFieldValue(nIndex, strFieldValue);

         // TO DO: Use field value string.
      }
      rs.MoveNext();
   }
}


// All result sets have been flushed. Cannot
// use the cursor, but the output parameter,
// m_nCountParam, has now been written.
// Note that m_nCountParam is not valid until
// CRecordset::FlushResultSet has returned FALSE,
// indicating no more result sets will be returned.

// TO DO: Use m_nCountParam

// Cleanup
rs.Close();

CRecordset::GetBookmark

現在のレコードのブックマーク値を取得します。

void GetBookmark(CDBVariant& varBookmark);

パラメーター

varBookmark
現在のレコードのブックマークを表す CDBVariant オブジェクトへの参照。

解説

ブックマークがレコードセットでサポートされているかどうかを確認するには、 CanBookmarkを呼び出します。 サポートされている場合にブックマークを使用できるようにするには、Open メンバー関数の dwOptions パラメーターで CRecordset::useBookmarks オプションを設定する必要があります。

Note

ブックマークがサポートされていないか使用できない場合、 GetBookmark を呼び出すと例外がスローされます。 ブックマークは、前方専用レコードセットではサポートされていません。

GetBookmark は、現在のレコードのブックマークの値を CDBVariant オブジェクトに割り当てます。 別のレコードに移動した後、いつでもそのレコードに戻すには、対応するCDBVariant オブジェクトを使用してSetBookmarkを呼び出します。

Note

特定のレコードセット操作の後、ブックマークが無効になる可能性があります。 たとえば、 GetBookmark を呼び出し、その後に Requeryを呼び出した場合、 SetBookmarkを使用してレコードに戻ることができない場合があります。 CDatabase::GetBookmarkPersistenceを呼び出して、SetBookmarkを安全に呼び出すことができるかどうかを確認します。

ブックマークとレコードセットのナビゲーションの詳細については、「レコードセット: ブックマークと絶対位置 (ODBC)」およびRecordset: Scrolling (ODBC)に関する記事を参照してください。

CRecordset::GetDefaultConnect

既定の接続文字列を取得するために呼び出されます。

virtual CString GetDefaultConnect();

戻り値

既定の接続文字列を含むCString。

解説

フレームワークは、このメンバー関数を呼び出して、レコードセットの基になっているデータ ソースの既定の接続文字列を取得します。 ClassWizard では、テーブルと列に関する情報を取得するために ClassWizard で使用するのと同じデータ ソースを識別することで、この関数を実装します。 アプリケーションの開発時に、この既定の接続に依存すると便利な場合があります。 ただし、既定の接続は、アプリケーションのユーザーには適していない場合があります。 その場合は、この関数を再実装し、 ClassWizardのバージョンを破棄する必要があります。 接続文字列の詳細については、「Data Source (ODBC)」を参照してください。

CRecordset::GetDefaultSQL

実行する既定の SQL 文字列を取得するために呼び出されます。

virtual CString GetDefaultSQL();

戻り値

既定の SQL ステートメントを含む CString 。

解説

フレームワークは、このメンバー関数を呼び出して、レコードセットの基になっている既定の SQL ステートメントを取得します。 テーブル名または SQL SELECT ステートメントです。

既定の SQL ステートメントを間接的に定義するには、 ClassWizardを使用してレコードセット クラスを宣言し、このタスク ClassWizard 実行します。

自分で使用するために SQL ステートメント文字列が必要な場合は、 GetSQLを呼び出します。これは、レコードセットが開かれたときにレコードセットのレコードを選択するために使用される SQL ステートメントを返します。 クラスの GetDefaultSQL のオーバーライドで、既定の SQL 文字列を編集できます。 たとえば、 CALL ステートメントを使用して、定義済みのクエリの呼び出しを指定できます。 (ただし、 GetDefaultSQLを編集する場合は、データ ソース内の列数と一致するように m_nFields も変更する必要があることに注意してください)。

詳細については、「 Recordset: テーブルのクラスの宣言 (ODBC)」を参照してください。

注意事項

フレームワークがテーブル名を識別できなかった場合、複数のテーブル名が指定された場合、または CALL ステートメントを解釈できなかった場合、テーブル名は空になります。 CALLステートメントを使用する場合は、中かっことCALLキーワードの間、または中かっこの前、または SELECT ステートメントの SELECT キーワードの前に空白を挿入しないでください。

CRecordset::GetFieldValue

現在のレコードのフィールド データを取得します。

void GetFieldValue(
    LPCTSTR lpszName,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringA& strValue
);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringW& strValue
);

void GetFieldValue(
    short nIndex,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    short nIndex,
    CStringA& strValue);

void GetFieldValue(
    short nIndex,
    CStringW& strValue);

パラメーター

lpszName
フィールドの名前。

varValue フィールドの値を格納する CDBVariant オブジェクトへの参照。

nFieldType
フィールドの ODBC C データ型。 DEFAULT_FIELD_TYPE既定値を使用すると、次の表に基づいて、GetFieldValueが SQL データ型から C データ型を決定するように強制されます。 それ以外の場合は、データ型を直接指定するか、互換性のあるデータ型を選択できます。たとえば、任意のデータ型を SQL_C_CHARに格納できます。

C data type (C データ型) SQL data type (SQL データ型)
SQL_C_BIT SQL_BIT
SQL_C_UTINYINT SQL_TINYINT
SQL_C_SSHORT SQL_SMALLINT
SQL_C_SLONG SQL_INTEGER
SQL_C_FLOAT SQL_REAL
SQL_C_DOUBLE SQL_FLOATSQL_DOUBLE
SQL_C_TIMESTAMP SQL_DATESQL_TIMESQL_TIMESTAMP
SQL_C_CHAR SQL_NUMERICSQL_DECIMALSQL_BIGINTSQL_CHARSQL_VARCHARSQL_LONGVARCHAR
SQL_C_BINARY SQL_BINARYSQL_VARBINARYSQL_LONGVARBINARY

ODBC データ型の詳細については、Windows SDK の付録 D の「SQL データ型」および「C データ型」のトピックを参照してください。

nIndex
フィールドの 0 から始まるインデックス。

strValue
フィールドのデータ型に関係なく、テキストに変換されたフィールドの値を格納する CString オブジェクトへの参照。

解説

フィールドは、名前またはインデックスで検索できます。 フィールド値は、 CDBVariant オブジェクトまたは CString オブジェクトのいずれかに格納できます。

一括行フェッチを実装した場合、現在のレコードは常に行セットの最初のレコードに配置されます。 特定の行セット内のレコードで GetFieldValue を使用するには、最初に SetRowsetCursorPosition メンバー関数を呼び出して、その行セット内の目的の行にカーソルを移動する必要があります。 その後、その行の GetFieldValue を呼び出します。 一括行フェッチを実装するには、Open メンバー関数で dwOptions パラメーターのCRecordset::useMultiRowFetch オプションを指定する必要があります。

GetFieldValueを使用すると、デザイン時に静的にバインドするのではなく、実行時にフィールドを動的にフェッチできます。 たとえば、レコードセット オブジェクトを CRecordsetから直接宣言した場合、 GetFieldValue を使用してフィールド データを取得する必要があります。レコード フィールド交換 (RFX)、または一括レコード フィールド交換 (Bulk RFX) は実装されていません。

Note

CRecordsetから派生せずにレコードセット オブジェクトを宣言する場合は、ODBC カーソル ライブラリを読み込んでいません。 カーソル ライブラリでは、レコードセットに少なくとも 1 つのバインドされた列が必要です。ただし、 CRecordset を直接使用する場合、どの列もバインドされていません。 メンバー関数は CDatabase::OpenEx し、カーソル ライブラリを読み込むかどうかを制御 CDatabase::Open 。

GetFieldValue は ODBC API 関数 SQLGetDataを呼び出します。 ドライバーがフィールド値の実際の長さSQL_NO_TOTAL値を出力した場合、 GetFieldValue は例外をスローします。 SQLGetDataの詳細については、Windows SDK を参照してください。

例

次のサンプル コードは、CRecordsetから直接宣言されたレコードセット オブジェクトのGetFieldValueの呼び出しを示しています。

// Create and open a database object;
// do not load the cursor library
CDatabase db;
db.OpenEx(NULL, CDatabase::forceOdbcDialog);

// Create and open a recordset object
// directly from CRecordset. Note that a
// table must exist in a connected database.
// Use forwardOnly type recordset for best
// performance, since only MoveNext is required
CRecordset rs(&db);
rs.Open(CRecordset::forwardOnly, _T("SELECT * FROM Customer"));

// Create a CDBVariant object to
// store field data
CDBVariant varValue;

// Loop through the recordset,
// using GetFieldValue and
// GetODBCFieldCount to retrieve
// data in all columns
short nFields = rs.GetODBCFieldCount();
while (!rs.IsEOF())
{
   for (short index = 0; index < nFields; index++)
   {
      rs.GetFieldValue(index, varValue);
      // do something with varValue
   }
   rs.MoveNext();
}

rs.Close();
db.Close();

Note

DAO クラス CDaoRecordsetとは異なり、 CRecordset には SetFieldValue メンバー関数がありません。 CRecordsetから直接オブジェクトを作成すると、実質的に読み取り専用になります。

バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::GetODBCFieldCount

レコードセット オブジェクト内のフィールドの合計数を取得します。

short GetODBCFieldCount() const;

戻り値

レコードセット内のフィールドの数。

解説

レコードセットの作成の詳細については、「 Recordset: レコードセットの作成と終了 (ODBC)」を参照してください。

CRecordset::GetODBCFieldInfo

レコードセット内のフィールドに関する情報を取得します。

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

パラメーター

lpszName
フィールドの名前。

fieldinfo
CODBCFieldInfo構造体への参照。

nIndex
フィールドの 0 から始まるインデックス。

解説

関数の 1 つのバージョンでは、名前でフィールドを検索できます。 もう 1 つのバージョンでは、インデックスでフィールドを検索できます。

返される情報の説明については、 CODBCFieldInfo 構造体を参照してください。

レコードセットの作成の詳細については、「 Recordset: レコードセットの作成と終了 (ODBC)」を参照してください。

CRecordset::GetRecordCount

レコードセットのサイズを決定します。

long GetRecordCount() const;

戻り値

レコードセット内のレコードの数。レコードセットにレコードが含まれている場合は 0。レコード数を特定できない場合は -1。

解説

注意事項

レコード数は"高いウォーター マーク" として保持され、ユーザーがレコードを移動すると見なされる最も番号の高いレコードです。 レコードの合計数は、ユーザーが最後のレコードを超えて移動した後でのみ認識されます。 パフォーマンス上の理由から、 MoveLastを呼び出してもカウントは更新されません。 レコードを自分でカウントするには、IsEOFが 0 以外の値を返すまでMoveNextを繰り返し呼び出します。 CRecordset:AddNewとUpdateを使用してレコードを追加すると、カウントが増加します。CRecordset::Deleteを使用してレコードを削除すると、カウントが減少します。

CRecordset::GetRowsetSize

特定のフェッチ中に取得する行数の現在の設定を取得します。

DWORD GetRowsetSize() const;

戻り値

特定のフェッチ中に取得する行の数。

解説

一括行フェッチを使用している場合、レコードセットを開くときの既定の行セット サイズは 25 です。それ以外の場合は 1 です。

一括行フェッチを実装するには、Open メンバー関数の dwOptions パラメーターに CRecordset::useMultiRowFetch オプションを指定する必要があります。 行セット サイズの設定を変更するには、 SetRowsetSizeを呼び出します。

バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::GetRowsFetched

フェッチ後に取得されたレコードの数を決定します。

DWORD GetRowsFetched() const;

戻り値

特定のフェッチ後にデータ ソースから取得された行の数。

解説

これは、一括行フェッチを実装した場合に便利です。 通常、行セット のサイズは、フェッチから取得される行の数を示します。 ただし、レコードセット内の行の合計数は、1 つの行セットで取得される行の数にも影響します。 たとえば、レコードセットのサイズ設定が 4 のレコードが 10 個ある場合、 MoveNext を呼び出してレコードセットをループ処理すると、最終的な行セットには 2 つのレコードのみが含まれます。

一括行フェッチを実装するには、Open メンバー関数の dwOptions パラメーターに CRecordset::useMultiRowFetch オプションを指定する必要があります。 行セットのサイズを指定するには、 SetRowsetSize を呼び出します。

バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

例

CMultiCustomer rs(&m_dbCust);

// Set the rowset size
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// loop through the recordset by rowsets
while (!rs.IsEOF())
{
   for (int rowCount = 0; rowCount < (int)rs.GetRowsFetched(); rowCount++)
   {
      // do something
   }

   rs.MoveNext();
}

rs.Close();

CRecordset::GetRowStatus

現在の行セット内の行の状態を取得します。

WORD GetRowStatus(WORD wRow) const;

パラメーター

wRow
現在の行セット内の行の 1 から始まる位置。 この値の範囲は、1 から行セットのサイズまでです。

戻り値

行の状態値。 詳細については、「解説」を参照してください。

解説

GetRowStatus は、データ ソースから最後に取得されてから行の状態が変更されたか、 wRow に対応する行がフェッチされなかったことを示す値を返します。 次の表は、可能性のある戻り値の一覧です。

状態 の値 説明
SQL_ROW_SUCCESS 行は変更されません。
SQL_ROW_UPDATED 行が更新されました。
SQL_ROW_DELETED 行が削除されました。
SQL_ROW_ADDED 行が追加されました。
SQL_ROW_ERROR エラーが原因で行を取得できません。
SQL_ROW_NOROW wRowに対応する行はありません。

詳細については、Windows SDK の ODBC API 関数 SQLExtendedFetch を参照してください。

CRecordset::GetStatus

レコードセット内の現在のレコードのインデックスと、最後のレコードが表示されたかどうかを判断します。

void GetStatus(CRecordsetStatus& rStatus) const;

パラメーター

rStatus
CRecordsetStatus オブジェクトへの参照です。 詳細については、「解説」をご覧ください。

解説

CRecordset はインデックスの追跡を試みますが、状況によってはこれが不可能な場合があります。 説明については、 GetRecordCount を参照してください。

CRecordsetStatus構造体の形式は次のとおりです。

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

CRecordsetStatusの 2 つのメンバーには、次の意味があります。

  • m_lCurrentRecord レコードセット内の現在のレコードの 0 から始まるインデックス (既知の場合) を格納します。 インデックスを特定できない場合、このメンバーには AFX_CURRENT_RECORD_UNDEFINED (-2) が含まれます。 IsBOFが TRUE の場合 (空のレコードセットまたは最初のレコードの前にスクロールを試みる)、m_lCurrentRecordは AFX_CURRENT_RECORD_BOF (-1) に設定されます。 最初のレコードの場合は、0、2 番目のレコード 1 に設定されます。

  • m_bRecordCountFinal レコードセット内のレコードの合計数が決定された場合は 0 以外。 通常、これは、レコードセットの先頭から開始し、IsEOFが 0 以外の値を返すまでMoveNextを呼び出すことによって実現する必要があります。 このメンバーが 0 の場合、 GetRecordCountによって返されるレコード数 (-1 ではない場合) は、レコードの "高いウォーター マーク" カウントにすぎません。

CRecordset::GetSQL

このメンバー関数を呼び出して、レコードセットを開いたときにレコードセットのレコードを選択するために使用された SQL ステートメントを取得します。

const CString& GetSQL() const;

戻り値

SQL ステートメントを含むCStringへのconst参照。

解説

これは通常、SQL SELECT ステートメントです。 GetSQLによって返される文字列は読み取り専用です。

GetSQLによって返される文字列は、通常、lpszSQL パラメーター内のレコードセットに渡した文字列とOpenメンバー関数とは異なります。 これは、レコードセットは、 Openに渡した内容、 ClassWizardで指定した内容、 m_strFilter および m_strSort データ メンバーで指定した内容、および指定したパラメーターに基づいて完全な SQL ステートメントを構築するためです。 レコードセットがこの SQL ステートメントを構築する方法の詳細については、「 Recordset: レコードセットのレコードの選択方法 (ODBC)」を参照してください。

Note

このメンバー関数は、 Openを呼び出した後にのみ呼び出します。

CRecordset::GetTableName

レコードセットのクエリの基になる SQL テーブルの名前を取得します。

const CString& GetTableName() const;

戻り値

レコードセットがテーブルに基づいている場合は、テーブル名を含むCStringへのconst参照。それ以外の場合は空の文字列。

解説

GetTableName は、レコードセットがテーブルに基づいている場合にのみ有効であり、複数のテーブルまたは定義済みのクエリ (ストアド プロシージャ) の結合ではありません。 名前は読み取り専用です。

Note

このメンバー関数は、 Openを呼び出した後にのみ呼び出します。

CRecordset::IsBOF

レコードセットが最初のレコードの前に配置されている場合は、0 以外の値を返します。 現在のレコードはありません。

BOOL IsBOF() const;

戻り値

レコードセットにレコードが含まれている場合、または最初のレコードの前に後方にスクロールした場合は 0 以外。それ以外の場合は 0。

解説

レコードからレコードまでスクロールする前に、このメンバー関数を呼び出して、レコードセットの最初のレコードの前に移動したかどうかを確認します。 IsBOFをIsEOFと共に使用して、レコードセットにレコードが含まれているか空であるかを判断することもできます。 Openを呼び出した直後に、レコードセットにレコードが含まれている場合、IsBOFは 0 以外の値を返します。 少なくとも 1 つのレコードを含むレコードセットを開くと、最初のレコードが現在のレコードになり、 IsBOF 0 が返されます。

最初のレコードが現在のレコードで、 MovePrevを呼び出すと、 IsBOF は 0 以外の値を返します。 IsBOFが 0 以外の値を返し、MovePrevを呼び出すと、エラーが発生します。 IsBOFが 0 以外の値を返した場合、現在のレコードは未定義になり、現在のレコードを必要とするアクションはエラーになります。

例

この例では、 IsBOF と IsEOF を使用して、コードがレコードセットを双方向にスクロールする場合にレコードセットの制限を検出します。

// Open a recordset; first record is current
// Open a recordset; first record is current
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if(rsCustSet.IsBOF())
   return;
   // The recordset is empty

// Scroll to the end of the recordset, past
// the last record, so no record is current
while (!rsCustSet.IsEOF())
   rsCustSet.MoveNext();

// Move to the last record
rsCustSet.MoveLast();

// Scroll to beginning of the recordset, before
// the first record, so no record is current
while(!rsCustSet.IsBOF())
   rsCustSet.MovePrev();

// First record is current again
rsCustSet.MoveFirst();

CRecordset::IsDeleted

現在のレコードが削除されたかどうかを判断します。

BOOL IsDeleted() const;

戻り値

レコードセットが削除されたレコードに配置されている場合は 0 以外。それ以外の場合は 0。

解説

レコードまでスクロールIsDeletedTRUE (0 以外) が返される場合は、他のレコードセット操作を実行する前に、別のレコードまでスクロールする必要があります。

IsDeletedの結果は、レコードセットの種類、レコードセットが更新可能かどうか、レコードセットを開いたときにCRecordset::skipDeletedRecordsオプションを指定したかどうか、ドライバーパックでレコードが削除されたかどうか、複数のユーザーがあるかどうかなど、さまざまな要因によって異なります。

CRecordset::skipDeletedRecordsとドライバーのパッキングの詳細については、Open メンバー関数を参照してください。

Note

一括行フェッチを実装している場合は、 IsDeletedを呼び出さないでください。 代わりに、 GetRowStatus メンバー関数を呼び出します。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::IsEOF

レコードセットが最後のレコードの後に配置されている場合は、0 以外の値を返します。 現在のレコードはありません。

BOOL IsEOF() const;

戻り値

レコードセットにレコードが含まれている場合、または最後のレコードを超えてスクロールした場合は 0 以外。それ以外の場合は 0。

解説

レコードからレコードまでスクロールして、レコードセットの最後のレコードを超えたかどうかを確認するには、このメンバー関数を呼び出します。 IsEOFを使用して、レコードセットにレコードが含まれているか空であるかを判断することもできます。 Openを呼び出した直後に、レコードセットにレコードが含まれている場合、IsEOFは 0 以外の値を返します。 少なくとも 1 つのレコードを含むレコードセットを開くと、最初のレコードが現在のレコードになり、 IsEOF 0 が返されます。

MoveNextを呼び出すときに最後のレコードが現在のレコードである場合、IsEOFは 0 以外の値を返します。 IsEOFが 0 以外の値を返し、MoveNextを呼び出すと、エラーが発生します。 IsEOFが 0 以外の値を返した場合、現在のレコードは未定義になり、現在のレコードを必要とするアクションはエラーになります。

例

IsBOF の例を参照してください。

CRecordset::IsFieldDirty

指定したフィールド データ メンバーが、 Edit または AddNew が呼び出された後に変更されたかどうかを判断します。

BOOL IsFieldDirty(void* pv);

パラメーター

pv
状態を確認するフィールド データ メンバーへのポインター。または、いずれかのフィールドがダーティかどうかを判断 NULL 。

戻り値

AddNewまたはEditの呼び出し後に指定したフィールド データ メンバーが変更された場合は 0 以外、それ以外の場合は 0。

解説

現在のレコードが (Edit または AddNew の呼び出しの後に) CRecordsetの Update メンバー関数の呼び出しによって更新されると、すべてのダーティ フィールド データ メンバーのデータがデータ ソースのレコードに転送されます。

Note

このメンバー関数は、一括行フェッチを使用しているレコードセットには適用されません。 一括行フェッチを実装した場合、 IsFieldDirty は常に FALSE を返し、アサーションが失敗します。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

IsFieldDirtyを呼び出すと、フィールドのダーティ ステータスが再評価されるため、SetFieldDirty に対する前の呼び出しの影響がリセットされます。 AddNewの場合、現在のフィールド値が擬似 null 値と異なる場合、フィールドの状態はダーティに設定されます。 Editの場合、フィールド値がキャッシュされた値と異なる場合、フィールドの状態はダーティに設定されます。

IsFieldDirty は、 DoFieldExchangeによって実装されます。

ダーティ フラグの詳細については、「 Recordset: レコードセットのレコードの選択方法 (ODBC)」を参照してください。

CRecordset::IsFieldNull

現在のレコードの指定したフィールドが Null (値なし) の場合は、0 以外の値を返します。

BOOL IsFieldNull(void* pv);

パラメーター

pv
状態を確認するフィールド データ メンバーへのポインター。または、いずれかのフィールドが Null かどうかを判断するために NULL 。

戻り値

指定されたフィールド データ メンバーに Null のフラグが設定されている場合は 0 以外。それ以外の場合は 0。

解説

このメンバー関数を呼び出して、レコードセットの指定されたフィールド データ メンバーに Null のフラグが設定されているかどうかを確認します。 (データベース用語では、Null は "値を持たない" ことを意味し、C++ の NULL と同じではありません)。フィールド データ メンバーに Null のフラグが設定されている場合、値がない現在のレコードの列として解釈されます。

Note

このメンバー関数は、一括行フェッチを使用しているレコードセットには適用されません。 一括行フェッチを実装した場合、 IsFieldNull は常に FALSE を返し、アサーションが失敗します。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

IsFieldNull は、 DoFieldExchangeによって実装されます。

CRecordset::IsFieldNullable

現在のレコード内の指定したフィールドを Null (値を持たない) に設定できる場合は、0 以外の値を返します。

BOOL IsFieldNullable(void* pv);

パラメーター

pv
状態を確認するフィールド データ メンバーへのポインター。または、いずれかのフィールドを Null 値に設定できるかどうかを判断する NULL 。

解説

このメンバー関数を呼び出して、指定されたフィールド データ メンバーが "null 許容" かどうかを判断します (Null 値に設定できます。C++ NULL は Null と同じではありません。データベースの用語では、"値を持たない" ことを意味します)。

Note

一括行フェッチを実装している場合は、 IsFieldNullableを呼び出すことはできません。 代わりに、 GetODBCFieldInfo メンバー関数を呼び出して、フィールドを Null 値に設定できるかどうかを判断します。 一括行フェッチを実装しているかどうかに関係なく、いつでも GetODBCFieldInfoを呼び出すことができます。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

Null にできないフィールドには値が必要です。 レコードの追加または更新時にこのようなフィールドを Null に設定しようとすると、データ ソースは追加または更新を拒否し、 Update は例外をスローします。 この例外は、SetFieldNullを呼び出すときではなく、Updateを呼び出すときに発生します。

関数の最初の引数にNULLを使用すると、paramフィールドではなく、outputColumnフィールドにのみ関数が適用されます。 たとえば、呼び出し

SetFieldNull(NULL);

では、 outputColumn フィールドのみが NULLに設定されます。 param フィールドは影響を受けません。

paramフィールドで作業するには、次のように、作業する個々のparamの実際の住所を指定する必要があります。

SetFieldNull(&m_strParam);

つまり、outputColumn フィールドと同様に、すべてのparamフィールドをNULLに設定することはできません。

IsFieldNullable は、 DoFieldExchange によって実装されます。

CRecordset::IsOpen

レコードセットが既に開いているかどうかを判断します。

BOOL IsOpen() const;

戻り値

レコードセット オブジェクトの Open または Requery メンバー関数が以前に呼び出され、レコードセットが閉じていない場合は 0 以外。それ以外の場合は 0。

CRecordset::m_hstmt

レコードセットに関連付けられた ODBC ステートメントのデータ構造 ( HSTMT 型) へのハンドルが含まれます。

解説

ODBC データ ソースに対する各クエリは、 HSTMTに関連付けられています。

注意事項

Openが呼び出される前に、m_hstmtを使用しないでください。

通常、 HSTMT に直接アクセスする必要はありませんが、SQL ステートメントを直接実行するために必要な場合があります。 クラス CDatabaseの ExecuteSQL メンバー関数では、m_hstmtの使用例を示します。

CRecordset::m_nFields

レコードセット クラスのフィールド データ メンバーの数を格納します。つまり、データ ソースからレコードセットによって選択された列の数です。

解説

レコードセット クラスのコンストラクターは、正しい数値で m_nFields を初期化する必要があります。 一括行フェッチを実装していない場合は、 ClassWizard を使用してレコードセット クラスを宣言するときに、この初期化を書き込みます。 手動で記述することもできます。

フレームワークでは、この数値を使用して、フィールド データ メンバーと、データ ソース上の現在のレコードの対応する列の間の相互作用を管理します。

注意事項

この数は、パラメーター CFieldExchange::outputColumnでSetFieldTypeを呼び出した後に、DoFieldExchangeまたはDoBulkFieldExchangeに登録された "出力列" の数に対応している必要があります。

「レコードセット: データ列を動的にバインドする」の記事で説明されているように、列を動的にバインドできます。その場合は、動的にバインドされた列のDoFieldExchangeまたはDoBulkFieldExchangeメンバー関数内の RFX 関数呼び出しまたは一括 RFX 関数呼び出しの数を反映するために、m_nFieldsの数を増やす必要があります。

詳細については、「 Recordset: データ列の動的バインディング (ODBC) 」および「 Recordset: 一括レコードのフェッチ (ODBC)」を参照してください。

例

「 レコード フィールド交換: RFX の使用」を参照してください。

CRecordset::m_nParams

レコードセット クラスのパラメーター データ メンバーの数を格納します。つまり、レコードセットのクエリで渡されるパラメーターの数です。

解説

レコードセット クラスにパラメーター データ メンバーがある場合、クラスのコンストラクターは正しい数値で m_nParams 初期化する必要があります。 m_nParamsの値の既定値は 0 です。 パラメーター データ メンバーを追加する場合 (手動で行う必要があります)、パラメーターの数 ( m_strFilter または m_strSort 文字列内の '' プレースホルダーの数以上である必要があります) を反映するために、クラス コンストラクターに初期化を手動で追加する必要もあります。

フレームワークは、レコードセットのクエリをパラメーター化するときにこの数を使用します。

注意事項

この数は、パラメーター値が CFieldExchange::inputParam、CFieldExchange::param、CFieldExchange::outputParam、またはCFieldExchange::inoutParamのSetFieldTypeを呼び出した後に、DoFieldExchangeまたはDoBulkFieldExchangeに登録された "params" の数に対応している必要があります。

例

「 Recordset: Parameterizing a Recordset (ODBC) 」および「 Record Field Exchange: Using RFX」の記事を参照してください。

CRecordset::m_pDatabase

レコードセットがデータ ソースに接続されている CDatabase オブジェクトへのポインターを格納します。

解説

この変数は 2 つの方法で設定されます。 通常は、レコードセット オブジェクトを構築するときに、既に接続されている CDatabase オブジェクトへのポインターを渡します。 代わりに NULL 渡 CRecordset 、 CDatabase オブジェクトを作成して接続します。 どちらの場合も、 CRecordset はこの変数にポインターを格納します。

通常、 m_pDatabaseに格納されているポインターを直接使用する必要はありません。 ただし、 CRecordsetに独自の拡張機能を記述する場合は、ポインターの使用が必要になる場合があります。 たとえば、独自の CDBExceptionをスローする場合は、ポインターが必要になる場合があります。 または、トランザクションの実行、タイムアウトの設定、SQL ステートメントを直接実行するためにクラス CDatabaseの ExecuteSQL メンバー関数の呼び出しなど、同じCDatabase オブジェクトを使用して何かを行う必要がある場合に必要になる場合があります。

CRecordset::m_strFilter

レコードセット オブジェクトを構築した後、そのOpenメンバー関数を呼び出す前に、このデータ メンバーを使用して、SQL WHERE 句を含むCStringを格納します。

解説

レコードセットは、この文字列を使用して、 Open または Requery の呼び出し中に選択したレコードを制限 (またはフィルター処理) します。 これは、レコードのサブセット ("カリフォルニアに基づくすべての営業担当者" ("州 = CA") など) を選択する場合に役立ちます。 WHERE句の ODBC SQL 構文は次のとおりです。

WHERE search-condition

文字列に WHERE キーワードを含めないでください。 フレームワークによって提供されます。

また、フィルター文字列をパラメーター化するには、その中に '' プレースホルダーを配置し、各プレースホルダーのクラスでパラメーター データ メンバーを宣言し、実行時にパラメーターをレコードセットに渡します。 これにより、実行時にフィルターを構築できます。 詳細については、「レコードセット: パラメーターを利用したレコードセット (ODBC)」を参照してください。

SQL WHERE 句の詳細については、「 SQL」を参照してください。 レコードの選択とフィルター処理の詳細については、「 Recordset: Filtering Records (ODBC)」を参照してください。

例

CCustomer rsCustSet(&m_dbCust);

// Set the filter
rsCustSet.m_strFilter = _T("L_Name = 'Flanders'");

// Run the filtered query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::m_strSort

レコードセット オブジェクトを構築した後、そのOpenメンバー関数を呼び出す前に、このデータ メンバーを使用して、SQL ORDER BY 句を含むCStringを格納します。

解説

レコードセットは、この文字列を使用して、 Open または Requery 呼び出し中に選択したレコードを並べ替えます。 この機能を使用すると、1 つ以上の列でレコードセットを並べ替えることができます。 ORDER BY句の ODBC SQL 構文は次のとおりです。

ORDER BY sort-specification [, sort-specification]...

並べ替え指定が整数または列名である場合。 並べ替え文字列の列リストに "ASC" または "DESC" を追加することで、昇順または降順 (既定では昇順) を指定することもできます。 選択したレコードは、最初にリストされた最初の列、次に 2 番目の列で並べ替えられます。 たとえば、姓、名で "Customers" レコードセットを並べ替える場合があります。 一覧表示できる列の数は、データ ソースによって異なります。 詳細については、Windows SDK を参照してください。

文字列に ORDER BY キーワードを含めないでください。 フレームワークによって提供されます。

SQL 句の詳細については、「 SQL」を参照してください。 レコードの並べ替えの詳細については、「 Recordset: レコードの並べ替え (ODBC)」を参照してください。

例

CCustomer rsCustSet(&m_dbCust);

// Set the sort string
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");

// Run the sorted query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::Move

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

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

パラメーター

nRows
前後に移動する行の数。 正の値は、レコードセットの末尾に向かって前方に移動します。 負の値は、先頭に向かって後方に移動します。

wFetchType
Moveがフェッチする行セットを決定します。 詳細については、「解説」を参照してください。

解説

nRowsに値 0 を渡すと、Move現在のレコードが更新されます。Moveは現在のAddNewモードまたはEdit モードを終了し、AddNewまたはEditが呼び出される前に現在のレコードの値を復元します。

Note

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

Move では、レコードセットの位置が行セットごとに変更されます。 nRowsとwFetchTypeの値に基づいて、Moveは適切な行セットをフェッチし、その行セットの最初のレコードを現在のレコードにします。 一括行フェッチを実装していない場合、行セットのサイズは常に 1 になります。 行セットをフェッチする場合、MoveCheckRowsetError メンバー関数を直接呼び出して、フェッチによって発生したエラーを処理します。

渡す値に応じて、 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

Note

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

注意事項

レコードセットにレコードがない場合、 Move を呼び出すと例外がスローされます。 レコードセットにレコードがあるかどうかを確認するには、 IsBOF と IsEOFを呼び出します。

Note

レコードセットの先頭または末尾をスクロールした場合 (IsBOF または IsEOF は 0 以外の値を返します)、 Move 関数を呼び出すと、 CDBExceptionがスローされる可能性があります。 たとえば、 IsEOF が 0 以外の値を返し、 IsBOF 返さない場合、 MoveNext は例外をスローしますが、 MovePrev はスローしません。

Note

現在のレコードの更新中または追加中に Move を呼び出すと、更新は警告なしで失われます。

レコードセット ナビゲーションの詳細については、「レコードセット: スクロール (ODBC) 」および「 Recordset: Bookmarks and Absolute Positions (ODBC)」の記事を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。 関連情報については、Windows SDK の ODBC API 関数 SQLExtendedFetch を参照してください。

例

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

CRecordset::MoveFirst

最初の行セットの最初のレコードを現在のレコードにします。

void MoveFirst();

解説

一括行フェッチが実装されているかどうかに関係なく、これは常にレコードセットの最初のレコードになります。

レコードセットを開いた直後に MoveFirst を呼び出す必要はありません。 その時点で、最初のレコード (存在する場合) は自動的に現在のレコードになります。

Note

このメンバー関数は、前方のみのレコードセットでは有効ではありません。

Note

レコードセット内を移動する場合、削除されたレコードをスキップすることはできません。 詳細については、 IsDeleted メンバー関数を参照してください。

注意事項

レコードセットにレコードがない場合、 Move 関数のいずれかを呼び出すと例外がスローされます。 レコードセットにレコードがあるかどうかを確認するには、 IsBOF と IsEOFを呼び出します。

Note

現在のレコードの更新または追加中に Move 関数のいずれかを呼び出すと、更新は警告なしで失われます。

レコードセット ナビゲーションの詳細については、「レコードセット: スクロール (ODBC) 」および「 Recordset: Bookmarks and Absolute Positions (ODBC)」の記事を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

例

IsBOF の例を参照してください。

CRecordset::MoveLast

最後の完全な行セットの最初のレコードを現在のレコードにします。

void MoveLast();

解説

一括行フェッチを実装していない場合、レコードセットの行セット サイズは 1 であるため、 MoveLast レコードセット内の最後のレコードに移動します。

Note

このメンバー関数は、前方のみのレコードセットでは有効ではありません。

Note

レコードセット内を移動する場合、削除されたレコードをスキップすることはできません。 詳細については、 IsDeleted メンバー関数を参照してください。

注意事項

レコードセットにレコードがない場合、 Move 関数のいずれかを呼び出すと例外がスローされます。 レコードセットにレコードがあるかどうかを確認するには、 IsBOF と IsEOFを呼び出します。

Note

現在のレコードの更新または追加中に Move 関数のいずれかを呼び出すと、更新は警告なしで失われます。

レコードセット ナビゲーションの詳細については、「レコードセット: スクロール (ODBC) 」および「 Recordset: Bookmarks and Absolute Positions (ODBC)」の記事を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

例

IsBOF の例を参照してください。

CRecordset::MoveNext

次の行セットの最初のレコードを現在のレコードにします。

void MoveNext();

解説

一括行フェッチを実装していない場合、レコードセットの行セット サイズは 1 であるため、 MoveNext 次のレコードに移動します。

Note

レコードセット内を移動する場合、削除されたレコードをスキップすることはできません。 詳細については、 IsDeleted メンバー関数を参照してください。

注意事項

レコードセットにレコードがない場合、 Move 関数のいずれかを呼び出すと例外がスローされます。 レコードセットにレコードがあるかどうかを確認するには、 IsBOF と IsEOFを呼び出します。

Note

MoveNextを呼び出す前に、IsEOFを呼び出すこともできます。 たとえば、レコードセットの末尾を超えてスクロールした場合、 IsEOF は 0 以外の値を返します。後続の MoveNext の呼び出しでは例外がスローされます。

Note

現在のレコードの更新または追加中に Move 関数のいずれかを呼び出すと、更新は警告なしで失われます。

レコードセット ナビゲーションの詳細については、「レコードセット: スクロール (ODBC) 」および「 Recordset: Bookmarks and Absolute Positions (ODBC)」の記事を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

例

IsBOF の例を参照してください。

CRecordset::MovePrev

前の行セットの最初のレコードを現在のレコードにします。

void MovePrev();

解説

一括行フェッチを実装していない場合、レコードセットの行セット サイズは 1 であるため、 MovePrev 前のレコードに移動します。

Note

このメンバー関数は、前方のみのレコードセットでは有効ではありません。

Note

レコードセット内を移動する場合、削除されたレコードをスキップすることはできません。 詳細については、 IsDeleted メンバー関数を参照してください。

注意事項

レコードセットにレコードがない場合、 Move 関数のいずれかを呼び出すと例外がスローされます。 レコードセットにレコードがあるかどうかを確認するには、 IsBOF と IsEOFを呼び出します。

Note

MovePrevを呼び出す前に、IsBOFを呼び出すこともできます。 たとえば、レコードセットの先頭より前にスクロールした場合、 IsBOF は 0 以外の値を返します。後続の MovePrev の呼び出しでは例外がスローされます。

Note

現在のレコードの更新または追加中に Move 関数のいずれかを呼び出すと、更新は警告なしで失われます。

レコードセット ナビゲーションの詳細については、「レコードセット: スクロール (ODBC) 」および「 Recordset: Bookmarks and Absolute Positions (ODBC)」の記事を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

例

IsBOF の例を参照してください。

CRecordset::OnSetOptions

指定した ODBC ステートメントのオプション (選択時に使用) を設定するために呼び出されます。

virtual void OnSetOptions(HSTMT hstmt);

パラメーター

hstmt
オプションを設定する ODBC ステートメントの HSTMT 。

解説

OnSetOptionsを呼び出して、指定した ODBC ステートメントのオプション (選択時に使用) を設定します。 フレームワークは、このメンバー関数を呼び出して、レコードセットの初期オプションを設定します。 OnSetOptions は、スクロール可能なカーソルとカーソルのコンカレンシーに対するデータ ソースのサポートを決定し、それに応じてレコードセットのオプションを設定します。 ( OnSetOptions は選択操作に使用されますが、 OnSetUpdateOptions は更新操作に使用されます)。

ドライバーまたはデータ ソースに固有のオプションを設定するには、 OnSetOptions をオーバーライドします。 たとえば、データ ソースが排他的アクセスのオープンをサポートしている場合は、その機能を利用するために OnSetOptions をオーバーライドできます。

カーソルの詳細については、 ODBCを参照してください。

CRecordset::OnSetUpdateOptions

指定した ODBC ステートメントのオプション (更新時に使用) を設定するために呼び出されます。

virtual void OnSetUpdateOptions(HSTMT hstmt);

パラメーター

hstmt
オプションを設定する ODBC ステートメントの HSTMT 。

解説

OnSetUpdateOptionsを呼び出して、指定した ODBC ステートメントのオプション (更新時に使用) を設定します。 フレームワークは、レコードセット内のレコードを更新する HSTMT を作成した後、このメンバー関数を呼び出します。 ( OnSetOptions は選択操作に使用されますが、 OnSetUpdateOptions は更新操作に使用されます)。 OnSetUpdateOptions は、スクロール可能なカーソルとカーソルのコンカレンシーに対するデータ ソースのサポートを決定し、それに応じてレコードセットのオプションを設定します。

OnSetUpdateOptionsオーバーライドして ODBC ステートメントのオプションを設定してから、そのステートメントを使用してデータベースにアクセスします。

カーソルの詳細については、 ODBCを参照してください。

CRecordset::Open

テーブルを取得するか、レコードセットが表すクエリを実行して、レコードセットを開きます。

virtual BOOL Open(
    UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    DWORD dwOptions = none);

パラメーター

nOpenType
既定値をそのまま使用するか、 AFX_DB_USE_DEFAULT_TYPEするか、 enum OpenTypeの次のいずれかの値を使用します。

  • CRecordset::dynaset 双方向スクロールを含むレコードセット。 レコードセットを開くとレコードのメンバーシップと順序が決まりますが、他のユーザーがデータ値に加えた変更は、フェッチ操作の後に表示されます。 ダイナセットは、キーセット ドリブン レコードセットとも呼ばれます。

  • CRecordset::snapshot 双方向スクロールを含む静的レコードセット。 レコードセットを開くと、レコードのメンバーシップと順序が決まります。 レコードをフェッチすると、データ値が決まります。 他のユーザーによって行われた変更は、レコードセットが閉じてから再度開かれるまで表示されません。

  • CRecordset::dynamic 双方向スクロールを含むレコードセット。 他のユーザーが行ったメンバーシップ、順序、およびデータ値の変更は、フェッチ操作後に表示されます。 多くの ODBC ドライバーでは、この種類のレコードセットはサポートされていません。

  • CRecordset::forwardOnly 前方スクロールのみを含む読み取り専用レコードセット。

    CRecordsetの場合、既定値は CRecordset::snapshot です。 既定値の機構により、Visual C++ ウィザードで既定値の異なる ODBC CRecordset と DAO CDaoRecordset 両方を操作できます。

これらのレコードセットの種類の詳細については、「 Recordset (ODBC)」を参照してください。 関連情報については、Windows SDK の「ブロックカーソルとスクロール可能カーソルの使用」を参照してください。

注意事項

要求された型がサポートされていない場合、フレームワークは例外をスローします。

lpszSQL
次のいずれかを含む文字列ポインター:

  • NULL ポインター。

  • テーブルの名前。

  • SQL SELECT ステートメント (必要に応じて、SQL WHERE 句または ORDER BY 句を使用)。

  • 定義済みのクエリ (ストアド プロシージャ) の名前を指定する CALL ステートメント。 中かっこと CALL キーワードの間に空白を挿入しないように注意してください。

この文字列の詳細については、「 Remarks 」セクションの ClassWizard の役割の表と説明を参照してください。

Note

結果セット内の列の順序は、 DoFieldExchange または DoBulkFieldExchange 関数オーバーライドの RFX 関数呼び出しまたは一括 RFX 関数呼び出しの順序と一致する必要があります。

dwOptions
ビットマスク。以下に示す値の組み合わせを指定できます。 これらの値の一部は同時に指定できません。 既定値は none です。

  • CRecordset::none オプションは設定されていません。 このパラメーター値は、他のすべての値と同時に指定できません。 既定では、レコードセットは Edit または Delete で更新でき、新しいレコードを AddNewで追加できます。 更新可能性は、指定したデータ ソースと nOpenType オプションによって異なります。 一括追加の最適化は使用できません。 一括行フェッチは実装されません。 削除されたレコードは、レコードセットのナビゲーション中にスキップされません。 ブックマークは使用できません。 自動ダーティ フィールド チェックが実装されます。

  • CRecordset::appendOnly レコードセットの Edit または Delete を許可しないでください。 AddNew のみ実行できます。 このオプションは CRecordset::readOnly と同時に指定できません。

  • CRecordset::readOnly レコードセットを読み取り専用で開きます。 このオプションは CRecordset::appendOnly と同時に指定できません。

  • CRecordset::optimizeBulkAdd 準備された SQL ステートメントを使用して、一度に多数のレコードの追加を最適化します。 ODBC API 関数 SQLSetPos を使用してレコードセットを更新していない場合にのみ適用されます。 最新の更新で、ダーティとマークされるフィールドが決まります。 このオプションは CRecordset::useMultiRowFetch と同時に指定できません。

  • CRecordset::useMultiRowFetch 一括行フェッチを実装して、1 回のフェッチ操作で複数の行を取得できるようにします。 これは、パフォーマンスを向上させるために設計された高度な機能です。ただし、一括レコード フィールドの交換は、 ClassWizardではサポートされていません。 このオプションは CRecordset::optimizeBulkAdd と同時に指定できません。 CRecordset::useMultiRowFetchを指定すると、オプション CRecordset::noDirtyFieldCheckが自動的にオンになります (二重バッファリングは使用できません)。順方向専用レコードセットでは、オプション CRecordset::useExtendedFetchが自動的にオンになります。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

  • CRecordset::skipDeletedRecords レコードセット内を移動するときに、削除されたすべてのレコードをスキップします。 これにより、特定の相対フェッチでパフォーマンスが低下します。 このオプションは、前方のみのレコードセットでは有効ではありません。 nRowsパラメーターを 0 に設定し、CRecordset::skipDeletedRecords オプションを設定してMoveを呼び出すと、Moveがアサートされます。 CRecordset::skipDeletedRecords は、 driver パッキングに似ています。つまり、削除された行はレコードセットから削除されます。 ただし、ドライバーがレコードをパックすると、削除したレコードのみがスキップされます。レコードセットが開いている間、他のユーザーによって削除されたレコードはスキップされません。 CRecordset::skipDeletedRecords は、他のユーザーによって削除された行をスキップします。

  • CRecordset::useBookmarks サポートされている場合は、レコードセットでブックマークを使用できます。 ブックマークを使用すると、データの取得速度は低下しますが、データ移動のパフォーマンスが向上します。 前方スクロール専用レコードセットでは無効です。 詳細については、「 Recordset: Bookmarks and Absolute Positions (ODBC)」を参照してください。

  • CRecordset::noDirtyFieldCheck ダーティ フィールドの自動チェック (ダブル バッファリング) をオフにします。 これにより、パフォーマンスが向上します。ただし、 SetFieldDirty および SetFieldNull メンバー関数を呼び出して、フィールドをダーティとして手動でマークする必要があります。 クラス CRecordset でのダブル バッファリングは、クラス CDaoRecordsetでのダブル バッファリングに似ています。 ただし、 CRecordsetでは、個々のフィールドでダブル バッファリングを有効にすることはできません。すべてのフィールドに対して有効にするか、すべてのフィールドに対して無効にします。 オプション CRecordset::useMultiRowFetchを指定すると、 CRecordset::noDirtyFieldCheck は自動的にオンになります。ただし、一括行フェッチを実装するレコードセットでは、 SetFieldDirty と SetFieldNull を使用することはできません。

  • CRecordset::executeDirect 準備された SQL ステートメントは使用しないでください。 パフォーマンスを向上させるために、 Requery メンバー関数が呼び出されない場合は、このオプションを指定します。

  • CRecordset::useExtendedFetchSQLFetchの代わりにSQLExtendedFetchを実装します。 これは、前方スクロール専用レコードセットに対してバルク行フェッチを実装するために設計されています。 前方専用レコードセットに CRecordset::useMultiRowFetch オプションを指定すると、 CRecordset::useExtendedFetch が自動的にオンになります。

  • CRecordset::userAllocMultiRowBuffers ユーザーは、データのストレージ バッファーを割り当てます。 独自のストレージを割り当てる場合は、 CRecordset::useMultiRowFetch でこのオプションを使用します。 それ以外の場合、フレームワークは必要なストレージを自動的に割り当てます。 詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。 CRecordset::useMultiRowFetchを指定せずにCRecordset::userAllocMultiRowBuffersを指定すると、アサーションが失敗します。

戻り値

CRecordset オブジェクトが正常に開かれた場合は 0 以外、CDatabase::Open (呼び出された場合) が 0 を返す場合は 0。

解説

レコードセットによって定義されたクエリを実行するには、このメンバー関数を呼び出す必要があります。 Openを呼び出す前に、レコードセット オブジェクトを構築する必要があります。

このレコードセットのデータ ソースへの接続は、 Openを呼び出す前にレコードセットを構築する方法によって異なります。 データ ソースに接続されていないレコードセット コンストラクターに CDatabase オブジェクトを渡すと、このメンバー関数は GetDefaultConnect を使用してデータベース オブジェクトを開こうとします。 レコードセット コンストラクターに NULL を渡すと、コンストラクターによって CDatabase オブジェクトが作成され、データベース オブジェクトの接続が試行 Open 。 このような状況でレコードセットと接続を閉じる方法の詳細については、 Closeを参照してください。

Note

CRecordset オブジェクトを使用したデータ ソースへのアクセスは常に共有されます。 CDaoRecordset クラスとは異なり、CRecordset オブジェクトを使用して排他アクセス権を持つデータ ソースを開くことはありません。

Openを呼び出すと、クエリ (通常は SQL SELECT ステートメント) は、次の表に示す条件に基づいてレコードを選択します。

パラメーター lpszSQL の値。 レコードの選択基準 例
NULL GetDefaultSQL の返す文字列。
SQL テーブル名 DoFieldExchange または DoBulkFieldExchange のテーブル リストのすべての列。 "Customer"
定義済みクエリ (ストアド プロシージャ) の名前 返すためにクエリが定義された列。 "{call OverDueAccts}"
SELECT column-list FROM table-list 指定したテーブルの指定した列。 "SELECT CustId, CustName FROM

Customer"

注意事項

SQL 文字列に余分な空白を挿入しないでください。 たとえば、中かっこと CALL キーワードの間に空白を挿入すると、MFC によって SQL 文字列がテーブル名として誤って解釈され、 SELECT ステートメントに組み込まれ、例外がスローされます。 同様に、定義済みのクエリで出力パラメーターを使用する場合は、中かっこと '' 記号の間に空白を挿入しないでください。 最後に、CALL ステートメントの中かっこの前、または SELECT ステートメントの SELECT キーワードの前に空白を挿入しないでください。

通常の手順では、 NULL を Openに渡します。この場合、 Open はGetDefaultSQL 呼び出。 派生CRecordset クラスを使用している場合は、ClassWizardで指定したテーブル名GetDefaultSQL指定します。 代わりに、その他の情報を lpszSQL パラメーターに指定できます。

何を渡しても、Openはクエリの最終的な SQL 文字列を構築し (文字列に渡したlpszSQL文字列に SQL WHERE句とORDER BY句が付加されている可能性があります)、クエリを実行します。 Openを呼び出した後でGetSQLを呼び出すことで、構築された文字列を調べることができます。 レコードセットが SQL ステートメントを構築してレコードを選択する方法の詳細については、「 Recordset: レコードセットがレコードを選択する方法 (ODBC)」を参照してください。

レコードセット クラスのフィールド データ メンバーは、選択したデータの列に結び付けられています。 いくつかのレコードが返された場合、最初のレコードが現在のレコードになります。

フィルターや並べ替えなどのレコードセットのオプションを設定する場合は、レコードセット オブジェクトを作成した後、 Openを呼び出す前に、これらを指定します。 レコードセットが既に開いている後にレコードセット内のレコードを更新する場合は、 Requeryを呼び出します。

その他の例を含む詳細については、「 Recordset (ODBC)、 Recordset: レコードセットの選択方法 (ODBC)、および Recordset: Createing and Closing Recordsets (ODBC)を参照してください。

例

次のコード例は、 Open 呼び出しのさまざまな形式を示しています。

// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived 
// objects

// Open rs using the default SQL statement, implement bookmarks, and turn 
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
   CRecordset::noDirtyFieldCheck);

// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));

// Accept all defaults
rsDefault.Open();

CRecordset::RefreshRowset

現在の行セット内の行のデータと状態を更新します。

void RefreshRowset(
    WORD wRow,
    WORD wLockType = SQL_LOCK_NO_CHANGE);

パラメーター

wRow
現在の行セット内の行の 1 から始まる位置。 この値の範囲は、0 から行セットのサイズまでです。

wLockType
更新後に行をロックする方法を示す値。 詳細については、「解説」を参照してください。

解説

wRowに 0 の値を渡すと、行セット内のすべての行が更新されます。

RefreshRowsetを使用するには、Open メンバー関数で CRecordset::useMulitRowFetch オプションを指定して、一括行フェッチを実装している必要があります。

RefreshRowset は ODBC API 関数 SQLSetPosを呼び出します。 wLockType パラメーターは、SQLSetPosが実行された後の行のロック状態を指定します。 次の表では、 wLockTypeに使用できる値について説明します。

wLockType 説明
SQL_LOCK_NO_CHANGE (既定値) ドライバーまたはデータ ソースは、行が呼び出される前と同じロックまたはロック解除状態 RefreshRowset 確認します。
SQL_LOCK_EXCLUSIVE ドライバーまたはデータ ソースは、行を排他的にロックします。 すべてのデータ ソースがこの種類のロックをサポートしているわけではありません。
SQL_LOCK_UNLOCK ドライバーまたはデータ ソースによって行のロックが解除されます。 すべてのデータ ソースがこの種類のロックをサポートしているわけではありません。

SQLSetPosの詳細については、Windows SDK を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::Requery

レコードセットを再構築 (更新) します。

virtual BOOL Requery();

戻り値

レコードセットが正常に再構築された場合は 0 以外。それ以外の場合は 0。

解説

いくつかのレコードが返された場合、最初のレコードが現在のレコードになります。

自分または他のユーザーがデータ ソースに対して行っている追加と削除をレコードセットに反映させるには、 Requeryを呼び出してレコードセットを再構築する必要があります。 レコードセットがダイナセットの場合、自分または他のユーザーが既存のレコードに対して行った更新が自動的に反映されます (ただし、追加は反映されません)。 レコードセットがスナップショットの場合は、他のユーザーによる編集と追加と削除を反映するために Requery を呼び出す必要があります。

ダイナセットまたはスナップショットの場合は、新しいフィルターまたは並べ替え、または新しいパラメーター値を使用してレコードセットを再構築する場合は、いつでも Requery 呼び出します。 Requeryを呼び出す前に、新しい値をm_strFilterとm_strSortに割り当てることで、新しいフィルターまたは並べ替えプロパティを設定します。 Requeryを呼び出す前に、パラメーター データ メンバーに新しい値を割り当てることで、新しいパラメーターを設定します。 フィルター文字列と並べ替え文字列が変更されていない場合は、クエリを再利用できるため、パフォーマンスが向上します。

レコードセットの再構築が失敗した場合、レコードセットは閉じられます。 Requeryを呼び出す前に、CanRestart メンバー関数を呼び出してレコードセットを再クエリできるかどうかを判断できます。 CanRestart は、 Requery が成功することを保証しません。

注意事項

Openを呼び出した後にのみ、Requeryを呼び出します。

例

次の使用例は、別の並べ替え順序を適用するためにレコードセットを再構築します。

CCustomer rsCustSet(&m_dbCust);

// Open the recordset
rsCustSet.Open();

// Use the recordset ...

// Set the sort order and Requery the recordset
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");
if (!rsCustSet.CanRestart())
return;    // Unable to requery

if (!rsCustSet.Requery())
// Requery failed, so take action
AfxMessageBox(_T("Requery failed!"));

CRecordset::SetAbsolutePosition

指定したレコード番号に対応するレコードにレコードセットを配置します。

void SetAbsolutePosition(long nRows);

パラメーター

nRows
レコードセット内の現在のレコードの 1 から始まる序数位置。

解説

SetAbsolutePosition は、この序数の位置に基づいて現在のレコード ポインターを移動します。

Note

このメンバー関数は、前方のみのレコードセットでは有効ではありません。

ODBC レコードセットの場合、絶対位置を 1 に設定すると、レコードセット内の最初のレコードが参照されます。0 に設定すると、ファイルの先頭 (BOF) の位置が参照されます。

負の値を SetAbsolutePositionに渡すこともできます。 この場合、レコードセットの位置はレコードセットの末尾から評価されます。 たとえば、 SetAbsolutePosition( -1 ) は、現在のレコード ポインターをレコードセット内の最後のレコードに移動します。

Note

絶対位置は、サロゲート レコード番号として使用されるものではありません。 ブックマークは、前のレコードが削除されるときにレコードの位置が変更されるため、特定の位置を保持して戻す場合に推奨される方法です。 また、レコードセット内の個々のレコードの順序は、 ORDER BY 句を使用して SQL ステートメントを使用して作成されない限り保証されないため、レコードセットが再作成された場合、特定のレコードが同じ絶対位置を持つことは保証できません。

レコードセットのナビゲーションとブックマークの詳細については、「レコードセット: スクロール (ODBC) 」および「 Recordset: Bookmarks and Absolute Positions (ODBC)」を参照してください。

CRecordset::SetBookmark

指定したブックマークを含むレコードにレコードセットを配置します。

void SetBookmark(const CDBVariant& varBookmark);

パラメーター

varBookmark
特定のレコードのブックマーク値を含む CDBVariant オブジェクトへの参照。

解説

ブックマークがレコードセットでサポートされているかどうかを確認するには、 CanBookmarkを呼び出します。 サポートされている場合にブックマークを使用できるようにするには、Open メンバー関数の dwOptions パラメーターで CRecordset::useBookmarks オプションを設定する必要があります。

Note

ブックマークがサポートされていないか使用できない場合、 SetBookmark を呼び出すと例外がスローされます。 ブックマークは、前方専用レコードセットではサポートされていません。

最初に現在のレコードのブックマークを取得するには、 GetBookmarkを呼び出します。これにより、ブックマーク値が CDBVariant オブジェクトに保存されます。 後で、保存されたブックマーク値を使用して SetBookmark を呼び出すことによって、そのレコードに戻ることができます。

Note

特定のレコードセット操作の後、 SetBookmarkを呼び出す前にブックマークの永続化を確認する必要があります。 たとえば、 GetBookmark でブックマークを取得し、 Requeryを呼び出すと、ブックマークが無効になる可能性があります。 CDatabase::GetBookmarkPersistenceを呼び出して、SetBookmarkを安全に呼び出すことができるかどうかを確認します。

ブックマークとレコードセットのナビゲーションの詳細については、「レコードセット: ブックマークと絶対位置 (ODBC)」およびRecordset: Scrolling (ODBC)に関する記事を参照してください。

CRecordset::SetFieldDirty

レコードセットのフィールド データ メンバーに変更または変更されていないフラグを設定します。

void SetFieldDirty(void* pv, BOOL bDirty = TRUE);

パラメーター

pv
レコードセットまたは NULL 内のフィールド データ メンバーのアドレスを格納します。 NULL場合、レコードセット内のすべてのフィールド データ メンバーにフラグが設定されます。 (C++ NULL は、データベース用語の Null と同じではありません。つまり、"値がありません")。

bDirty
TRUE フィールド データ メンバーが "ダーティ" (変更済み) としてフラグが設定される場合。 それ以外の場合は、フィールド データ メンバーに "clean" (変更なし) のフラグが設定される場合に FALSE 。

解説

フィールドを変更せずにマークすると、フィールドが更新されず、SQL トラフィックが少なくなります。

Note

このメンバー関数は、一括行フェッチを使用しているレコードセットには適用されません。 一括行フェッチを実装した場合、 SetFieldDirty アサーションが失敗します。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

フレームワークは、変更されたフィールド データ メンバーがレコード フィールド交換 (RFX) メカニズムによってデータ ソース上のレコードに確実に書き込まれるようにマークします。 フィールドの値を変更すると、通常、フィールドは自動的にダーティに設定されるため、自分で SetFieldDirty を呼び出す必要はほとんどありませんが、フィールド データ メンバーの値に関係なく、列が明示的に更新または挿入されるようにしたい場合があります。

注意事項

EditまたはAddNewを呼び出した後にのみ、このメンバー関数を呼び出します。

関数の最初の引数にNULLを使用すると、paramフィールドではなく、outputColumnフィールドにのみ関数が適用されます。 たとえば、呼び出し

SetFieldNull(NULL);

では、 outputColumn フィールドのみが NULLに設定されます。 param フィールドは影響を受けません。

paramフィールドで作業するには、次のように、作業する個々のparamの実際の住所を指定する必要があります。

SetFieldNull(&m_strParam);

つまり、outputColumn フィールドと同様に、すべてのparamフィールドをNULLに設定することはできません。

CRecordset::SetFieldNull

レコードセットのフィールド データ メンバーに Null (具体的には値がない) または Null 以外の値としてフラグを設定します。

void SetFieldNull(void* pv, BOOL bNull = TRUE);

パラメーター

pv
レコードセットまたは NULL内のフィールド データ メンバーのアドレスを格納します。 NULL場合、レコードセット内のすべてのフィールド データ メンバーにフラグが設定されます。 (C++ NULL は、データベース用語の Null と同じではありません。つまり、"値がありません")。

bNull
フィールド データ メンバーに値なし (Null) のフラグを設定する場合は 0 以外。 フィールド データ メンバーに Null 以外のフラグを設定する場合は、それ以外の場合は 0。

解説

レコードセットに新しいレコードを追加すると、すべてのフィールド データ メンバーが最初に Null 値に設定され、"ダーティ" (変更済み) としてフラグが設定されます。 データ ソースからレコードを取得する場合、その列には既に値が含まれるか、Null になります。

Note

一括行フェッチを使用しているレコードセットでは、このメンバー関数を呼び出さないでください。 一括行フェッチを実装した場合、 SetFieldNull 呼び出すとアサーションが失敗します。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

現在のレコードのフィールドに値を指定しない場合は、bNullを TRUE に設定して SetFieldNull を呼び出して Null としてフラグを設定します。 フィールドが以前に Null とマークされていて、値を指定する場合は、その新しい値を設定します。 SetFieldNullで Null フラグを削除する必要はありません。 フィールドを Null にできるかどうかを判断するには、 IsFieldNullableを呼び出します。

注意事項

EditまたはAddNewを呼び出した後にのみ、このメンバー関数を呼び出します。

関数の最初の引数にNULLを使用すると、paramフィールドではなく、outputColumnフィールドにのみ関数が適用されます。 たとえば、呼び出し

SetFieldNull(NULL);

では、 outputColumn フィールドのみが NULLに設定されます。 param フィールドは影響を受けません。

paramフィールドで作業するには、次のように、作業する個々のparamの実際の住所を指定する必要があります。

SetFieldNull(&m_strParam);

つまり、outputColumn フィールドと同様に、すべてのparamフィールドをNULLに設定することはできません。

Note

パラメーターを Null に設定すると、レコードセットを開く前に SetFieldNull を呼び出すとアサーションが発生します。 この場合は、 SetParamNullを呼び出します。

SetFieldNull は、 DoFieldExchangeによって実装されます。

CRecordset::SetLockingMode

ロック モードを "オプティミスティック" ロック (既定) または "ペシミスティック" ロックに設定します。 更新プログラムのレコードのロック方法を決定します。

void SetLockingMode(UINT nMode);

パラメーター

nMode
enum LockModeの次のいずれかの値が含まれています。

  • optimistic オプティミスティック ロックは、 Updateの呼び出し中にのみ更新されるレコードをロックします。

  • pessimistic ペシミスティック ロックは、 Edit が呼び出されるとすぐにレコードをロックし、 Update 呼び出しが完了するか、新しいレコードに移動するまでロックを維持します。

解説

レコードセットが更新に使用する 2 つのレコード ロック戦略のうちどれを指定する必要がある場合は、このメンバー関数を呼び出します。 既定では、レコードセットのロック モードは optimistic。 これは、ロック戦略 pessimistic より慎重に変更できます。 レコードセット オブジェクトを構築して開いた後、Editを呼び出す前に、SetLockingModeを呼び出します。

CRecordset::SetParamNull

パラメーターに Null (具体的には値を持たない) または Null 以外のフラグを設定します。

void SetParamNull(
    int nIndex,
    BOOL bNull = TRUE);

パラメーター

nIndex
パラメーターの 0 から始まるインデックス。

bNull
TRUE (既定値) の場合、パラメーターには Null のフラグが設定されます。 それ以外の場合、パラメーターには Null 以外のフラグが設定されます。

解説

SetFieldNullとは異なり、レコードセットを開く前にSetParamNullを呼び出すことができます。

SetParamNull は、通常、定義済みのクエリ (ストアド プロシージャ) で使用されます。

CRecordset::SetRowsetCursorPosition

カーソルを現在の行セット内の行に移動します。

void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE);

パラメーター

wRow
現在の行セット内の行の 1 から始まる位置。 この値の範囲は、1 から行セットのサイズまでです。

wLockType
更新後に行をロックする方法を示す値。 詳細については、「解説」を参照してください。

解説

一括行フェッチを実装する場合、レコードは行セットによって取得されます。ここで、フェッチされた行セットの最初のレコードは現在のレコードです。 行セット内の別のレコードを現在のレコードにするには、 SetRowsetCursorPositionを呼び出します。 たとえば、 SetRowsetCursorPosition を GetFieldValue メンバー関数と組み合わせて、レコードセットの任意のレコードからデータを動的に取得できます。

SetRowsetCursorPositionを使用するには、Open メンバー関数で dwOptions パラメーターのCRecordset::useMultiRowFetch オプションを指定して、一括行フェッチを実装する必要があります。

SetRowsetCursorPosition は ODBC API 関数 SQLSetPosを呼び出します。 wLockType パラメーターは、SQLSetPosが実行された後の行のロック状態を指定します。 次の表では、 wLockTypeに使用できる値について説明します。

wLockType 説明
SQL_LOCK_NO_CHANGE (既定値) ドライバーまたはデータ ソースは、行が呼び出される前と同じロックまたはロック解除状態 SetRowsetCursorPosition 確認します。
SQL_LOCK_EXCLUSIVE ドライバーまたはデータ ソースは、行を排他的にロックします。 すべてのデータ ソースがこの種類のロックをサポートしているわけではありません。
SQL_LOCK_UNLOCK ドライバーまたはデータ ソースによって行のロックが解除されます。 すべてのデータ ソースがこの種類のロックをサポートしているわけではありません。

SQLSetPosの詳細については、Windows SDK を参照してください。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::SetRowsetSize

フェッチ中に取得するレコードの数を指定します。

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

パラメーター

dwNewRowsetSize
特定のフェッチ中に取得する行の数。

解説

この仮想メンバー関数は、一括行フェッチを使用するときに、1 回のフェッチ中に取得する行の数を指定します。 一括行フェッチを実装するには、Open メンバー関数の dwOptions パラメーターに CRecordset::useMultiRowFetch オプションを設定する必要があります。

Note

一括行フェッチを実装せずに SetRowsetSize を呼び出すと、アサーションが失敗します。

Openを呼び出す前にSetRowsetSizeを呼び出して、レコードセットの行セット サイズを最初に設定します。 一括行フェッチを実装するときの既定の行セット サイズは 25 です。

Note

SetRowsetSizeを呼び出すときは注意が必要です。 データのストレージを手動で割り当てる場合 (Openの dwOptions パラメーターのCRecordset::userAllocMultiRowBuffers オプションで指定されている場合)、SetRowsetSizeを呼び出した後、カーソル ナビゲーション操作を実行する前に、これらのストレージ バッファーを再割り当てする必要があるかどうかを確認する必要があります。

行セット サイズの現在の設定を取得するには、 GetRowsetSizeを呼び出します。

バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

CRecordset::Update

新しいデータまたは編集されたデータをデータ ソースに保存して、 AddNew または Edit 操作を完了します。

virtual BOOL Update();

戻り値

1 つのレコードが正常に更新された場合は 0 以外。列が変更されていない場合は 0。 レコードが更新されなかった場合、または複数のレコードが更新された場合は、例外がスローされます。 データ ソースのその他のエラーに対しても例外がスローされます。

解説

AddNewまたはメンバー関数の呼び出し後に、このメンバー関数Edit呼び出します。 この呼び出しは、 AddNew または Edit 操作を完了するために必要です。

Note

一括行フェッチを実装している場合は、 Updateを呼び出すことはできません。 これにより、アサーションが失敗します。 クラス CRecordset には、データの一括行を更新するためのメカニズムは用意されていませんが、ODBC API 関数 SQLSetPosを使用して独自の関数を記述できます。 バルク行フェッチの詳細については、「レコードセット: バルク行フェッチ (ODBC)」を参照してください。

AddNewとEditの両方で、追加または編集されたデータをデータ ソースに保存するために配置する編集バッファーを準備します。 Update はデータを保存します。 変更済みとしてマークまたは検出されたフィールドのみが更新されます。

データ ソースがトランザクションをサポートしている場合は、トランザクションの Update 呼び出し (およびその対応する AddNew または Edit 呼び出し) を行うことができます。 トランザクションの詳細情報については、「トランザクション (ODBC)」を参照してください。

注意事項

AddNewまたはEditを最初に呼び出さずにUpdateを呼び出すと、UpdateはCDBExceptionをスローします。 AddNewまたはEditを呼び出す場合は、Move操作を呼び出す前、またはレコードセットまたはデータ ソース接続を閉じる前に、Updateを呼び出す必要があります。 それ以外の場合、変更は通知なしで失われます。

Updateエラーの処理の詳細については、「Recordset: レコードセットのレコードの更新方法 (ODBC)」を参照してください。

例

「 トランザクション: レコードセット (ODBC) でのトランザクションの実行」を参照してください。

関連項目

CObject クラス
階層グラフ
CDatabase クラス
CRecordView クラス