CCommand::Open

  • Article

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

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.

Requirements

Header: atldbcli.h

See Also

Reference

CCommand Class