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

成员

方法

名称 描述
Close 关闭当前命令。
GetNextResult 在使用多个结果集时提取下一个结果。
打开 执行并选择性地绑定命令。

继承的方法

名称 描述
创建 为指定会话创建新命令，然后设置命令文本。
CreateCommand 创建新的命令。
GetParameterInfo 获取命令的参数、参数名称和参数类型的列表。
准备 验证并优化当前命令。
ReleaseCommand 在必要时释放参数访问器，然后释放命令。
SetParameterInfo 指定每个命令参数的本机类型。
Unprepare 放弃当前命令执行计划。

注解

当你需要执行基于参数的操作或执行命令时，请使用此类。 如果只需要打开一个简单行集，请使用 CTable。

使用的访问器类可确定绑定参数和数据的方法。

请注意，不能将存储过程与 Jet 的 OLE DB 提供程序一起使用，因为该提供程序不支持存储过程（查询字符串中只允许使用常数）。

CCommand::Close

发布与命令关联的访问器行集。

语法

void Close();

备注

命令使用行集、结果集访问器和（可选的）参数访问器（与不支持参数并且不需要参数访问器的表不同）。

执行某个命令时，您应该在该命令之后调用 Close 和 ReleaseCommand。

当你要重复执行同一命令时，你应通过在调用 Close 之前调用 Execute 来发布每个结果集访问器。 在序列末尾，应通过调用 ReleaseCommand 发布参数访问器。 另一种常见情形是调用具有输出参数的存储过程。 在很多提供程序（如 SQL Server 的 OLE DB 提供程序）上，输出参数值在您关闭结果集访问器前不可访问。 调用 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：

如果 Then
pParams 的 cParamSets 元素大于 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 c调用 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 ();

参数

session
[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::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 使用者模板参考