db_command
OLE DB コマンドを作成します。
[ db_command(
command,
name,
source_name,
hresult,
bindings,
bulk_fetch)
]
パラメータ
command
OLE DB コマンドのテキストが含まれているコマンド文字列。簡単な例を次に示します。[ db_command ( command = "Select * from Products" ) ]command 構文は次のとおりです。
binding parameter block 1 OLE DB command binding parameter block 2 continuation of OLE DB command binding parameter block 3 ...連結パラメータ ブロックの定義は次のとおりです。
([bindtype] szVar1 [, szVar2 [, nVar3 [, ...]]])
指定項目 :
'(' は、データ連結ブロックの開始を示します。
[bindtype] には、以下の文字列のいずれかを指定します。大文字と小文字は区別されません。
[db_column]。各メンバ変数を行セットの列に連結します。
[bindto]。[db_column] と同じです。
[in]。メンバ変数を入力パラメータとして連結します。
[out]。メンバ変数を出力パラメータとして連結します。
[in,out]。メンバ変数を入出力パラメータとして連結します。
SzVarX は現在のスコープ内のメンバ変数に解決されます。
')' は、データ連結ブロックの終了を示します。
コマンド文字列に [in]、[out]、[in/out] などの指定子が 1 つ以上含まれている場合、db_command はパラメータ マップを作成します。
コマンド文字列に [db_column] や [bindto] などのパラメータが 1 つ以上含まれている場合、db_command は行セットとアクセサ マップを生成して連結された変数にサービスを提供します。詳細については、「db_accessor」を参照してください。
.gif "メモ")
メモ :[db_command をクラス レベルで使用する場合は、[bindtype] 構文と bindings パラメータは無効です。
連結パラメータ ブロックのいくつかの例を次に示します。次の例では、pubs データベースの authors テーブルにある au_fname 列および au_lname 列に、データ メンバ m_au_fname および m_au_lname をそれぞれ連結します。
TCHAR m_au_fname[21]; TCHAR m_au_lname[41]; TCHAR m_state[3] = 'CA'; [db_command ( command = "SELECT au_fname([bindto]m_au_fname), au_lname([bindto]m_au_lname) " \ "FROM dbo.authors " \ "WHERE state = ?([in]m_state)")]
name (省略可能)
行セットの操作に使用するハンドルの名前。name を指定すると、指定した name を持つクラスが db_command によって生成され、行セットの走査や複数のアクション クエリの実行に使用できます。name を指定しないと、ユーザーに複数の結果行を返すことができません。source_name (省略可能)
実行するコマンドの対象となる属性 db_source が適用された CSession 変数またはクラスのインスタンス。「db_source」を参照してください。db_command は、source_name に使用されている変数が有効であることを確認するので、指定の変数は関数スコープかグローバル スコープにある必要があります。
hresult (省略可能)
データベース コマンドの HRESULT を受け取る変数を識別する値。変数が存在しない場合は、属性によって自動的に挿入されます。bindings (省略可能)
OLE DB コマンドと連結パラメータを区別する値。bindings 値を指定すると、db_command は関連する値を解析しますが、[bindtype] パラメータを解析しません。この場合は、OLE DB プロバイダ構文を使用できます。連結パラメータを指定せずに解析を無効にするには、Bindings="" と指定します。
bindings に値を指定しない場合、db_command は '('、角かっこで囲まれた [bindtype]、以前に宣言された 1 つ以上の C++ メンバ変数、')' を順に探し、連結パラメータ ブロックを解析します。結果のコマンドからかっこ内のすべてのテキストが削除され、そのコマンドの列やパラメータの連結を行うためにこのパラメータが使用されます。
bulk_fetch (省略可能)
フェッチする行数を指定する整数値。既定値は 1 で、単一行のフェッチを指定します。行セットの型は CRowset になります。
1 より大きい値は、一括行フェッチを指定します。一括行フェッチとは、複数の行ハンドルをフェッチするための一括行セットの機能です。行セットの型は CBulkRowset になり、指定した行数を使って SetRows を呼び出します。
bulk_fetch が 1 より小さい場合、SetRows は 0 を返します。
解説
db_command は、コマンドを実行するために OLE DB コンシューマで使用する CCommand オブジェクトを作成します。
db_command はクラス スコープまたは関数スコープで使用できます。主な違いは、CCommand オブジェクトのスコープです。関数スコープでは、連結などのデータは関数の終了時に無効になります。クラス スコープと関数スコープを使用する場合、どちらも OLE DB コンシューマ テンプレートのクラス CCommand<> が必要ですが、テンプレートの引数はそれぞれ異なります。関数スコープの場合はローカル変数で構成された Accessor に対して連結を実行しますが、クラス スコープの場合は CAccessor の派生クラスを引数として使用します。クラス属性として使用する場合、db_command は db_column と連携して機能します。
db_command を使用して、結果セットを返さないコマンドを実行できます。
コンシューマ属性プロバイダがこの属性をクラスに適用すると、コンパイラはクラスの名前を _YourClassNameAccessor (YourClassName はクラスの名前) に変更します。さらに、コンパイラは、_YourClassName から派生した YourClassName という名前のクラスを生成します。クラス ビューに両方のクラスが表示されます。
使用例
このサンプルでは、テーブルから州の列が "CA" に一致する氏名を選択するコマンドを定義します。db_command では、行セットを作成して読み込み、それに対して、MoveNext などの CRowset メンバ関数だけでなく、ウィザードで生成した OpenAll や CloseAll などの関数を実行できます。
このコードには、pubs データベースに接続する独自の接続文字列を指定する必要があります。開発環境でのこの操作方法については、「方法 : サーバー エクスプローラからデータベースに接続する」および「方法 : サーバー エクスプローラまたはデータベース エクスプローラで新しいデータ接続を追加する」を参照してください。
// db_command.h
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>
#pragma once
[ db_source(L"your connection string"),
db_command(L" \
SELECT au_lname, au_fname \
FROM dbo.authors \
WHERE state = 'CA'") ]
struct CAuthors {
// In order to fix several issues with some providers, the code below may bind
// columns in a different order than reported by the provider
DBSTATUS m_dwau_lnameStatus;
DBSTATUS m_dwau_fnameStatus;
DBLENGTH m_dwau_lnameLength;
DBLENGTH m_dwau_fnameLength;
[ db_column("au_lname", status="m_dwau_lnameStatus", length="m_dwau_lnameLength") ] TCHAR m_au_lname[41];
[ db_column("au_fname", status="m_dwau_fnameStatus", length="m_dwau_fnameLength") ] TCHAR m_au_fname[21];
[ db_param("7", paramtype="DBPARAMIO_INPUT") ] TCHAR m_state[3];
void GetRowsetProperties(CDBPropSet* pPropSet) {
pPropSet->AddProperty(DBPROP_CANFETCHBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
pPropSet->AddProperty(DBPROP_CANSCROLLBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
}
};
// db_command.cpp
// compile with: /c
#include "db_command.h"
int main(int argc, _TCHAR* argv[]) {
HRESULT hr = CoInitialize(NULL);
// Instantiate rowset
CAuthors rs;
// Open rowset and move to first row
strcpy_s(rs.m_state, sizeof(rs.m_state), _T("CA"));
hr = rs.OpenAll();
hr = rs.MoveFirst();
// Iterate through the rowset
while( SUCCEEDED(hr) && hr != DB_S_ENDOFROWSET ) {
// Print out the column information for each row
printf("First Name: %s, Last Name: %s\n", rs.m_au_fname, rs.m_au_lname);
hr = rs.MoveNext();
}
rs.CloseAll();
CoUninitialize();
}
このサンプルでは、CMySource データ ソース クラスで db_source を使用し、CCommand1 コマンド クラスおよび CCommand2 コマンド クラスで db_command を使用します。
// db_command_2.cpp
// compile with: /c
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>
// class usage for both db_source and db_command
[ db_source(L"your connection string"),
db_command(L" \
SELECT au_lname, au_fname \
FROM dbo.authors \
WHERE state = 'CA'") ]
struct CMySource {
HRESULT OpenDataSource() {
return S_OK;
}
};
[db_command(command = "SELECT * FROM Products")]
class CCommand1 {};
[db_command(command = "SELECT FNAME, LNAME FROM Customers")]
class CCommand2 {};
int main() {
CMySource s;
HRESULT hr = s.OpenDataSource();
if (SUCCEEDED(hr)) {
CCommand1 c1;
hr = c1.Open(s);
CCommand2 c2;
hr = c2.Open(s);
}
s.CloseDataSource();
}
必要条件
属性コンテキスト
対象 |
class、struct、メンバ、メソッド、ローカル |
複数回の適用 |
不可 |
必要な属性 |
なし |
無効な属性 |
なし |
属性コンテキストの詳細については、「属性コンテキスト」を参照してください。