`db_command`

项目
06/16/2023

创建 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_fname 和 m_au_lname 数据成员绑定到 pubs 数据库中作者表的 au_fname 和 au_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
（可选）用于处理行集的句柄名称。如果指定名称 name，db_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_command 和 db_column 配合使用。

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

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

示例

本示例定义一个命令，该命令从状态列与“CA”匹配的表格中选择第一个和最后一个名称。 db_command 创建并读取行集，在行集上可以调用向导生成的函数（例如 OpenAll 和 CloseAll）和 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_command 和 CCommand1 上的 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();
}

要求

特性上下文	值
适用于	`class`、`struct`、member、method、local
可重复	否
必需的特性	无
无效的特性	无

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

另请参阅

OLE DB 使用者特性
 独立特性

通过

`db_command`

语法

参数

备注

示例

要求

另请参阅

反馈

其他资源