description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CCommand Class |
CCommand Class |
11/04/2016 |
|
|
0760bfc5-b9ee-4aee-8e54-31bd78714d3a |
Provides methods to set and execute a command.
template <class TAccessor = CNoAccessor,
template <typename T> class TRowset = CRowset,
class TMultiple = CNoMultipleResults>
class CCommand :
public CAccessorRowset <TAccessor, TRowset>,
public CCommandBase,
public TMultiple
TAccessor
The type of accessor class (such as CDynamicParameterAccessor
, CDynamicStringAccessor
, or CEnumeratorAccessor
) that you want the command to use. The default is CNoAccessor
, which specifies that the class not support parameters or output columns.
TRowset
The type of rowset class (such as CArrayRowset
or CNoRowset
) that you want the command to use. The default is CRowset
.
TMultiple
To use an OLE DB command that can return multiple results, specify CMultipleResults. Otherwise, use CNoMultipleResults. For details, see IMultipleResults.
Header: atldbcli.h
Name | Description |
---|---|
Close | Closes the current command. |
GetNextResult | Fetches the next result when using multiple result sets. |
Open | Executes and optionally binds the command. |
Name | Description |
---|---|
Create | Creates a new command for the specified session, then sets the command text. |
CreateCommand | Creates a new command. |
GetParameterInfo | 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. |
SetParameterInfo | Specifies the native type of each command parameter. |
Unprepare | Discards the current command execution plan. |
Use this class when you need to perform a parameter-based operation or execute a command. 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.
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).
Releases the accessor rowset associated with the command.
void Close();
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).
When you execute a command, you should call both Close
and ReleaseCommand after the command.
When you want to execute the same command repeatedly, you should release each result set accessor by calling Close
before calling Execute
. 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. 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. 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.
The following example shows how you can call Close
and ReleaseCommand
when you execute the same command repeatedly.
[!code-cppNVC_OLEDB_Consumer#2]
Fetches the next result set if one is available.
HRESULT GetNextResult(DBROWCOUNT* pulRowsAffected,
bool bBind = true) throw();
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. The default is true
, which causes the command to be bound automatically. Setting bBind to false
prevents the automatic binding of the command so that you can bind manually. (Manual binding is of particular interest to OLAP users.)
A standard HRESULT.
If a result set has been previously fetched, this function releases the previous result set and unbinds the columns. If bBind is true
, it binds the new columns.
You should call this function only if you have specified multiple results by setting the CCommand
template parameter TMultiple=CMultipleResults
.
Executes and optionally binds the command.
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();
session
[in] The session in which to execute the command.
wszCommand
[in] The command to execute, passed as a Unicode string. Can be NULL when using CAccessor
, in which case the command will be retrieved from the value passed to the DEFINE_COMMAND macro. See ICommand::Execute in the OLE DB Programmer's Reference for details.
szCommand
[in] Same as wszCommand except that this parameter takes an ANSI command string. The fourth form of this method can take a NULL value. See "Remarks" later in this topic for details.
pPropSet
[in] A pointer to an array of DBPROPSET structures containing properties and values to be set. 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. If *pRowsAffected is NULL, no row count is returned. Otherwise, Open
sets *pRowsAffected according to the following conditions:
If | Then |
---|---|
The 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 | *pRowsAffected is set to -1. |
The command does not update, delete, or insert rows | *pRowsAffected is undefined. |
guidCommand
[in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. 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. The default is true
, which causes the command to be bound automatically. Setting bBind to false
prevents the automatic binding of the command so that you can bind manually. (Manual binding is of particular interest to OLAP users.)
ulPropSets
[in] The number of DBPROPSET structures passed in the pPropSet argument.
A standard HRESULT.
The first three forms of Open
take a session, create a command, and execute the command, binding any parameters as necessary.
The first form of Open
takes a Unicode command string and has no default value.
The second form of Open
takes an ANSI command string and no default value (provided for backward compatibility with existing ANSI applications).
The third form of Open
allows the command string to be NULL, because of type int
with a default value of NULL. It is provided for calling Open(session, NULL);
or Open(session);
because NULL is of type int
. This version requires and asserts that the int
parameter be NULL.
Use the fourth form of Open
when you have already created a command and you want to perform a single Prepare and multiple executions.
Note
Open
calls Execute
, which in turn calls GetNextResult
.
Calls CCommand::CreateCommand to create a command for the specified session, then calls ICommandText::SetCommandText to specify the command text.
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 ();
session
[in] A session on which to create the command.
wszCommand
[in] A pointer to the Unicode text of the command string.
szCommand
[in] A pointer to the ANSI text of the command string.
guidCommand
[in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. For a description of dialects, see ICommandText::GetCommandText in the OLE DB Programmer's Reference.
A standard HRESULT.
The first form of Create
takes a Unicode command string. The second form of Create
takes an ANSI command string (provided for backward compatibility with existing ANSI applications).
Creates a new command.
HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();
session
[in] A CSession
object to be associated with the new command.
A standard HRESULT.
This method creates a command using the specified session object.
Gets a list of the command's parameters, their names, and their types.
HRESULT CCommandBase::GetParameterInfo(DB_UPARAMS* pParams,
DBPARAMINFO** ppParamInfo,
OLECHAR** ppNamesBuffer) throw ();
See ICommandWithParameters::GetParameterInfo in the OLE DB Programmer's Reference.
A standard HRESULT.
Validates and optimizes the current command.
HRESULT CCommandBase::Prepare(ULONG cExpectedRuns = 0) throw();
cExpectedRuns
[in] The number of times you expect to execute the command.
A standard HRESULT.
This method wraps the OLE DB method ICommandPrepare::Prepare.
Releases the parameter accessor, then releases the command itself.
void CCommandBase::ReleaseCommand() throw();
ReleaseCommand
is used in conjunction with Close
. See Close for usage details.
Specifies the native type of each command parameter.
HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
const DBORDINAL* pOrdinals,
const DBPARAMBINDINFO* pParamInfo) throw();
See ICommandWithParameters::SetParameterInfo in the OLE DB Programmer's Reference.
A standard HRESULT.
Discards the current command execution plan.
HRESULT CCommandBase::Unprepare() throw();
A standard HRESULT.
This method wraps the OLE DB method ICommandPrepare::Unprepare.
OLE DB Consumer Templates
OLE DB Consumer Templates Reference