CCommand クラス

コマンドを設定して実行するためのメソッドを提供します。

構文

template <class TAccessor = CNoAccessor,
   template <typename T> class TRowset = CRowset,
   class TMultiple = CNoMultipleResults>
class CCommand :
   public CAccessorRowset <TAccessor, TRowset>,
   public CCommandBase,
   public TMultiple

パラメーター

TAccessor
コマンドで使用するアクセサー クラス (CDynamicParameterAccessor、CDynamicStringAccessor、CEnumeratorAccessor など) の型。 既定値は CNoAccessor です。これは、クラスがパラメーターまたは出力列をサポートしていないことを指定します。

TRowset
コマンドで使用する行セット クラス (CArrayRowset や CNoRowset など) の型。 既定値は、CRowset です。

TMultiple
複数の結果を戻す可能性がある OLE DB コマンドを使用する場合は、CMultipleResults を指定します。 それ以外の場合は、CNoMultipleResults を使用します。 詳細については、「IMultipleResults」を参照してください。

必要条件

ヘッダー: atldbcli.h

メンバー

メソッド

名前	説明
閉じる	現在のコマンドを閉じます。
GetNextResult	複数の結果セットを使用するときに、次の結果をフェッチします。
[ファイル]	コマンドを実行し、必要に応じてバインドします。

継承されたメソッド

名前	説明
作成	指定されたセッションに対して新しいコマンドを作成し、コマンド テキストを設定します。
CreateCommand	新しいコマンドを作成します。
GetParameterInfo	コマンドのパラメーターおよびそれらの名前と型の一覧を取得します。
準備	現在のコマンドを検証して最適化します。
ReleaseCommand	必要に応じてパラメーター アクセサーを解放してから、コマンドを解放します。
SetParameterInfo	各コマンド パラメーターのネイティブ型を指定します。
Unprepare	現在のコマンド実行プランを破棄します。

解説

このクラスは、パラメーターベースの操作を実行したり、コマンドを実行したりする必要がある場合に使用します。 単純な行セットを開くことだけが必要な場合には、代わりに CTable を使用します。

使用しているアクセサー クラスによって、パラメーターとデータをバインドする方法が決まります。

OLE DB Provider for Jet ではストアド プロシージャを使用できないことに注意してください。このプロバイダーではストアド プロシージャがサポートされていないためです (クエリ文字列で定数のみ使用できます)。

CCommand::Close

コマンドに関連付けられているアクセサー行セットを解放します。

構文

void Close();

解説

コマンドは、行セット、結果セット アクセサー、および (必要に応じて) パラメーター アクセサーを使用します (これは、パラメーターをサポートせず、パラメーター アクセサーを必要としないテーブルとは異なります)。

コマンドを実行するとき、コマンドの後で Close と ReleaseCommand の両方を呼び出す必要があります。

同じコマンドを繰り返し実行する場合は、Execute を呼び出す前に Close を呼び出して、各結果セット アクセサーを解放する必要があります。 シリーズの最後に、ReleaseCommand を呼び出してパラメーター アクセサーを解放する必要があります。 もう 1 つの一般的なシナリオでは、出力パラメーターを含むストアド プロシージャを呼び出します。 多くのプロバイダー (OLE DB Provider for SQL Server など) では、結果セット アクセサーを閉じるまで、出力パラメーターの値にアクセスできません。 Close を呼び出して、返された行セットと結果セット アクセサーを閉じます。ただし、パラメーター アクセサーは閉じないため、出力パラメーターの値を取得できます。

例

次の例は、同じコマンドを繰り返し実行する場合に Close と ReleaseCommand を呼び出す方法を示しています。

void DoCCommandTest()
{
   HRESULT hr;

   hr = CoInitialize(NULL);

   CCustomer rs;           // Your CCommand-derived class
   rs.m_BillingID = 6611;  // Open billing ID 6611
   hr = rs.OpenAll();      // (Open also executes the command)
   hr = rs.MoveFirst();    // Move to the first row and print it

   _tprintf_s(_T("First name: %s, Last Name: %s, Customer ID: %d, Postal Code: %s\n"),
      rs.m_ContactFirstName, rs.m_L_Name, rs.m_CustomerID, rs.m_PostalCode);

   // Close the first command execution
   rs.Close();

   rs.m_BillingID = 3333;     // Open billing ID 3333 (a new customer)
   hr = rs.Open();            // (Open also executes the command)
   hr = rs.MoveFirst();       // Move to the first row and print it

   _tprintf_s(_T("First name: %s, Last Name: %s, Customer ID: %d, Postal Code: %s\n"),
      rs.m_ContactFirstName, rs.m_L_Name, rs.m_CustomerID, rs.m_PostalCode);

   // Close the second command execution;
   // Instead of the two following lines
   // you could simply call rs.CloseAll()
   // (a wizard-generated method):
   rs.Close();
   rs.ReleaseCommand();

   CoUninitialize();
}

CCommand::GetNextResult

次の結果セットがある場合はフェッチします。

構文

HRESULT GetNextResult(DBROWCOUNT* pulRowsAffected,
   bool bBind = true) throw();

パラメーター

pulRowsAffected
[入力/出力] コマンドの影響を受ける行のカウントが返されるメモリへのポインター。

bBind
[入力] コマンドの実行後にコマンドを自動的にバインドするかどうかを指定します。 既定値は true です。これにより、コマンドが自動的にバインドされます。 bBind を false に設定すると、コマンドの自動バインドが防止されるため、手動でバインドできます。 (手動バインドは、特に OLAP ユーザーに関係します)。

戻り値

標準の HRESULT。

解説

結果セットが既にフェッチされている場合、この関数は前の結果セットを解放し、列のバインドを解除します。 bBind が true の場合、新しい列をバインドします。

CCommand テンプレートパラメーター TMultiple=CMultipleResults を設定して複数の結果を指定した場合にのみ、この関数を呼び出す必要があります。

CCommand::Open

コマンドを実行し、必要に応じてバインドします。

構文

HRESULT Open(const CSession& session,
   LPCWSTR wszCommand,
   DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   REFGUID guidCommand = DBGUID_DEFAULT,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

HRESULT Open(const CSession& session,
   LPCSTR szCommand,
   DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   REFGUID guidCommand = DBGUID_DEFAULT,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

HRESULT Open(const CSession& session,
   INT szCommand = NULL,
   DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   REFGUID guidCommand = DBGUID_DEFAULT,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

HRESULT Open(DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

パラメーター

セッション
[入力] コマンドを実行するセッション。

wszCommand
[入力] 実行するコマンド。Unicode 文字列として渡します。 CAccessor を使用するときは NULL を指定できます。その場合、コマンドは DEFINE_COMMAND マクロに渡される値から取得されます。 詳細については、"OLE DB プログラマーズ リファレンス" の「ICommand::Execute」を参照してください。

szCommand
[入力] wszCommand と同じですが、このパラメーターは ANSI コマンド文字列を受け取る点が異なります。 このメソッドの 4 番目の形式は、NULL 値を受け取ることができます。 詳細については、このトピックで後述する「解説」を参照してください。

pPropSet
[入力] 設定するプロパティと値を含む DBPROPSET 構造体の配列へのポインター。 Windows SDK に含まれる "OLE DB プログラマーズ リファレンス" のプロパティ セットとプロパティ グループに関するページを参照してください。

pRowsAffected
[入力/出力] コマンドの影響を受ける行のカウントが返されるメモリへのポインター。 *pRowsAffected が NULL の場合、行数は返されません。 それ以外の場合、Open は次の条件に応じて *pRowsAffected を設定します。

If	THEN
pParams の cParamSets 要素の長さが 1 を超えている	*pRowsAffected は、実行に指定されたすべてのパラメーター セットの影響を受ける行の合計数を表します。
影響を受ける行数がわからない	*pRowsAffected が -1 に設定されます。
コマンドが行の更新、削除、または挿入を行わない	*pRowsAffected は定義されません。

guidCommand
[入力] プロバイダーがコマンド テキストの解析に使用する構文と一般的な規則を指定する GUID。 詳細については、"OLE DB プログラマーズ リファレンス" の「ICommandText::GetCommandText」および「ICommandText::SetCommandText」を参照してください。

bBind
[入力] コマンドの実行後にコマンドを自動的にバインドするかどうかを指定します。 既定値は true です。これにより、コマンドが自動的にバインドされます。 bBind を false に設定すると、コマンドの自動バインドが防止されるため、手動でバインドできます。 (手動バインドは、特に OLAP ユーザーに関係します。)

ulPropSets
[入力] pPropSet 引数で渡される DBPROPSET 構造体の数。

戻り値

標準の HRESULT。

解説

Open の最初の 3 つの形式は、セッションを受け取って、コマンドを作成して実行し、必要に応じてパラメーターとバインドします。

Open の最初の形式は、Unicode コマンド文字列を受け取り、既定値はありません。

Open の 2 番目の形式は、ANSI コマンド文字列を受け取り、既定値はありません (既存の ANSI アプリケーションとの下位互換性のために提供されています)。

Open の 3 番目の形式では、int 型の既定値は NULL であるため、コマンド文字列を NULL にすることができます。 NULL は int 型であるため、これは Open(session, NULL); または Open(session); を呼び出すために提供されます。 このバージョンでは、int パラメーターが NULL であることが必要であり、そうであることが確認されます。

Open の 4 番目の形式を使用するのは、既にコマンドを作成しており、1 つの Prepare と複数の実行を行おうとする場合です。

Note

Open が Execute を呼び出し、これがさらに GetNextResult を呼び出します。

CCommand::Create

CCommand::CreateCommand を呼び出して、指定されたセッションに対してコマンドを作成してから、ICommandText::SetCommandText を呼び出してコマンド テキストを指定します。

構文

HRESULT CCommandBase::Create(const CSession& session,
   LPCWSTR wszCommand,
   REFGUID guidCommand = DBGUID_DEFAULT) throw ();

HRESULT CCommandBase::Create(const CSession& session,
   LPCSTR szCommand,
   REFGUID guidCommand = DBGUID_DEFAULT) throw ();

パラメーター

セッション
[入力] コマンドを作成するセッション。

wszCommand
[入力] コマンド文字列の Unicode テキストへのポインター。

szCommand
[入力] コマンド文字列の ANSI テキストへのポインター。

guidCommand
[入力] プロバイダーがコマンド テキストの解析に使用する構文と一般的な規則を指定する GUID。 言語の詳細については、"OLE DB プログラマーズ リファレンス" の「ICommandText::GetCommandText」をご覧ください。

戻り値

標準の HRESULT。

解説

Create の最初の形式は、Unicode コマンド文字列を受け取ります。 Create の 2 番目の形式は、ANSI コマンド文字列を受け取ります (既存の ANSI アプリケーションとの下位互換性のために提供されています)。

CCommand::CreateCommand

新しいコマンドを作成します。

構文

HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();

パラメーター

セッション
[入力] 新しいコマンドに関連付けられる CSession オブジェクト。

戻り値

標準の HRESULT。

解説

このメソッドは、指定されたセッション オブジェクトを使用してコマンドを作成します。

CCommand::GetParameterInfo

コマンドのパラメーターおよびそれらの名前と型の一覧を取得します。

構文

HRESULT CCommandBase::GetParameterInfo(DB_UPARAMS* pParams,
   DBPARAMINFO** ppParamInfo,
   OLECHAR** ppNamesBuffer) throw ();

パラメーター

"OLE DB プログラマーズ リファレンス" の「ICommandWithParameters::GetParameterInfo」を参照してください。

戻り値

標準の HRESULT。

CCommand::Prepare

現在のコマンドを検証して最適化します。

構文

HRESULT CCommandBase::Prepare(ULONG cExpectedRuns = 0) throw();

パラメーター

cExpectedRuns
[入力] コマンドを実行しようとする回数。

戻り値

標準の HRESULT。

解説

このメソッドは、OLE DB メソッド ICommandPrepare::Prepare をラップします。

CCommand::ReleaseCommand

パラメーター アクセサーを解放してから、コマンドそのものを解放します。

構文

void CCommandBase::ReleaseCommand() throw();

解説

ReleaseCommand は Close と組み合わせて使用されます。 使用方法の詳細については、「Close」を参照してください。

CCommand::SetParameterInfo

各コマンド パラメーターのネイティブ型を指定します。

構文

HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
   const DBORDINAL* pOrdinals,
   const DBPARAMBINDINFO* pParamInfo) throw();

パラメーター

"OLE DB プログラマーズ リファレンス" の「ICommandWithParameters::SetParameterInfo」を参照してください。

戻り値

標準の HRESULT。

CCommand::Unprepare

現在のコマンド実行プランを破棄します。

構文

HRESULT CCommandBase::Unprepare() throw();

戻り値

標準の HRESULT。

解説

このメソッドは、OLE DB メソッド ICommandPrepare::Unprepare をラップします。

関連項目

OLE DB コンシューマー テンプレート
OLE DB コンシューマー テンプレート リファレンス