CCommand 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
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.
Requirements
Header: 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. |
| 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. |
Remarks
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).
CCommand::Close
Releases the accessor rowset associated with the command.
Syntax
void Close();
Remarks
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.
Example
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::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. 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.)
Return Value
A standard HRESULT.
Remarks
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.
CCommand::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. 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.
Return Value
A standard HRESULT.
Remarks
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.
CCommand::Create
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
[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.
Return Value
A standard HRESULT.
Remarks
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).
CCommand::CreateCommand
Creates a new command.
Syntax
HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();
Parameters
session
[in] A CSession object to be associated with the new command.
Return Value
A standard HRESULT.
Remarks
This method creates a command using the specified session object.
CCommand::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
See ICommandWithParameters::GetParameterInfo in the OLE DB Programmer's Reference.
Return Value
A standard HRESULT.
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
A standard HRESULT.
Remarks
This method wraps the OLE DB method ICommandPrepare::Prepare.
CCommand::ReleaseCommand
Releases the parameter accessor, then releases the command itself.
Syntax
void CCommandBase::ReleaseCommand() throw();
Remarks
ReleaseCommand is used in conjunction with Close. See Close for usage details.
CCommand::SetParameterInfo
Specifies the native type of each command parameter.
Syntax
HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
const DBORDINAL* pOrdinals,
const DBPARAMBINDINFO* pParamInfo) throw();
Parameters
See ICommandWithParameters::SetParameterInfo in the OLE DB Programmer's Reference.
Return Value
A standard HRESULT.
CCommand::Unprepare
Discards the current command execution plan.
Syntax
HRESULT CCommandBase::Unprepare() throw();
Return Value
A standard HRESULT.
Remarks
This method wraps the OLE DB method ICommandPrepare::Unprepare.
See also
OLE DB Consumer Templates
OLE DB Consumer Templates Reference
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for