`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.

Примечание.

bindtype синтаксис и bindings параметр недопустимы при использовании db_command на уровне класса.

Ниже приведены некоторые примеры привязки блоков параметров. В следующем примере элементы данных привязываются m_au_fname к au_fname столбцам и m_au_lname au_lname столбцам, соответственно, из таблицы авторов в pubs базе данных:

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
Переменная CSession или экземпляр класса с примененным атрибутом db_source, по которому выполняется команда (необязательно). См. раздел 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 значение меньше одного, SetRows возвращается ноль.

Замечания

db_commandCCommand создает объект, который используется потребителем 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`член, метод, локальный
Повторяемый	No
Обязательные атрибуты	нет
Недопустимые атрибуты	нет

Дополнительные сведения о контекстах атрибутов см. в разделе "Контексты атрибутов".

См. также

Атрибуты потребителя OLE DB
Автономные атрибуты

Поделиться через