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