CCommand 類別

發行項
08/03/2024

提供方法來設定和執行命令。

語法

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	使用多個結果集時擷取下一個結果。
Open	執行並選擇性地系結命令。

繼承的方法

名稱	描述
建立	建立指定工作階段的新命令，然後設定命令文字。
CreateCommand	建立新的命令。
GetParameterInfo	取得命令參數、其名稱及其類型的清單。
準備	驗證並優化目前的命令。
ReleaseCommand	視需要釋放參數存取子，然後釋放命令。
SetParameterInfo	指定每個命令參數的原生類型。
取消準備	捨棄目前的命令執行計劃。

備註

當您需要執行參數型作業或執行命令時，請使用這個類別。如果您只需要開啟簡單的數據列集，請改用 CTable 。

您所使用的存取子類別會決定係結參數和數據的方法。

請注意，您無法搭配 OLE DB Provider for Jet 使用預存程式，因為該提供者不支援預存程式（查詢字串中只允許常數）。

CCommand::Close

釋放與命令相關聯的存取子數據列集。

語法

void Close();

備註

命令會使用數據列集、結果集存取子和參數存取子（選擇性地）參數存取子（不同於不支持參數且不需要參數存取子的數據表）。

當您執行命令時，應該在命令之後呼叫 Close 和 ReleaseCommand 。

當您要重複執行相同的命令時，您應該先呼叫 Close 來釋放每個結果集存取子，然後再呼叫 Execute。在數列結尾，您應該呼叫 ReleaseCommand來釋放參數存取子。另一個常見案例是呼叫具有輸出參數的預存程式。在許多提供者上（例如 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
[in/out]傳回受命令影響之數據列計數的記憶體指標。

bBind
[in]指定是否在執行之後自動系結命令。預設值為 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();

參數

工作階段
[in]要在其中執行命令的會話。

wszCommand
[in]要執行的命令，傳遞為 Unicode 字串。使用 CAccessor時可以是 NULL，在此情況下，命令會從傳遞至 DEFINE_COMMAND 巨集的值擷取。如需詳細資訊，請參閱 OLE DB 程式設計人員參考中的 ICommand：：Execute。

szCommand
[in]與 wszCommand 相同，不同之處在於此參數會採用 ANSI 命令字串。這個方法的第四種形式可以採用 NULL 值。如需詳細資訊，請參閱本主題稍後的。

pPropSet
[in]DBPROPSET 結構的陣列指標，其中包含要設定的屬性和值。請參閱 Windows SDK 中 OLE DB 程式設計人員參考中的屬性集和屬性群組。

pRowsAffected
[in/out]傳回受命令影響之數據列計數的記憶體指標。如果 *pRowsAffected 為 NULL，則不會傳回任何數據列計數。否則， Open 請根據下列條件設定 *pRowsAffected ：

如果	結果為
的 `cParamSets` `pParams` 元素大於 1	*pRowsAffected 代表執行中指定的所有參數集所影響的數據列總數。
受影響的數據列數目無法使用	*pRowsAffected 設定為 -1。
命令不會更新、刪除或插入數據列	*pRowsAffected 未定義。

guidCommand
[in]GUID，指定要用於剖析命令文字之提供者的語法和一般規則。如需詳細資訊，請參閱 OLE DB 程式設計人員參考中的 ICommandText：：GetCommandText 和 ICommandText：：SetCommandText。

ulPropSets
[in]在 pPropSet 自變數中傳遞的 DBPROPSET 結構數目。

傳回值

標準 HRESULT。

備註

前三種形式的 Open 採用會話、建立命令，並視需要執行命令，系結任何參數。

的第一種形式 Open 會採用 Unicode 命令字串，而且沒有預設值。

的第二種形式 Open 會採用 ANSI 命令字串，且沒有預設值（針對與現有 ANSI 應用程式的回溯相容性提供）。

的第三種形式 Open 可讓命令字串成為 NULL，因為類型 int 具有 NULL 的預設值。它可供呼叫 Open(session, NULL); 或 Open(session); ，因為 NULL 的類型為 int。此版本需要並判斷提示 int 參數為NULL。

當您已經建立命令並想要執行單一準備和多個執行時，請使用的第四種形式Open。

注意

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

參數

工作階段
[in]要在其中建立命令的會話。

wszCommand
[in]命令字串之 Unicode 文字的指標。

szCommand
[in]命令字串之 ANSI 文字的指標。

OLE DB 消費者範本
 OLE DB 消費者範本參考

共用方式為

CCommand 類別

語法

參數

需求

成員

方法

繼承的方法

備註

CCommand::Close

語法

備註

範例

CCommand::GetNextResult

語法

參數

傳回值

備註

CCommand::Open

語法

參數

傳回值

備註

CCommand::Create

語法

參數

傳回值

備註

CCommand::CreateCommand

語法

參數

傳回值

備註

CCommand::GetParameterInfo

語法

參數

傳回值

CCommand::Prepare

語法

參數

傳回值

備註

CCommand::ReleaseCommand

語法

備註

CCommand::SetParameterInfo

語法

參數

傳回值

CCommand::Unprepare

語法

傳回值

備註

另請參閱

意見反應

其他資源