CRowset クラス

[アーティクル]
07/19/2022

OLE DB 行セットオブジェクトといくつかの関連するインターフェイスをカプセル化し、行セットデータの操作メソッドを提供します。

構文

template <class TAccessor = CAccessorBase>
class CRowset

パラメーター

TAccessor
アクセサークラス。既定値は、CAccessorBase です。

必要条件

ヘッダー: atldbcli.h

メンバー

メソッド

名前	説明
AddRefRows	現在の行に関連付けられた参照カウントをインクリメントします。
閉じる	行と現在の `IRowset` インターフェイスを解放します。
比較	IRowsetLocate::Compare を使って 2 つのブックマークを比較します。
CRowset	新しい `CRowset` オブジェクトを作成し、(必要に応じて) パラメーターとして指定した `IRowset` インターフェイスと関連付けます。
削除	IRowsetChange:DeleteRows を使って行セットから行を削除します。
FindNextRow	指定したブックマークの次に一致する行を検索します。
GetApproximatePosition	ブックマークに対応する行のおおよその位置を返します。
GetData	行セットの行のコピーからデータを取得します。
GetDataHere	指定したバッファーからデータを取得します。
GetOriginalData	保留中の変更を無視して、データソースから最後にフェッチされたデータ、またはデータソースに送信されたデータをフェッチします。
GetRowStatus	すべての行の状態を返します。
[挿入]	IRowsetChange:InsertRow を使って新しい行を作成し、挿入します。
IsSameRow	指定した行と現在の行を比較します。
MoveFirst	次のフェッチ位置を初期位置に戻します。
MoveLast	最後のレコードに移動します。
MoveNext	次の連続する行から、または次の行を越えて指定した数の位置からデータをフェッチします。
MovePrev	前のレコードに移動します。
MoveToBookmark	ブックマークで示された行、またはそのブックマークの指定したオフセット位置にある行をフェッチします。
MoveToRatio	行セット内の分数位置から始まる行をフェッチします。
ReleaseRows	IRowset::ReleaseRows を呼び出して、現在の行ハンドルを解放します。
SetData	IRowsetChange:SetData を使って、行の 1 つ以上の列にデータ値を設定します。
元に戻す	最後のフェッチまたは Update 以降に行に対して行われた変更をすべて元に戻します。
アップデート	最後のフェッチまたは更新以降に現在の行に対して行われた保留中の変更をすべて送信します。
UpdateAll	最後のフェッチまたは更新以降にすべての行に対して行われた保留中の変更をすべて送信します。

解説

OLE DB の行セットは、プログラムでデータを設定および取得するために使うオブジェクトです。

このクラスは、インスタンスを作成するためのものではなく、CTable または CCommand にテンプレートパラメーターとして渡します (CRowset が既定値です)。

CRowset::AddRefRows

IRowset::AddRefRows を呼び出し、現在の行ハンドルに関連付けられた参照カウントを (1 つずつ) インクリメントします。

構文

HRESULT AddRefRows() throw();

戻り値

標準の HRESULT。

解説

このメソッドを使って、現在の行ハンドルの参照カウントをインクリメントします。 ReleaseRows を呼び出して、カウントをデクリメントします。移動メソッドによって返される行の参照カウントは 1 です。

CRowset::Close

行と現在の IRowset インターフェイスを解放します。

構文

void Close() throw();

解説

このメソッドは、行セット内に現在あるすべての行を解放します。

CRowset::Compare

IRowsetLocate::Compare を使って 2 つのブックマークを比較します。

構文

HRESULT Compare(const CBookmarkBase& bookmark1,
   const CBookmarkBase& bookmark2,
   DBCOMPARE* pComparison) const throw();

パラメーター

Bookmark1
[入力] 比較する 1 つ目のブックマーク。

Bookmark2
[入力] 比較する 2 つ目のブックマーク。

pComparison
[出力] 比較の結果へのポインター。

戻り値

標準の HRESULT。

解説

このメソッドを使うには、省略可能なインターフェイス IRowsetLocate が必要ですが、プロバイダーによってはサポートされていない場合があります。この場合、メソッドから E_NOINTERFACE が返されます。また、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_IRowsetLocate を VARIANT_TRUE に設定する必要があります。

コンシューマーでのブックマークの使用については、「ブックマークを使用する」を参照してください。

CRowset::CRowset

新しい CRowset オブジェクトを作成し、(必要に応じて) パラメーターとして指定した IRowset インターフェイスと関連付けます。

構文

CRowset();

CRowset(IRowset* pRowset);

パラメーター

pRowset
[入力] このクラスに関連付ける IRowset インターフェイスへのポインター。

CRowset::Delete

IRowsetChange::DeleteRows を呼び出して行セットから現在の行を削除します。

構文

HRESULT Delete() const throw();

戻り値

標準の HRESULT。

CRowset::FindNextRow

指定したブックマークの次に一致する行を検索します。

構文

HRESULT FindNextRow(DBCOMPAREOP op,
   BYTE* pData,
   DBTYPE wType,
   DBLENGTH nLength,
   BYTE bPrecision,
   BYTE bScale,
   BOOL bSkipCurrent = TRUE,
   CBookmarkBase* pBookmark = NULL) throw();

パラメーター

op
[入力] 行値の比較に使う操作。値については、「IRowsetFind::FindNextRow」を参照してください。

pData
[入力] 照合する値へのポインター。

wType
[入力] バッファーの値部分のデータ型を示します。型インジケーターの詳細については、Windows SDK の「OLE DB プログラマーズリファレンス」の「データ型」を参照してください。

nLength
[入力] データ値に割り当てられたコンシューマーデータ構造の長さをバイト (バイト単位)。詳細については、「OLE DB プログラマーズリファレンス」の「DBBINDING 構造体」に記載されている cbMaxLen の説明を参照してください。

bPrecision
[入力] データの取得時に使う最大有効桁数。 wType が DBTYPE_NUMERIC である場合にのみ使われます。詳細については、「OLE DB プログラマーズリファレンス」の「DBTYPE_NUMERIC または DBTYPE_DECIMAL に関連する変換」を参照してください。

bScale
[入力] データの取得時に使う小数点以下桁数。 wType が DBTYPE_NUMERIC または DBTYPE_DECIMAL の場合にのみ使われます。詳細については、「OLE DB プログラマーズリファレンス」の「DBTYPE_NUMERIC または DBTYPE_DECIMAL に関連する変換」を参照してください。

bSkipCurrent
[入力] 検索を開始するブックマークからの行数。

pBookmark
[入力] 検索を開始する位置のブックマーク。

戻り値

標準の HRESULT。

解説

このメソッドを使うには、省略可能なインターフェイス IRowsetFind が必要ですが、プロバイダーによってはサポートされていない場合があります。この場合、メソッドから E_NOINTERFACE が返されます。また、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_IRowsetFind を VARIANT_TRUE に設定する必要があります。

コンシューマーでのブックマークの使用については、「ブックマークを使用する」を参照してください。

CRowset::GetApproximatePosition

ブックマークに対応する行のおおよその位置を返します。

構文

HRESULT GetApproximatePosition(const CBookmarkBase* pBookmark,
   DBCOUNTITEM* pPosition,
   DBCOUNTITEM* pcRows) throw();

パラメーター

pBookmark
[入力] 位置を検出する行を特定するブックマークへのポインター。行数のみが必要な場合は NULL。

pPosition
[出力] GetApproximatePosition が行位置を返す位置へのポインター。位置が不要な場合は NULL。

pcRows
[出力] GetApproximatePosition が行の合計数を返す位置へのポインター。行数が不要な場合は NULL。

戻り値

標準の HRESULT。

解説

このメソッドを使うには、省略可能なインターフェイス IRowsetScroll が必要ですが、プロバイダーによってはサポートされていない場合があります。この場合、メソッドから E_NOINTERFACE が返されます。また、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_IRowsetScroll を VARIANT_TRUE に設定する必要があります。

コンシューマーでのブックマークの使用については、「ブックマークを使用する」を参照してください。

CRowset::GetData

行セットの行のコピーからデータを取得します。

構文

HRESULT GetData() throw();

HRESULT GetData(int nAccessor) throw();

パラメーター

nAccessor
[入力] データへのアクセスに使うアクセサーの (ゼロオフセット) インデックス番号。

戻り値

標準の HRESULT。

解説

BEGIN_ACCESSOR で自動アクセサーではないアクセサーを指定した場合は、このメソッドを使ってアクセサー番号を渡し、明示的にデータを取得します。

CRowset::GetDataHere

現在の行からデータを取得し、指定したバッファーに格納します。

構文

HRESULT GetDataHere(int nAccessor,
   void* pBuffer) throw();

パラメーター

nAccessor
[入力] データにアクセスするために使うアクセサーのインデックス番号。

pBuffer
[出力] 現在のレコードのデータを格納するバッファー。

戻り値

標準の HRESULT。

解説

この関数の使用例については、MultiRead のサンプルに関するページを参照してください。

CRowset::GetOriginalData

IRowsetUpdate::GetOriginalData を呼び出し、データソースから最後にフェッチしたデータ、またはデータソースに送信したデータをフェッチします。

構文

HRESULT GetOriginalData() throw();

戻り値

標準の HRESULT。

解説

このメソッドは、データソースから最後にフェッチした、またはデータソースに送信したデータをフェッチします。保留中の変更に基づいて値をフェッチすることはありません。

このメソッドを使うには、省略可能なインターフェイス IRowsetUpdate が必要ですが、プロバイダーによってはサポートされていない場合があります。この場合、メソッドから E_NOINTERFACE が返されます。また、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_IRowsetUpdate を VARIANT_TRUE に設定する必要があります。

CRowset::GetRowStatus

すべての行の状態を返します。

構文

HRESULT GetRowStatus(DBPENDINGSTATUS* pStatus) const throw();

パラメーター

pStatus
[出力] GetRowStatus が状態値を返す位置へのポインター。「OLE DB プログラマーズリファレンス」の「DBPENDINGSTATUS」を参照してください。

戻り値

標準の HRESULT。

解説

CRowset::Insert

アクセサーのデータを使用して新しい行を作成し、初期化します。

構文

HRESULT Insert(int nAccessor = 0,
   bool bGetHRow = false) throw();

パラメーター

nAccessor
[入力] データの挿入に使うアクセサーの番号。

bGetHRow
[入力] 挿入した行のハンドルを取得するかどうかを示します。

戻り値

標準の HRESULT。

解説

このメソッドを使うには、省略可能なインターフェイス IRowsetChange が必要ですが、プロバイダーによってはサポートされていない場合があります。この場合、メソッドから E_NOINTERFACE が返されます。また、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_IRowsetChange を VARIANT_TRUE に設定する必要があります。

1 つ以上の列が書き込み可能でない場合、挿入に失敗することがあります。これを修正するにはカーソルマップを変更します。

例

次の例は、行セットを使ってデータソースにアクセスし、その行セット内のテーブルを使って文字列を挿入する方法を示しています。

まず、プロジェクトに新しい ATL オブジェクトを挿入して、テーブルクラスを作成します。たとえば、[Workspace](ワークスペース) ペインのプロジェクトを右クリックし、[New ATL Object](新しい ATL オブジェクト) を選びます。 [Data Access](データアクセス) カテゴリから、[Consumer](コンシューマー) を選びます。 [Table](テーブル) 型のコンシューマーオブジェクトを作成します (テーブルを選択すると、テーブルから直接行セットが作成されます。[コマンド] を選択すると、SQL コマンドを使用して行セットが作成されます)。データソースを選択し、そのデータソースにアクセスするテーブルを指定します。コンシューマーオブジェクト CCustomerTable を呼び出すと、次のように挿入コードが実装されます。

// Access the rowset using the wizard-generated class, CCustomerTable
CCustomerTable rs;           // Your CTable-derived class

// Insert a customer
// Note that for fixed-length fields such as billing ID it isn't necessary
// to set the length
rs.m_BillingID = 5002;
rs.m_dwBillingIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_ContactFirstName, sizeof(rs.m_ContactFirstName) / sizeof(TCHAR), 
   _T("Malcolm"));
rs.m_dwContactFirstNameLength = 7;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_L_Name, sizeof(rs.m_L_Name) / sizeof(TCHAR), _T("Reynolds"));
rs.m_dwL_NameLength = 8;
rs.m_dwContactFirstNameStatus = DBSTATUS_S_OK;

rs.m_CustomerID = 2005;
rs.m_dwCustomerIDStatus = DBSTATUS_S_OK;

_tcscpy_s(rs.m_PostalCode, sizeof(rs.m_PostalCode) / sizeof(TCHAR), 
   _T("34213-4444"));
rs.m_dwPostalCodeLength = 10;
rs.m_dwPostalCodeStatus = DBSTATUS_S_OK;

HRESULT hr = rs.Insert();
if (FAILED(hr))
{
   ATLTRACE(_T("Insert failed: 0x%X\n"), hr);
}

CRowset::IsSameRow

指定した行と現在の行を比較します。

構文

HRESULT IsSameRow(HROW hRow) const throw();

パラメーター

hRow
[入力] 現在の行と比較する行へのハンドル。

戻り値

標準の HRESULT。 S_OK は、行が同じであることを示します。その他の値については、Windows SDK の「OLE DB プログラマーズリファレンス」の「IRowsetIndentity::IsSameRow」を参照してください。

CRowset::MoveFirst

カーソルを初期位置に移動し、初期行を取得します。

構文

HRESULT MoveFirst() throw();

戻り値

標準の HRESULT。

解説

IRowset::RestartPosition を呼び出し、次のフェッチ位置を初期位置 (行セットが作成されたときに次のフェッチ位置であった位置) に移動し、最初の行をフェッチします。

CRowset::MoveLast

カーソルを最後の行に移動します。

構文

HRESULT MoveLast() throw();

戻り値

標準の HRESULT。

解説

IRowset::RestartPosition を呼び出し、次のフェッチ位置を最後の位置に移動し、最後の行をフェッチします。

このメソッドを使う場合、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_CANSCROLLBACKWARDS を VARIANT_TRUE に設定する必要があります (パフォーマンスを向上させるために、DBPROP_QUICKRESTART を VARIANT_TRUE に設定することもできます)。

CRowset::MoveNext

カーソルを次のレコードに移動します。

構文

HRESULT MoveNext() throw();

HRESULT MoveNext(LONG lSkip,
   bool bForward= true) throw();

パラメーター

lSkip
[入力] フェッチする前にスキップする行の数。

bForward
[入力] 次のレコードに移動するには true を、後方に移動するには false を渡します。

戻り値

標準の HRESULT。行セットの最後に達すると、DB_S_ENDOFROWSET を返します。

解説

前の位置を記憶して、CRowset オブジェクトから次の連続する行をフェッチします。必要に応じて、lSkip 行分、前方にスキップするか、後方に移動するかを選ぶことができます。

このメソッドを使う場合、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、次のプロパティを設定する必要があります。

lSkip< 0 の場合、DBPROP_CANSCROLLBACKWARDS は VARIANT_TRUE にする必要があります。
bForward = false の場合、DBPROP_CANFETCHBACKWARDS は VARIANT_TRUE にする必要があります。

それ以外の場合 (lSkip>= 0 かつ bForward = true の場合)、追加のプロパティを設定する必要はありません。

CRowset::MovePrev

カーソルを前のレコードに移動します。

構文

HRESULT MovePrev() throw();

戻り値

標準の HRESULT。

解説

このメソッドを使う場合、行セットを含むテーブルまたはコマンドに対して Open を呼び出す前に、DBPROP_CANFETCHBACKWARDS または DBPROP_CANSCROLLBACKWARDS を VARIANT_TRUE に設定する必要があります。

CRowset::MoveToBookmark

ブックマークで示された行、またはそのブックマークの指定したオフセット (lSkip) 位置にある行をフェッチします。

構文

HRESULT MoveToBookmark(const CBookmarkBase& bookmark,
   LONG lSkip = 0) throw();

パラメーター

bookmark
[入力] データをフェッチする位置を示すブックマーク。

lSkip
[入力] ブックマークからターゲット行までの行数。 lSkip が 0 の場合、フェッチされる最初の行はブックマークされた行です。 lSkip が 1 の場合、フェッチされる最初の行はブックマークされた行の次の行です。 lSkip が -1 の場合、フェッチされる最初の行はブックマークされた行の前の行です。

戻り値

標準の HRESULT。

解説

コンシューマーでのブックマークの使用については、「ブックマークを使用する」を参照してください。

CRowset::MoveToRatio

行セット内の分数位置から始まる行をフェッチします。

構文

HRESULT MoveToRatio(DBCOUNTITEM nNumerator,
   DBCOUNTITEM nDenominator,bool bForward = true) throw();

パラメーター

nNumerator
[入力] データをフェッチする分数位置を決定するために使われる分子。

nDenominator
[入力] データをフェッチする分数位置を決定するために使われる分母。

bForward
[入力] 前方または後方のどちらに移動するかを示します。既定値は前方です。

戻り値

標準の HRESULT。

解説

MoveToRatio は、おおよそ次の式に従って行をフェッチします。

(nNumerator * RowsetSize ) / nDenominator

この RowsetSize は行セットサイズであり、単位は行数です。この数式の正確性は、プロバイダーによって異なります。詳細については、「IRowsetScroll::GetRowsAtRatio」を参照してください。

CRowset::ReleaseRows

IRowset::ReleaseRows を呼び出して、現在の行ハンドルを解放します。

構文

HRESULT ReleaseRows() throw();

戻り値

標準の HRESULT。

CRowset::SetData

ある行の 1 つ以上の列にデータ値を設定します。

構文

HRESULT SetData() const throw();

HRESULT SetData(int nAccessor) const throw();

パラメーター

nAccessor
[入力] データにアクセスするために使うアクセサーの番号。

戻り値

標準の HRESULT。

解説

引数を受け取らない SetData フォームの場合、すべてのアクセサーが更新に使われます。通常は、SetData を呼び出して、ある行の列にデータ値を設定し、Update を呼び出してそれらの変更を送信します。

1 つ以上の列が書き込み可能でない場合、設定操作は失敗する可能性があります。これを修正するにはカーソルマップを変更します。

CRowset::Undo

最後のフェッチまたは Update 以降に行に対して行われた変更をすべて元に戻します。

構文

HRESULT Undo(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

パラメーター

pcRows
[出力] 必要に応じて、Undo が元に戻そうとした行数を返す位置へのポインター。

phRow
[出力] 必要に応じて、Undo が元に戻そうとしたすべての行へのハンドルの配列を返す位置へのポインター。

pStatus
[出力] Undo が行の状態値を返す位置へのポインター。 pStatus が null の場合、状態は返されません。

戻り値

標準の HRESULT。

解説

CRowset::Update

最後のフェッチまたは Update の呼び出し以降に現在の行に対して行われた保留中の変更をすべて送信します。

構文

HRESULT Update(DBCOUNTITEM* pcRows = NULL,
   HROW* phRow = NULL,
   DBROWSTATUS* pStatus = NULL) throw();

パラメーター

pcRows
[出力] 必要に応じて、Update が更新しようとした行数を返す位置へのポインター。

phRow
[出力] Update が更新しようとした行のハンドルを返す位置へのポインター。 phRow が null の場合、ハンドルは返されません。

pStatus
[出力] Update が行の状態値を返す位置へのポインター。 pStatus が null の場合、状態は返されません。

戻り値

標準の HRESULT。

解説

(Update または UpdateAll を使って) 最後に行がフェッチまたは更新されてから現在の行に対して行われた保留中の変更をすべて送信します。通常は、SetData を呼び出して、ある行の列にデータ値を設定し、Update を呼び出してそれらの変更を送信します。

CRowset::UpdateAll

最後のフェッチまたは Update の呼び出し以降にすべての行に対して行われた保留中の変更をすべて送信します。

構文

HRESULT UpdateAll(DBCOUNTITEM* pcRows = NULL,
   HROW** pphRow = NULL,
   DBROWSTATUS** ppStatus = NULL) throw();

パラメーター

pcRows
[出力] 必要に応じて、UpdateAll が更新しようとした行数を返す位置へのポインター。

pphRow
[出力] UpdateAll が更新しようとした行のハンドルを返すメモリへのポインター。 pphRow が null の場合、ハンドルは返されません。

ppStatus
[出力] Update が行の状態値を返す位置へのポインター。 ppStatus が null の場合、状態は返されません。

解説

Update または UpdateAll を使って最後に行がフェッチまたは更新されてから、すべての行に対して行われた保留中の変更を送信します。 UpdateAll を使うと、変更されたすべての行は、それらのハンドル (pphRow を参照してください) をまだ持っているかどうかに関係なく、更新されます。

たとえば、Insert を使って行セットに 5 行を挿入した場合、Update を 5 回呼び出すか、UpdateAll を 1 回呼び出してすべてを更新することができます。

戻り値

標準の HRESULT。