Класс 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 Возвращает следующий результат при использовании нескольких результирующих наборов.
Открыть Выполняет и при необходимости привязывает команду.

Наследуемые методы

Имя Описание
Создание Создает новую команду для указанного сеанса, а затем задает текст команды.
CreateCommand Создает новую команду.
GetParameterInfo Возвращает список параметров команды, их имен и их типов.
Подготовка Проверяет и оптимизирует текущую команду.
ReleaseCommand При необходимости освобождает метод доступа к параметру, а затем освобождает команду.
SetParameterInfo Задает собственный тип каждого параметра команды.
Неподготовленный Отменяет текущий план выполнения команды.

Замечания

Используйте этот класс, если необходимо выполнить операцию на основе параметров или выполнить команду. Если вам просто нужно открыть простой набор строк, используйте вместо этого CTable .

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

Обратите внимание, что нельзя использовать хранимые процедуры с поставщиком OLE DB для Jet, так как этот поставщик не поддерживает хранимые процедуры (только константы разрешены в строках запроса).

CCommand::Close

Освобождает набор строк метода доступа, связанный с командой.

Синтаксис

void Close();

Замечания

Команда использует набор строк, метод доступа результирующих наборов и (необязательно) метод доступа к параметрам (в отличие от таблиц, которые не поддерживают параметры и не нуждаются в методе доступа к параметрам).

При выполнении команды необходимо вызвать и Close ReleaseCommand после команды.

При повторном выполнении одной и той же команды необходимо освободить каждый метод доступа к результирующем набору, вызвав перед вызовом Close Execute. В конце серии необходимо освободить метод доступа к параметрам путем вызова ReleaseCommand. Другой распространенный сценарий — вызов хранимой процедуры с выходными параметрами. Во многих поставщиках (например, поставщик OLE DB для 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();
}

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] Команда для выполнения, переданная в виде строки Юникода. Может иметь значение NULL при использовании CAccessor. В этом случае команда будет извлечена из значения, переданного макросу DEFINE_COMMAND . Дополнительные сведения см. в разделе "ICommand::Execute" в справочнике программиста OLE DB.

szCommand
[in] То же, что и wszCommand , за исключением того, что этот параметр принимает командную строку ANSI. Четвертая форма этого метода может принимать значение NULL. Дополнительные сведения см. в разделе "Примечания" далее в этом разделе.

pPropSet
[in] Указатель на массив структур DBPROPSET , содержащих свойства и значения, которые необходимо задать. См . раздел "Наборы свойств" и "Группы свойств" в справочнике программиста OLE DB в пакете SDK для Windows.

pRowsAffected
[in/out] Указатель на память, в которой возвращается количество строк, затронутых командой. Если *pRowsAffected имеет значение NULL, число строк не возвращается. Open В противном случае задает *pRowsAffected в соответствии со следующими условиями:

If Следующее действие
Элемент cParamSets pParams больше 1 *pRowsAffected представляет общее количество строк, затронутых всеми наборами параметров, указанными в выполнении.
Количество затронутых строк недоступно *pRowsAffected имеет значение -1.
Команда не обновляет, удалять или вставлять строки *pRowsAffected не определен.

guidCommand
[in] ИДЕНТИФИКАТОР GUID, указывающий синтаксис и общие правила для поставщика, который будет использоваться при анализе текста команды. Дополнительные сведения см. в разделе ICommandText::GetCommandText и ICommandText::SetCommandText в справочнике программиста OLE DB.

bBind
[in] Указывает, следует ли автоматически привязать команду после выполнения. Значением по умолчанию является true, что приводит к автоматической привязке команды. Настройка bBind , чтобы false предотвратить автоматическую привязку команды, чтобы можно было выполнить привязку вручную. (Привязка вручную является особенно интересной для пользователей OLAP.)

ulPropSets
[in] Число структур DBPROPSET, переданных в аргументе pPropSet.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Первые три формы принятия сеанса Open , создание команды и выполнение команды, привязка всех параметров по мере необходимости.

Первая форма принимает командную строку Юникода Open и не имеет значения по умолчанию.

Вторая форма Open принимает командную строку ANSI и значение по умолчанию (предоставляется для обратной совместимости с существующими приложениями ANSI).

Третья форма Open позволяет командной строке иметь значение NULL из-за типа int со значением NULL по умолчанию. Он предоставляется для вызова Open(session, NULL); или Open(session); из-за типа intNULL. Для этой версии требуется и утверждается, что int параметр имеет значение NULL.

Используйте четвертую форму Open , когда вы уже создали команду, и вы хотите выполнить одну подготовку и несколько выполнений.

Примечание.

Open вызовы 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 ();

Параметры

сеанс
[in] Сеанс, на котором создается команда.

wszCommand
[in] Указатель на текст Юникода командной строки.

szCommand
[in] Указатель на текст ANSI командной строки.

guidCommand
[in] ИДЕНТИФИКАТОР GUID, указывающий синтаксис и общие правила для поставщика, который будет использоваться при анализе текста команды. Описание диалектов см. в разделе ICommandText::GetCommandText в справочнике программиста OLE DB.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Первая форма принимает командную строку Юникода Create . Вторая форма принимает командную строку ANSI (предоставляется для обратной Create совместимости с существующими приложениями 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 ();

Параметры

См. раздел ICommandWithParameters::GetParameterInfo в справочнике программиста OLE DB.

Возвращаемое значение

Стандартный HRESULT.

CCommand::Prepare

Проверяет и оптимизирует текущую команду.

Синтаксис

HRESULT CCommandBase::Prepare(ULONG cExpectedRuns = 0) throw();

Параметры

cExpectedRuns
[in] Количество раз, когда требуется выполнить команду.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Этот метод упаковывает метод OLE DB ICommandPrepare::P repare.

CCommand::ReleaseCommand

Освобождает метод доступа к параметрам, а затем освобождает саму команду.

Синтаксис

void CCommandBase::ReleaseCommand() throw();

Замечания

ReleaseCommand используется в сочетании с Close. Дополнительные сведения об использовании см. в разделе "Закрыть ".

CCommand::SetParameterInfo

Задает собственный тип каждого параметра команды.

Синтаксис

HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
   const DBORDINAL* pOrdinals,
   const DBPARAMBINDINFO* pParamInfo) throw();

Параметры

См. раздел ICommandWithParameters::SetParameterInfo в справочнике программиста OLE DB.

Возвращаемое значение

Стандартный HRESULT.

CCommand::Unprepare

Отменяет текущий план выполнения команды.

Синтаксис

HRESULT CCommandBase::Unprepare() throw();

Возвращаемое значение

Стандартный HRESULT.

Замечания

Этот метод упаковывает метод OLE DB ICommandPrepare::Unprepare.

См. также

Шаблоны объекта-получателя OLE DB
Ссылка на шаблоны объекта-получателя OLE DB