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 使用預存程式,因為該提供者不支援預存程式(查詢字串中只允許常數)。
釋放與 命令相關聯的存取子數據列集。
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();
}
如果有的話,擷取下一個結果集。
HRESULT GetNextResult(DBROWCOUNT* pulRowsAffected,
bool bBind = true) throw();
pulRowsAffected
[in/out]傳回受命令影響之數據列計數的記憶體指標。
bBind
[in]指定是否在執行之後自動系結命令。 預設值為 true
,這會導致命令自動系結。 將 bBind 設定為false
防止命令的自動繫結,讓您可以手動系結。 (手動系結對 OLAP 用戶特別感興趣。
標準 HRESULT。
如果先前已擷取結果集,此函式會釋放先前的結果集,並將數據行解除系結。 如果 bBind 為 true
,則會系結新的數據行。
只有在您已藉由設定 CCommand
範本參數 TMultiple=CMultipleResults
來指定多個結果時,才應該呼叫此函式。
執行並選擇性地系結 命令。
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::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 應用程式的回溯相容性提供)。
建立新的命令。
HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();
工作階段
[in] CSession
要與新命令相關聯的物件。
標準 HRESULT。
這個方法會使用指定的會話物件來建立命令。
取得命令參數、其名稱及其類型的清單。
HRESULT CCommandBase::GetParameterInfo(DB_UPARAMS* pParams,
DBPARAMINFO** ppParamInfo,
OLECHAR** ppNamesBuffer) throw ();
請參閱 OLE DB 程式設計人員參考中的 ICommandWithParameters::GetParameterInfo。
標準 HRESULT。
驗證並優化目前的命令。
HRESULT CCommandBase::Prepare(ULONG cExpectedRuns = 0) throw();
cExpectedRuns
[in]您預期要執行命令的次數。
標準 HRESULT。
此方法會包裝 OLE DB 方法 ICommandPrepare::P repare。
釋放參數存取子,然後再釋放命令本身。
void CCommandBase::ReleaseCommand() throw();
ReleaseCommand
與搭配 Close
使用。 如需使用量詳細數據,請參閱 關閉 。
指定每個命令參數的原生類型。
HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
const DBORDINAL* pOrdinals,
const DBPARAMBINDINFO* pParamInfo) throw();
請參閱 OLE DB 程式設計人員參考中的 ICommandWithParameters::SetParameterInfo。
標準 HRESULT。
捨棄目前的命令執行計劃。
HRESULT CCommandBase::Unprepare() throw();
標準 HRESULT。
此方法會包裝 OLE DB 方法 ICommandPrepare::Unprepare。