CCommand-Klasse

  • Artikel

Stellt Methoden zum Festlegen und Ausführen eines Befehls bereit.

Syntax

template <class TAccessor = CNoAccessor,
   template <typename T> class TRowset = CRowset,
   class TMultiple = CNoMultipleResults>
class CCommand :
   public CAccessorRowset <TAccessor, TRowset>,
   public CCommandBase,
   public TMultiple

Parameter

TAccessor
Der Typ der Accessorklasse (z CDynamicParameterAccessor. B. , CDynamicStringAccessoroder CEnumeratorAccessor), die der Befehl verwenden soll. Der Standardwert ist CNoAccessor, der angibt, dass die Klasse parameter oder Ausgabespalten nicht unterstützt.

TRowset
Der Typ der Rowset-Klasse (z CArrayRowset . B. oder CNoRowset), die der Befehl verwenden soll. Der Standardwert ist CRowset.

TMultiple
Wenn Sie einen OLE DB-Befehl verwenden möchten, der mehrere Ergebnisse zurückgeben kann, geben Sie CMultipleResults an. Verwenden Sie andernfalls CNoMultipleResults. Weitere Informationen finden Sie unter "IMultipleResults".

Anforderungen

Header: atldbcli.h

Member

Methoden

Name Beschreibung
Abschließen Schließt den aktuellen Befehl.
GetNextResult Ruft das nächste Ergebnis ab, wenn mehrere Resultsets verwendet werden.
Öffnen Führt den Befehl aus und bindet den Befehl optional.

Geerbte Methoden

Name Beschreibung
Erstellen Erstellt einen neuen Befehl für die angegebene Sitzung und legt dann den Befehlstext fest.
CreateCommand Erstellt einen neuen Befehl.
GetParameterInfo Ruft eine Liste der Parameter des Befehls, deren Namen und deren Typen ab.
Vorbereiten Überprüft und optimiert den aktuellen Befehl.
ReleaseCommand Gibt den Parameteraccessor bei Bedarf frei, und gibt dann den Befehl frei.
SetParameterInfo Gibt den systemeigenen Typ der einzelnen Befehlsparameter an.
Nicht vorbereitet Verwirft den aktuellen Befehlsausführungsplan.

Hinweise

Verwenden Sie diese Klasse, wenn Sie einen parameterbasierten Vorgang ausführen oder einen Befehl ausführen müssen. Wenn Sie lediglich ein einfaches Rowset öffnen müssen, verwenden Sie stattdessen CTable .

Die verwendete Accessorklasse bestimmt die Methode der Bindungsparameter und -daten.

Beachten Sie, dass Sie gespeicherte Prozeduren nicht mit dem OLE DB-Anbieter für Jet verwenden können, da dieser Anbieter gespeicherte Prozeduren nicht unterstützt (nur Konstanten sind in Abfragezeichenfolgen zulässig).

CCommand::Close

Gibt das dem Befehl zugeordnete Accessor-Rowset frei.

Syntax

void Close();

Hinweise

Ein Befehl verwendet ein Rowset, einen Resultset-Accessor und (optional) einen Parameteraccessor (im Gegensatz zu Tabellen, die Parameter nicht unterstützen und keinen Parameteraccessor benötigen).

Wenn Sie einen Befehl ausführen, sollten Sie beide Close und ReleaseCommand nach dem Befehl aufrufen.

Wenn Sie denselben Befehl wiederholt ausführen möchten, sollten Sie jeden Resultset-Accessor freigeben, indem Sie vor dem Aufrufen aufrufen Close Execute. Am Ende der Datenreihe sollten Sie den Parameteraccessor durch Aufrufen ReleaseCommandfreigeben. Ein weiteres gängiges Szenario ist das Aufrufen einer gespeicherten Prozedur mit Ausgabeparametern. Auf vielen Anbietern (z. B. dem OLE DB-Anbieter für SQL Server) kann erst auf die Ausgabeparameterwerte zugegriffen werden, wenn Sie den Resultset-Accessor schließen. Rufen Sie Close auf, um das zurückgegebene Rowset und den Resultset-Accessor zu schließen, aber nicht den Parameteraccessor, sodass Sie die Ausgabeparameterwerte abrufen können.

Beispiel

Das folgende Beispiel zeigt, wie Sie Close und ReleaseCommand aufrufen, wenn Sie wiederholt den gleichen Befehl ausführen.

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

Ruft das nächste Resultset ab, wenn eins verfügbar ist.

Syntax

HRESULT GetNextResult(DBROWCOUNT* pulRowsAffected,
   bool bBind = true) throw();

Parameter

Betroffene pulRows
[in/out] Ein Zeiger auf den Arbeitsspeicher, in dem die Anzahl von Zeilen zurückgegeben wird, die von einem Befehl betroffen sind.

bBind
[in] Gibt an, ob der Befehl nach der Ausführung automatisch gebunden werden soll. Der Standardwert ist true, was bewirkt, dass der Befehl automatisch gebunden wird. Durch Festlegen von "bBind " wird false die automatische Bindung des Befehls verhindert, sodass Sie manuell binden können. (Manuelle Bindung ist für OLAP-Benutzer von besonderem Interesse.)

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Wenn zuvor ein Resultset abgerufen wurde, gibt diese Funktion den vorherigen Resultset frei und bindet die Spalten. Wenn bBind lautet true, bindet sie die neuen Spalten.

Sie sollten diese Funktion nur aufrufen, wenn Sie mehrere Ergebnisse angegeben haben, indem Sie den CCommand Vorlagenparameter TMultiple=CMultipleResults festlegen.

CCommand::Open

Führt den Befehl aus und bindet den Befehl optional.

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

Parameter

Sitzungskonsistenz
[in] Die Sitzung, in der der Befehl ausgeführt werden soll.

wszCommand
[in] Der auszuführende Befehl, der als Unicode-Zeichenfolge übergeben wird. Kann bei Verwendung CAccessorNULL sein, in diesem Fall wird der Befehl aus dem wert abgerufen, der an das DEFINE_COMMAND Makro übergeben wird. Weitere Informationen finden Sie unter "ICommand::Execute " in der OLE DB-Programmierreferenz .

szCommand
[in] Identisch mit wszCommand , außer dass dieser Parameter eine ANSI-Befehlszeichenfolge verwendet. Die vierte Form dieser Methode kann einen NULL-Wert annehmen. Ausführliche Informationen finden Sie weiter unten in diesem Thema unter "Hinweise".

pPropSet
[in] Ein Zeiger auf ein Array von DBPROPSET-Strukturen , die Eigenschaften und Werte enthalten, die festgelegt werden sollen. Siehe Eigenschaftensätze und Eigenschaftengruppen in der OLE DB-Programmierreferenz im Windows SDK.

pRowsAffected
[in/out] Ein Zeiger auf den Arbeitsspeicher, in dem die Anzahl von Zeilen zurückgegeben wird, die von einem Befehl betroffen sind. Wenn *pRowsAffected NULL ist, wird keine Zeilenanzahl zurückgegeben. Open Andernfalls wird *pRowsAffected entsprechend den folgenden Bedingungen festgelegt:

Wenn Then
Das cParamSets Element von pParams ist größer als 1 *pRowsAffected stellt die Gesamtanzahl der Zeilen dar, die von allen in der Ausführung angegebenen Parametersätzen betroffen sind.
Die Anzahl der betroffenen Zeilen ist nicht verfügbar. *pRowsAffected ist auf -1 festgelegt.
Der Befehl aktualisiert, löscht oder fügt keine Zeilen ein. *pRowsAffected ist nicht definiert.

guidCommand
[in] Eine GUID, die die Syntax und allgemeine Regeln für den Anbieter angibt, die beim Analysieren des Befehlstexts verwendet werden sollen. Weitere Informationen finden Sie unter "ICommandText::GetCommandText " und "ICommandText::SetCommandText " in der OLE DB-Programmierreferenz .

bBind
[in] Gibt an, ob der Befehl nach der Ausführung automatisch gebunden werden soll. Der Standardwert ist true, was bewirkt, dass der Befehl automatisch gebunden wird. Durch Festlegen von "bBind " wird false die automatische Bindung des Befehls verhindert, sodass Sie manuell binden können. (Manuelle Bindung ist für OLAP-Benutzer von besonderem Interesse.)

ulPropSets
[in] Die Anzahl der im pPropSet-Argument übergebenen DBPROPSET-Strukturen.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Die ersten drei Formen der Open Sitzung erstellen, einen Befehl erstellen und den Befehl ausführen, um alle Parameter nach Bedarf zu binden.

Die erste Form einer Open Unicode-Befehlszeichenfolge und hat keinen Standardwert.

Die zweite Form von Open akzeptiert eine ANSI-Befehlszeichenfolge und keinen Standardwert (aus Gründen der Abwärtskompatibilität mit vorhandenen ANSI-Anwendungen).

Mit der dritten Form Open kann die Befehlszeichenfolge NULL sein, da der Typ int einen Standardwert von NULL aufweist. Es wird zum Aufrufen Open(session, NULL); bereitgestellt oder Open(session); weil NULL vom Typ intist. Diese Version erfordert und bestätigt, dass der int Parameter NULL ist.

Verwenden Sie die vierte Form, Open wenn Sie bereits einen Befehl erstellt haben und eine einzelne Vorbereitung und mehrere Ausführungen ausführen möchten.

Hinweis

Open Aufrufe Execute, die wiederum Anrufe GetNextResult.

CCommand::Create

Ruft CCommand::CreateCommand auf, um einen Befehl für die angegebene Sitzung zu erstellen, und ruft dann ICommandText::SetCommandText auf, um den Befehlstext anzugeben.

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

Parameter

Sitzungskonsistenz
[in] Eine Sitzung, in der der Befehl erstellt werden soll.

wszCommand
[in] Ein Zeiger auf den Unicode-Text der Befehlszeichenfolge.

szCommand
[in] Ein Zeiger auf den ANSI-Text der Befehlszeichenfolge.

guidCommand
[in] Eine GUID, die die Syntax und allgemeine Regeln für den Anbieter angibt, die beim Analysieren des Befehlstexts verwendet werden sollen. Eine Beschreibung der Dialekte finden Sie unter "ICommandText::GetCommandText " in der OLE DB-Programmierreferenz.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Die erste Form der Zeichenfolge für Create Unicode-Befehle. Die zweite Form der Create AnSI-Befehlszeichenfolge (die aus Gründen der Abwärtskompatibilität mit vorhandenen ANSI-Anwendungen bereitgestellt wird).

CCommand::CreateCommand

Erstellt einen neuen Befehl.

Syntax

HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();

Parameter

Sitzungskonsistenz
[in] Ein CSession Objekt, das dem neuen Befehl zugeordnet werden soll.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode erstellt einen Befehl mithilfe des angegebenen Sitzungsobjekts.

CCommand::GetParameterInfo

Ruft eine Liste der Parameter des Befehls, deren Namen und deren Typen ab.

Syntax

HRESULT CCommandBase::GetParameterInfo(DB_UPARAMS* pParams,
   DBPARAMINFO** ppParamInfo,
   OLECHAR** ppNamesBuffer) throw ();

Parameter

Siehe "ICommandWithParameters::GetParameterInfo " in der OLE DB-Programmierreferenz.

Rückgabewert

Ein Standard-HRESULT.

CCommand::Prepare

Überprüft und optimiert den aktuellen Befehl.

Syntax

HRESULT CCommandBase::Prepare(ULONG cExpectedRuns = 0) throw();

Parameter

cExpectedRuns
[in] Die Häufigkeit, mit der Sie den Befehl ausführen möchten.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode umschließt die OLE DB-Methode ICommandPrepare::P repare.

CCommand::ReleaseCommand

Gibt den Parameteraccessor frei und gibt dann den Befehl selbst frei.

Syntax

void CCommandBase::ReleaseCommand() throw();

Hinweise

ReleaseCommand wird in Verbindung mit Close. Weitere Informationen finden Sie unter "Schließen ".

CCommand::SetParameterInfo

Gibt den systemeigenen Typ der einzelnen Befehlsparameter an.

Syntax

HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
   const DBORDINAL* pOrdinals,
   const DBPARAMBINDINFO* pParamInfo) throw();

Parameter

Siehe "ICommandWithParameters::SetParameterInfo " in der OLE DB-Programmierreferenz.

Rückgabewert

Ein Standard-HRESULT.

CCommand::Unprepare

Verwirft den aktuellen Befehlsausführungsplan.

Syntax

HRESULT CCommandBase::Unprepare() throw();

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode umschließt die OLE DB-Methode ICommandPrepare::Unprepare.

Siehe auch

OLE DB-Consumervorlagen
Referenz der OLE DB-Consumervorlagen