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 | 使用多個結果集時擷取下一個結果。 |
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 。
bBind
[in]指定是否在執行之後自動系結命令。 預設值為 true
,這會導致命令自動系結。 將 bBind 設定 為 false
防止命令的自動系結,讓您可以手動系結。 (手動系結對 OLAP 使用者特別感興趣。
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 文字的指標。
guidCommand
[in]GUID,指定要用於剖析命令文字之提供者的語法和一般規則。 如需方言的描述,請參閱 OLE DB 程式設計人員參考 中的 ICommandText::GetCommandText 。
傳回值
標準 HRESULT。
備註
的第一種形式 Create
會採用 Unicode 命令字串。 的第二種形式 Create
採用 ANSI 命令字串(針對與現有 ANSI 應用程式的回溯相容性提供)。
CCommand::CreateCommand
建立新的命令。
語法
HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();
參數
工作階段
[in] 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
[in]您預期要執行命令的次數。
傳回值
標準 HRESULT。
備註
此方法會包裝 OLE DB 方法 ICommandPrepare::P repare 。
CCommand::ReleaseCommand
釋放參數存取子,然後再釋放命令本身。
語法
void CCommandBase::ReleaseCommand() throw();
備註
ReleaseCommand
與 搭配 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 。
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應