Execute Method

See Also      Applies To

Runs an action query or executes an SQL statement on a specified CdbConnection or CdbDatabase object.

Syntax: from a CdbConnection or CdbDatabase object

VOIDExecute(LPCTSTR pstrQuery,

LONG lOptions = -1);

Syntax: from a CdbQueryDef object

VOIDExecute(LONG lOptions = -1);

Parameters

Settings

You can use the following constants for IOptions.

Note The constants dbConsistent and dbInconsistent are mutually exclusive. You can use one or the other, but not both in a given instance of OpenRecordset. Using both dbConsistent and dbInconsistent causes an error.

Remarks

The Execute method is valid only for action queries. If you use Execute with another type of query, an error occurs. Because an action query doesn't return any records, Execute doesn't return a CdbRecordset. (Executing an SQL pass-through query in an ODBCDirect workspace will not return an error if a CdbRecordset isn't returned.)

Use the RecordsAffected property of the CdbConnection, CdbDatabase, or CdbQueryDef object to determine the number of records affected by the most recent Execute method. For example, RecordsAffected contains the number of records deleted, updated, or inserted when executing an action query. When you use the Execute method to run a query, the RecordsAffected property of the CdbQueryDef object is set to the number of records affected.

In a Microsoft Jet workspace, if you provide a syntactically correct SQL statement and have the appropriate permissions, the Execute method won't fail — even if not a single row can be modified or deleted. Therefore, always use the dbFailOnError option when using the Execute method to run an update or delete query. This option generates a run-time error and rolls back all successful changes if any of the records affected are locked and can't be updated or deleted.

For best performance in a Microsoft Jet workspace, especially in a multiuser environment, nest the Execute method inside a transaction. Use the BeginTrans method on the current CdbWorkspace object, then use the Execute method, and complete the transaction by using the CommitTrans method on the CdbWorkspace. This saves changes on disk and frees any locks placed while the query is running.

In an ODBCDirect workspace, if you include the optional dbRunAsync constant, the query runs asynchronously. To determine whether an asynchronous query is still executing, check the value of the StillExecuting property on the object from which the Execute method was called. To terminate execution of an asynchronous Execute method call, use the Cancel method.

Usage: from a CdbDatabase or CdbConnection object

#include <afxole.h>
#include <dbdao.h>

CdbWorkspace      ws;
CdbDatabase      db;
...                  // Initialize ws, db, etc.

ws.BeginTrans();         // Start working.
db.Execute(_T("SELECT * FROM PARTS"),  dbFailOnError);     
                     // Make some changes.
ws.CommitTrans();          // Accept changes.
ws.Close();            // Close the workspace.

Usage: from a CdbQueryDef object

#include <afxole.h>
#include <dbdao.h>

CdbQueryDef       qd;
CdbConnection      conn;
LPCTSTR    lpctsrSQL = 
            _T("SELECT SALARY FROM EMPLOYEES ")
            _T("WHERE LASTNAME = 'SMITH'");
...
qd = conn.CreateQueryDef(_T("SALARYDEF"), lpctsrSQL);
qd.Execute(dbFailOnError);