db_command

创建 OLE DB 命令。

语法

[ db_command(command, name, source_name, hresult, bindings, bulk_fetch) ]

参数

command
包含 OLE DB 命令文本的命令字符串。 一个简单的例子是:

[ db_command ( command = "Select * from Products" ) ]

command 语法如下所示:

绑定参数块 1
  OLE DB 命令
绑定参数块 2
  OLE DB 命令的延续
绑定参数块 3
...

绑定参数块的定义如下:

(bindtype szVar1 [, szVar2 [, nVar3 [, ...]])

其中:

  • ( 标记数据绑定块的开始位置。

  • bindtype 是以下不区分大小写的字符串之一:

    • [db_column] 将每个成员变量绑定到行集中的列。

    • [bindto](与 [db_column] 相同)。

    • [in] 将成员变量绑定为输入参数。

    • [out] 将成员变量绑定为输出参数。

    • [in,out] 将成员变量绑定为输入/输出参数。

  • szVarN、nVarN 解析为当前范围内的成员变量。

  • ) 标记数据绑定块的结束位置。

如果命令字符串包含一个或多个说明符(例如 [in][out][in/out]),db_command 会生成参数映射。

如果命令字符串中包含一个或多个参数(例如 [db_column][bindto]),db_command 会生成行集和取值函数映射以服务这些绑定变量。 有关详细信息,请参阅 db_accessor

注意

在类级别使用 db_command 时,bindtype 语法和 bindings 参数无效。

下面是一些绑定参数块的示例。 下面的示例分别将 m_au_fnamem_au_lname 数据成员绑定到 pubs 数据库中作者表的 au_fnameau_lname 列:

TCHAR m_au_fname[21];
TCHAR m_au_lname[41];
TCHAR m_state[3] = 'CA';

[db_command (command = "SELECT au_fname([bindto]m_au_fname), au_lname([bindto]m_au_lname) " \
   "FROM dbo.authors " \
   "WHERE state = ?([in]m_state)")
]

name
(可选)用于处理行集的句柄名称。 如果指定名称 namedb_command 会生成具有指定 name 的类,可以用它来遍历行集或执行多个操作查询。 如果未指定 name,则无法向用户返回多个行的结果。

source_name
(可选)向其应用 db_source 特性的类的 CSession 变量或实例(在其上运行命令)。 请参阅 db_source

db_command 检查可确保用于 source_name 的变量有效,使指定的变量位于函数或全局范围内。

hresult
(可选)标识将接收此数据库命令的 HRESULT 的变量。 如果该变量不存在,特性会将其自动插入。

bindings
(可选)允许从 OLE DB 命令分离绑定参数。

如果指定 bindings 的值,db_command 会分析相关联的值,但不会分析 bindtype 参数。 这种用法允许使用 OLE DB 提供程序语法。 若要禁用分析,但不绑定参数,请指定 Bindings=""

如果未指定 bindings 的值,db_command 会分析绑定参数块。 它查找“(”,其后依次跟着 bindtype(在括号中)、一个或多个以前声明的 C++ 成员变量、“)”。 它从生成的命令中去除括号内的所有文本。 这些参数用于构造此命令的列和参数绑定。

bulk_fetch
(可选)指定要提取的行数的整数值。

默认值为 1,指定单行提取(行集将为 CRowset 类型)。

大于 1 的值指定批量取行。 批量取行指提取多个行句柄的批量行集功能(行集将为 CBulkRowset 类型,并将采用指定的行数调用 SetRows)。

如果 bulk_fetch 小于 1,SetRows 将返回零。

备注

db_command 创建 CCommand 对象,OLE DB 使用者使用该对象来执行命令。

可以将 db_command 与类或函数范围一起使用,主要差异在于 CCommand 对象的范围。 使用函数范围,绑定等数据终止于函数末端。 类和函数范围的用法均涉及到 OLE DB 使用者模板类 CCommand<>,但对于函数事例和类事例,模板参数不同。 在函数事例中,将绑定包含本地变量的 Accessor,而类用法将 CAccessor 派生类推断为参数。 用作类特性时,db_commanddb_column 配合使用。

db_command 可用于执行不返回结果集的命令。

使用者特性提供程序将此特性应用到某个类时,编译器会将该类重命名为 _[YourClassName]Accessor,其中 [YourClassName] 是你为类提供的名称。 编译器还会创建一个名为 [YourClassName] 的类,该类派生自 _[YourClassName]Accessor。 将在类视图中看到这两个类。

示例

本示例定义一个命令,该命令从状态列与“CA”匹配的表格中选择第一个和最后一个名称。 db_command 创建并读取行集,在行集上可以调用向导生成的函数(例如 OpenAllCloseAll)和 CRowset 成员函数(例如 MoveNext)。

此代码要求提供你自己的连接到 pubs 数据库的连接字符串。 若要了解如何在开发环境中提供连接字符串,请参阅如何:连接到数据库并浏览现有对象添加新连接

源文件 db_command.h

// db_command.h
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>

#pragma once

[  db_source(L"your connection string"), db_command(L" \
      SELECT au_lname, au_fname \
      FROM dbo.authors \
      WHERE state = 'CA'")  ]

struct CAuthors {
   // In order to fix several issues with some providers, the code below may bind
   // columns in a different order than reported by the provider

   DBSTATUS m_dwau_lnameStatus;
   DBSTATUS m_dwau_fnameStatus;
   DBLENGTH m_dwau_lnameLength;
   DBLENGTH m_dwau_fnameLength;

   [ db_column("au_lname", status="m_dwau_lnameStatus", length="m_dwau_lnameLength") ] TCHAR m_au_lname[41];
   [ db_column("au_fname", status="m_dwau_fnameStatus", length="m_dwau_fnameLength") ] TCHAR m_au_fname[21];

   [ db_param("7", paramtype="DBPARAMIO_INPUT") ] TCHAR m_state[3];

   void GetRowsetProperties(CDBPropSet* pPropSet) {
      pPropSet->AddProperty(DBPROP_CANFETCHBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
      pPropSet->AddProperty(DBPROP_CANSCROLLBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
   }
};

源文件 db_command.cpp

// db_command.cpp
// compile with: /c
#include "db_command.h"

int main(int argc, _TCHAR* argv[]) {
   HRESULT hr = CoInitialize(NULL);

   // Instantiate rowset
   CAuthors rs;

   // Open rowset and move to first row
   strcpy_s(rs.m_state, sizeof(rs.m_state), _T("CA"));
   hr = rs.OpenAll();
   hr = rs.MoveFirst();

   // Iterate through the rowset
   while( SUCCEEDED(hr) && hr != DB_S_ENDOFROWSET ) {
      // Print out the column information for each row
      printf("First Name: %s, Last Name: %s\n", rs.m_au_fname, rs.m_au_lname);
      hr = rs.MoveNext();
   }

   rs.CloseAll();
   CoUninitialize();
}

此示例使用数据源类 db_source 上的 CMySource以及命令类 db_commandCCommand1 上的 CCommand2

// db_command_2.cpp
// compile with: /c
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>
// class usage for both db_source and db_command

[  db_source(L"your connection string"), db_command(L" \
      SELECT au_lname, au_fname \
      FROM dbo.authors \
      WHERE state = 'CA'")  ]
struct CMySource {
   HRESULT OpenDataSource() {
      return S_OK;
   }
};

[db_command(command = "SELECT * FROM Products")]
class CCommand1 {};

[db_command(command = "SELECT FNAME, LNAME FROM Customers")]
class CCommand2 {};

int main() {
   CMySource s;
   HRESULT hr = s.OpenDataSource();
   if (SUCCEEDED(hr)) {
      CCommand1 c1;
      hr = c1.Open(s);

      CCommand2 c2;
      hr = c2.Open(s);
   }

   s.CloseDataSource();
}

要求

特性上下文
适用于 classstruct、member、method、local
可重复
必需的特性
无效的特性

有关特性上下文的详细信息,请参阅特性上下文

另请参阅

OLE DB 使用者特性
独立特性