Класс CCommandCCommand Class

Предоставляет методы для задания и выполнения команды.Provides methods to set and execute a command.

СинтаксисSyntax

template <class TAccessor = CNoAccessor,
   template <typename T> class TRowset = CRowset,
   class TMultiple = CNoMultipleResults>
class CCommand :
   public CAccessorRowset <TAccessor, TRowset>,
   public CCommandBase,
   public TMultiple

ПараметрыParameters

такцессорTAccessor
Тип класса метода доступа (например,, CDynamicParameterAccessor CDynamicStringAccessor или CEnumeratorAccessor ), который должна использовать команда.The type of accessor class (such as CDynamicParameterAccessor, CDynamicStringAccessor, or CEnumeratorAccessor) that you want the command to use. Значение по умолчанию — CNoAccessor , которое указывает, что класс не поддерживает параметры или выходные столбцы.The default is CNoAccessor, which specifies that the class not support parameters or output columns.

тровсетTRowset
Тип класса набора строк (например, CArrayRowset или CNoRowset ), который должна использовать команда.The type of rowset class (such as CArrayRowset or CNoRowset) that you want the command to use. Значение по умолчанию — CRowset.The default is CRowset.

тмултиплеTMultiple
Чтобы использовать команду OLE DB, которая может возвращать несколько результатов, укажите CMultipleResults.To use an OLE DB command that can return multiple results, specify CMultipleResults. В противном случае используйте CNoMultipleResults.Otherwise, use CNoMultipleResults. Дополнительные сведения см. в разделе IMultipleResults.For details, see IMultipleResults.

ТребованияRequirements

Заголовок: atldbcli.hHeader: atldbcli.h

ЭлементыMembers

МетодыMethods

ИмяName ОписаниеDescription
ЗакрытьClose Закрывает текущую команду.Closes the current command.
жетнекстресултGetNextResult Извлекает следующий результат при использовании нескольких результирующих наборов.Fetches the next result when using multiple result sets.
ОткрытьOpen Выполняет и при необходимости привязывает команду.Executes and optionally binds the command.

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

ИмяName ОписаниеDescription
СозданиеCreate Создает новую команду для указанного сеанса, а затем задает текст команды.Creates a new command for the specified session, then sets the command text.
CreateCommandCreateCommand Создает новую команду.Creates a new command.
GetParameterInfoGetParameterInfo Возвращает список параметров команды, их имена и типы.Gets a list of the command's parameters, their names, and their types.
ПодготовкаPrepare Проверяет и оптимизирует текущую команду.Validates and optimizes the current command.
релеасекоммандReleaseCommand При необходимости освобождает метод доступа к параметру, а затем освобождает команду.Releases the parameter accessor if necessary, then releases the command.
SetParameterInfoSetParameterInfo Задает собственный тип для каждого параметра команды.Specifies the native type of each command parameter.
UnprepareUnprepare Отменяет текущий план выполнения команды.Discards the current command execution plan.

КомментарииRemarks

Используйте этот класс, если необходимо выполнить операцию на основе параметров или выполнить команду.Use this class when you need to perform a parameter-based operation or execute a command. Если нужно просто открыть простой набор строк, используйте вместо него CTable .If you merely need to open a simple rowset, use CTable instead.

Класс метода доступа, который вы используете, определяет метод привязки параметров и данных.The accessor class you are using determines the method of binding parameters and data.

Обратите внимание, что нельзя использовать хранимые процедуры с поставщиком OLE DB для Jet, так как этот поставщик не поддерживает хранимые процедуры (в строках запросов разрешены только константы).Note that you cannot use stored procedures with the OLE DB Provider for Jet because that provider does not support stored procedures (only constants are allowed in query strings).

CCommand:: CloseCCommand::Close

Освобождает набор строк метода доступа, связанный с командой.Releases the accessor rowset associated with the command.

СинтаксисSyntax

void Close();

RemarksRemarks

Команда использует набор строк, метод доступа set Result и (необязательно) метод доступа к параметру (в отличие от таблиц, которые не поддерживают параметры и не требуют метода доступа к параметрам).A command uses a rowset, result set accessor, and (optionally) a parameter accessor (unlike tables, which do not support parameters and do not need a parameter accessor).

При выполнении команды необходимо вызвать обе функции Close и релеасекомманд после команды.When you execute a command, you should call both Close and ReleaseCommand after the command.

Если необходимо повторно выполнить одну и ту же команду, следует освободить метод доступа к результирующему набору, вызвав Close перед вызовом метода Execute .When you want to execute the same command repeatedly, you should release each result set accessor by calling Close before calling Execute. В конце серии необходимо освободить метод доступа к параметру, вызвав ReleaseCommand .At the end of the series, you should release the parameter accessor by calling ReleaseCommand. Другой распространенный сценарий — вызов хранимой процедуры, которая имеет выходные параметры.Another common scenario is calling a stored procedure that has output parameters. Во многих поставщиках (например, поставщик OLE DB для SQL Server) значения выходных параметров будут недоступны до закрытия метода доступа к результирующему набору.On many providers (such as the OLE DB provider for SQL Server) the output parameter values will not be accessible until you close the result set accessor. Вызовите, Close чтобы закрыть возвращаемый набор строк и метод доступа к результирующему набору, но не метод доступа к параметру, что позволяет получить значения выходных параметров.Call Close to close the returned rowset and result set accessor, but not the parameter accessor, thus allowing you to retrieve the output parameter values.

ПримерExample

В следующем примере показано, как можно вызывать Close и ReleaseCommand при повторном выполнении одной и той же команды.The following example shows how you can call Close and ReleaseCommand when you execute the same command repeatedly.

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:: ЖетнекстресултCCommand::GetNextResult

Выбирает следующий результирующий набор, если он доступен.Fetches the next result set if one is available.

СинтаксисSyntax

HRESULT GetNextResult(DBROWCOUNT* pulRowsAffected,
   bool bBind = true) throw();

ПараметрыParameters

пулровсаффектедpulRowsAffected
[вход/выход] Указатель на память, в которой возвращается число строк, затронутых командой.[in/out] A pointer to memory where the count of rows affected by a command is returned.

ббиндbBind
окне Указывает, следует ли выполнять автоматическую привязку команды после ее выполнения.[in] Specifies whether to bind the command automatically after being executed. Значение по умолчанию — true , что приводит к автоматическому связыванию команды.The default is true, which causes the command to be bound automatically. Установка параметра ббинд для false предотвращения автоматической привязки команды, чтобы можно было выполнить привязку вручную.Setting bBind to false prevents the automatic binding of the command so that you can bind manually. (Ручная привязка особенно интересна для пользователей OLAP.)(Manual binding is of particular interest to OLAP users.)

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

Стандартное значение HRESULT.A standard HRESULT.

КомментарииRemarks

Если результирующий набор был ранее выбран, эта функция освобождает предыдущий результирующий набор и отменяет привязку столбцов.If a result set has been previously fetched, this function releases the previous result set and unbinds the columns. Если ббинд имеет значение true , то он привязывает новые столбцы.If bBind is true, it binds the new columns.

Эту функцию следует вызывать только в том случае, если вы указали несколько результатов, задав CCommand параметр шаблона тмултипле = CMultipleResults .You should call this function only if you have specified multiple results by setting the CCommand template parameter TMultiple=CMultipleResults.

CCommand:: OpenCCommand::Open

Выполняет и при необходимости привязывает команду.Executes and optionally binds the command.

СинтаксисSyntax

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();

ПараметрыParameters

сессииsession
окне Сеанс, в котором выполняется команда.[in] The session in which to execute the command.

всзкоммандwszCommand
окне Выполняемая команда, передаваемая как строка в Юникоде.[in] The command to execute, passed as a Unicode string. Может иметь значение NULL при использовании CAccessor , в этом случае команда будет получена из значения, переданного в макрос DEFINE_COMMAND .Can be NULL when using CAccessor, in which case the command will be retrieved from the value passed to the DEFINE_COMMAND macro. Дополнительные сведения см. в разделе ICommand:: Execute в OLE DB справочнике программиста .See ICommand::Execute in the OLE DB Programmer's Reference for details.

сзкоммандszCommand
окне То же, что и всзкомманд , за исключением того, что этот параметр принимает строку команды ANSI.[in] Same as wszCommand except that this parameter takes an ANSI command string. Четвертая форма этого метода может принимать значение NULL.The fourth form of this method can take a NULL value. Дополнительные сведения см. в разделе "Примечания" Далее в этом разделе.See "Remarks" later in this topic for details.

pPropSetpPropSet
окне Указатель на массив структур DBPROPSET , содержащий свойства и значения, которые необходимо задать.[in] A pointer to an array of DBPROPSET structures containing properties and values to be set. См. раздел наборы свойств и группы свойств в справочнике по OLE DB программисту в Windows SDK.See Property Sets and Property Groups in the OLE DB Programmer's Reference in the Windows SDK.

провсаффектедpRowsAffected
[вход/выход] Указатель на память, в которой возвращается число строк, затронутых командой.[in/out] A pointer to memory where the count of rows affected by a command is returned. Если * провсаффектед имеет значение null, число строк не возвращается.If *pRowsAffected is NULL, no row count is returned. В противном случае Open устанавливает * провсаффектед в соответствии со следующими условиями:Otherwise, Open sets *pRowsAffected according to the following conditions:

IfIf Следующее действиеThen
cParamSetsЭлемент pParams больше 1The cParamSets element of pParams is greater than 1 * провсаффектед представляет общее количество строк, затронутых всеми наборами параметров, указанными при выполнении.*pRowsAffected represents the total number of rows affected by all of the parameter sets specified in the execution.
Количество затронутых строк недоступноThe number of affected rows is not available * провсаффектед имеет значение-1.*pRowsAffected is set to -1.
Команда не обновляет, не удаляет или не вставляет строкиThe command does not update, delete, or insert rows * провсаффектед не определен.*pRowsAffected is undefined.

гуидкоммандguidCommand
окне Идентификатор GUID, указывающий синтаксис и общие правила для поставщика, используемого при анализе текста команды.[in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. Дополнительные сведения см. в разделе ICommandText:: жеткоммандтекст and ICommandText:: SetCommandText в справочнике программиста OLE DB .See ICommandText::GetCommandText and ICommandText::SetCommandText in the OLE DB Programmer's Reference for details.

ббиндbBind
окне Указывает, следует ли выполнять автоматическую привязку команды после ее выполнения.[in] Specifies whether to bind the command automatically after being executed. Значение по умолчанию — true , что приводит к автоматическому связыванию команды.The default is true, which causes the command to be bound automatically. Установка параметра ббинд для false предотвращения автоматической привязки команды, чтобы можно было выполнить привязку вручную.Setting bBind to false prevents the automatic binding of the command so that you can bind manually. (Ручная привязка особенно интересна для пользователей OLAP.)(Manual binding is of particular interest to OLAP users.)

улпропсетсulPropSets
окне Число структур DBPROPSET , переданных в аргументе ппропсет .[in] The number of DBPROPSET structures passed in the pPropSet argument.

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

Стандартное значение HRESULT.A standard HRESULT.

КомментарииRemarks

Первые три формы Open принимают сеанс, создают команду и выполняют команду, привязывая все необходимые параметры.The first three forms of Open take a session, create a command, and execute the command, binding any parameters as necessary.

Первая форма Open принимает строку команды в Юникоде и не имеет значения по умолчанию.The first form of Open takes a Unicode command string and has no default value.

Вторая форма Open принимает строку команды ANSI и не имеет значения по умолчанию (предоставляется для обеспечения обратной совместимости с существующими приложениями ANSI).The second form of Open takes an ANSI command string and no default value (provided for backward compatibility with existing ANSI applications).

Третья форма Open позволяет строке команды иметь значение null, так как тип int со значением по умолчанию NULL.The third form of Open allows the command string to be NULL, because of type int with a default value of NULL. Он предоставляется для вызова Open(session, NULL); или, Open(session); поскольку null имеет тип int .It is provided for calling Open(session, NULL); or Open(session); because NULL is of type int. Эта версия требует и утверждает, что int параметр имеет значение null.This version requires and asserts that the int parameter be NULL.

Используйте четвертую форму, Open Если вы уже создали команду и хотите выполнить одну подготовку и несколько выполнений.Use the fourth form of Open when you have already created a command and you want to perform a single Prepare and multiple executions.

Примечание

Open вызовы Execute , которые, в свою очередь, вызывают GetNextResult .Open calls Execute, which in turn calls GetNextResult.

CCommand:: CreateCCommand::Create

Вызывает метод CCommand:: CreateCommand , чтобы создать команду для указанного сеанса, а затем вызывает ICommandText:: SetCommandText , чтобы указать текст команды.Calls CCommand::CreateCommand to create a command for the specified session, then calls ICommandText::SetCommandText to specify the command text.

СинтаксисSyntax

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 ();

ПараметрыParameters

сессииsession
окне Сеанс, в котором создается команда.[in] A session on which to create the command.

всзкоммандwszCommand
окне Указатель на текст в Юникоде строки команды.[in] A pointer to the Unicode text of the command string.

сзкоммандszCommand
окне Указатель на текст строки команды в формате ANSI.[in] A pointer to the ANSI text of the command string.

гуидкоммандguidCommand
окне Идентификатор GUID, указывающий синтаксис и общие правила для поставщика, используемого при анализе текста команды.[in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. Описание диалектов см. в разделе ICommandText:: жеткоммандтекст в справочнике программиста OLE DB.For a description of dialects, see ICommandText::GetCommandText in the OLE DB Programmer's Reference.

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

Стандартное значение HRESULT.A standard HRESULT.

КомментарииRemarks

Первая форма Create принимает строку команды в Юникоде.The first form of Create takes a Unicode command string. Вторая форма Create принимает строку команды ANSI (предоставляется для обеспечения обратной совместимости с существующими приложениями ANSI).The second form of Create takes an ANSI command string (provided for backward compatibility with existing ANSI applications).

CCommand:: CreateCommandCCommand::CreateCommand

Создает новую команду.Creates a new command.

СинтаксисSyntax

HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();

ПараметрыParameters

сессииsession
окне CSession Объект, связываемый с новой командой.[in] A CSession object to be associated with the new command.

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

Стандартное значение HRESULT.A standard HRESULT.

КомментарииRemarks

Этот метод создает команду, используя указанный объект сеанса.This method creates a command using the specified session object.

CCommand:: GetParameterInfoCCommand::GetParameterInfo

Возвращает список параметров команды, их имена и типы.Gets a list of the command's parameters, their names, and their types.

СинтаксисSyntax

HRESULT CCommandBase::GetParameterInfo(DB_UPARAMS* pParams,
   DBPARAMINFO** ppParamInfo,
   OLECHAR** ppNamesBuffer) throw ();

ПараметрыParameters

См. раздел ICommandWithParameters:: GetParameterInfo в справочнике программиста OLE DB.See ICommandWithParameters::GetParameterInfo in the OLE DB Programmer's Reference.

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

Стандартное значение HRESULT.A standard HRESULT.

CCommand::P готовкаCCommand::Prepare

Проверяет и оптимизирует текущую команду.Validates and optimizes the current command.

СинтаксисSyntax

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

ПараметрыParameters

цекспектедрунсcExpectedRuns
окне Количество ситуаций, в которых должна выполняться команда.[in] The number of times you expect to execute the command.

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

Стандартное значение HRESULT.A standard HRESULT.

КомментарииRemarks

Этот метод создает оболочку для метода OLE DB ICommandPrepare::P готовка.This method wraps the OLE DB method ICommandPrepare::Prepare.

CCommand:: РелеасекоммандCCommand::ReleaseCommand

Освобождает метод доступа к параметру, а затем освобождает саму команду.Releases the parameter accessor, then releases the command itself.

СинтаксисSyntax

void CCommandBase::ReleaseCommand() throw();

RemarksRemarks

ReleaseCommand используется в сочетании с Close .ReleaseCommand is used in conjunction with Close. Сведения об использовании см. в разделе " Закрыть ".See Close for usage details.

CCommand:: SetParameterInfoCCommand::SetParameterInfo

Задает собственный тип для каждого параметра команды.Specifies the native type of each command parameter.

СинтаксисSyntax

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

ПараметрыParameters

См. раздел ICommandWithParameters:: SetParameterInfo в справочнике программиста OLE DB.See ICommandWithParameters::SetParameterInfo in the OLE DB Programmer's Reference.

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

Стандартное значение HRESULT.A standard HRESULT.

CCommand:: unprepareCCommand::Unprepare

Отменяет текущий план выполнения команды.Discards the current command execution plan.

СинтаксисSyntax

HRESULT CCommandBase::Unprepare() throw();

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

Стандартное значение HRESULT.A standard HRESULT.

КомментарииRemarks

Этот метод создает оболочку для метода OLE DB ICommandPrepare:: unprepare.This method wraps the OLE DB method ICommandPrepare::Unprepare.

См. также разделSee also

Шаблоны объекта-получателя OLE DBOLE DB Consumer Templates
Справочник по шаблонам потребителей OLE DBOLE DB Consumer Templates Reference