Udostępnij za pośrednictwem

Klasa CCommand

  • Artykuł

Udostępnia metody ustawiania i wykonywania polecenia.

Składnia

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

Parametry

Funkcja TAccessor
Typ klasy dostępu (np CDynamicParameterAccessor. , CDynamicStringAccessorlub CEnumeratorAccessor), który ma być używany przez polecenie . Wartość domyślna to CNoAccessor, która określa, że klasa nie obsługuje parametrów ani kolumn wyjściowych.

TRowset
Typ klasy zestawu wierszy (np CArrayRowset . lub CNoRowset), której chcesz użyć polecenia. Wartość domyślna to CRowset.

TMultiple
Aby użyć polecenia OLE DB, które może zwrócić wiele wyników, określ CMultipleResults. W przeciwnym razie użyj CNoMultipleResults. Aby uzyskać szczegółowe informacje, zobacz IMultipleResults.

Wymagania

Nagłówek: atldbcli.h

Elementy członkowskie

Metody

Nazwa/nazwisko opis
Zamknij Zamyka bieżące polecenie.
GetNextResult Pobiera następny wynik podczas korzystania z wielu zestawów wyników.
Otwórz Wykonuje polecenie i opcjonalnie wiąże polecenie.

Metody dziedziczone

Nazwa/nazwisko opis
Utworzenie Tworzy nowe polecenie dla określonej sesji, a następnie ustawia tekst polecenia.
Utwórzpolecenia Tworzy nowe polecenie.
GetParameterInfo Pobiera listę parametrów polecenia, ich nazwy i typy.
Przygotowywanie Weryfikuje i optymalizuje bieżące polecenie.
ReleaseCommand Zwalnia metodę dostępu parametru w razie potrzeby, a następnie zwalnia polecenie.
SetParameterInfo Określa natywny typ każdego parametru polecenia.
Nieprzygotuj Odrzuca bieżący plan wykonywania polecenia.

Uwagi

Użyj tej klasy, gdy musisz wykonać operację opartą na parametrach lub wykonać polecenie. Jeśli wystarczy otworzyć prosty zestaw wierszy, zamiast tego użyj tabeli CTable .

Używana klasa dostępu określa metodę powiązania parametrów i danych.

Należy pamiętać, że nie można używać procedur składowanych z dostawcą OLE DB dla jet, ponieważ ten dostawca nie obsługuje procedur składowanych (tylko stałe są dozwolone w ciągach zapytania).

CCommand::Close

Zwalnia zestaw wierszy dostępu skojarzony z poleceniem .

Składnia

void Close();

Uwagi

Polecenie używa zestawu wierszy, metody dostępu zestawu wyników i (opcjonalnie) metody dostępu parametrów (w przeciwieństwie do tabel, które nie obsługują parametrów i nie wymagają dostępu do parametrów).

Po wykonaniu polecenia należy wywołać zarówno Close polecenie ReleaseCommand, jak i releaseCommand .

Jeśli chcesz wielokrotnie wykonywać to samo polecenie, należy zwolnić każdą metodę dostępu zestawu wyników, wywołując metodę przed wywołaniem Close metody Execute. Na końcu serii należy zwolnić metodę dostępu parametru, wywołując metodę ReleaseCommand. Innym typowym scenariuszem jest wywołanie procedury składowanej, która ma parametry wyjściowe. W przypadku wielu dostawców (takich jak dostawca OLE DB dla programu SQL Server) wartości parametrów wyjściowych nie będą dostępne, dopóki nie zamkniesz dostępu do zestawu wyników. Wywołaj metodę Close , aby zamknąć zwrócony zestaw wierszy i metodę dostępu zestawu wyników, ale nie metodę dostępu do parametrów, umożliwiając w ten sposób pobieranie wartości parametrów wyjściowych.

Przykład

W poniższym przykładzie pokazano, jak można wywołać Close polecenie i ReleaseCommand po wielokrotnym wykonaniu tego samego polecenia.

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

Pobiera następny zestaw wyników, jeśli jest dostępny.

Składnia

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

Parametry

pulRowsAffected
[in/out] Wskaźnik do pamięci, w którym zwracana jest liczba wierszy, których dotyczy polecenie.

bBind
[in] Określa, czy po wykonaniu polecenia ma zostać automatycznie powiązane. Wartość domyślna to true, co powoduje automatyczne wiązanie polecenia. Ustawienie elementu bBind uniemożliwia false automatyczne powiązanie polecenia, aby można było powiązać je ręcznie. (Powiązanie ręczne jest szczególnie interesujące dla użytkowników OLAP).

Wartość zwracana

Standardowy HRESULT.

Uwagi

Jeśli zestaw wyników został wcześniej pobrany, ta funkcja zwalnia poprzedni zestaw wyników i usuwa powiązanie kolumn. Jeśli parametr bBind ma wartość true, wiąże nowe kolumny.

Tę funkcję należy wywołać tylko wtedy, gdy określono wiele wyników, ustawiając parametr szablonu CCommand TMultipleCMultipleResults=.

CCommand::Open

Wykonuje polecenie i opcjonalnie wiąże polecenie.

Składnia

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

Parametry

sesja
[in] Sesja, w której ma zostać wykonane polecenie.

wszCommand
[in] Polecenie do wykonania, przekazane jako ciąg Unicode. Może mieć wartość NULL w przypadku użycia polecenia CAccessor, w którym przypadku polecenie zostanie pobrane z wartości przekazanej do makra DEFINE_COMMAND . Aby uzyskać szczegółowe informacje, zobacz ICommand::Execute w dokumentacji programisty OLE DB.

szCommand
[in] Tak samo jak wszCommand z tą różnicą, że ten parametr przyjmuje ciąg polecenia ANSI. Czwarta forma tej metody może przyjmować wartość NULL. Aby uzyskać szczegółowe informacje, zobacz "Uwagi" w dalszej części tego tematu.

pPropSet
[in] Wskaźnik do tablicy struktur DBPROPSET zawierających właściwości i wartości do ustawienia. Zobacz Zestawy właściwości i grupy właściwości w dokumentacji programisty OLE DB w zestawie Windows SDK.

PRowsAffected
[in/out] Wskaźnik do pamięci, w którym zwracana jest liczba wierszy, których dotyczy polecenie. Jeśli wartość *pRowsAffected ma wartość NULL, liczba wierszy nie jest zwracana. Open W przeciwnym razie ustawia wartość *pRowsAffected zgodnie z następującymi warunkami:

If Następnie
Element cParamSets elementu pParams jest większy niż 1 *pRowsAffected reprezentuje łączną liczbę wierszy, na które mają wpływ wszystkie zestawy parametrów określone w wykonaniu.
Liczba wierszy, których dotyczy problem, jest niedostępna *PRowsAffected ma wartość -1.
Polecenie nie aktualizuje, usuwa ani wstawia wierszy *Wpływ pRows jest niezdefiniowany.

guidCommand
[in] Identyfikator GUID określający składnię i ogólne reguły dla dostawcy do użycia w analizowaniu tekstu polecenia. Aby uzyskać szczegółowe informacje, zobacz ICommandText::GetCommandText i ICommandText::SetCommandText w dokumentacji programisty OLE DB.

bBind
[in] Określa, czy po wykonaniu polecenia ma zostać automatycznie powiązane. Wartość domyślna to true, co powoduje automatyczne wiązanie polecenia. Ustawienie elementu bBind uniemożliwia false automatyczne powiązanie polecenia, aby można było powiązać je ręcznie. (Powiązanie ręczne jest szczególnie interesujące dla użytkowników OLAP).

ulPropSets
[in] Liczba struktur DBPROPSET przekazanych w argumencie pPropSet .

Wartość zwracana

Standardowy HRESULT.

Uwagi

Pierwsze trzy formularze wykonywania sesji, tworzenia polecenia i wykonywania polecenia, wiązania dowolnych Open parametrów w razie potrzeby.

Pierwsza forma Open przyjmuje ciąg polecenia Unicode i nie ma wartości domyślnej.

Druga forma Open przyjmuje ciąg polecenia ANSI i nie ma wartości domyślnej (podanej w celu zapewnienia zgodności z poprzednimi wersjami z istniejącymi aplikacjami ANSI).

Trzecia forma polecenia Open umożliwia ciągowi polecenia wartość NULL ze względu na typ int z wartością domyślną null. Jest on udostępniany do wywoływania Open(session, NULL); lub Open(session); , ponieważ wartość NULL jest typu int. Ta wersja wymaga i potwierdza, że int parametr ma wartość NULL.

Użyj czwartej Open formy polecenia , jeśli utworzono już polecenie i chcesz wykonać pojedyncze wykonanie i wiele wykonań.

Uwaga

Open wywołuje metodę Execute, która z kolei wywołuje metodę GetNextResult.

CCommand::Create

Wywołuje polecenie CCommand::CreateCommand , aby utworzyć polecenie dla określonej sesji, a następnie wywołuje metodę ICommandText::SetCommandText , aby określić tekst polecenia.

Składnia

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

Parametry

sesja
[in] Sesja, na której ma zostać utworzone polecenie .

wszCommand
[in] Wskaźnik do tekstu Unicode ciągu polecenia.

szCommand
[in] Wskaźnik do tekstu ANSI ciągu polecenia.

guidCommand
[in] Identyfikator GUID określający składnię i ogólne reguły dla dostawcy do użycia w analizowaniu tekstu polecenia. Aby uzyskać opis dialektów, zobacz ICommandText::GetCommandText w dokumentacji programisty OLE DB.

Wartość zwracana

Standardowy HRESULT.

Uwagi

Pierwsza forma Create przyjmuje ciąg polecenia Unicode. Druga forma Create przyjmuje ciąg polecenia ANSI (zapewnia zgodność z poprzednimi wersjami z istniejącymi aplikacjami ANSI).

CCommand::CreateCommand

Tworzy nowe polecenie.

Składnia

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

Parametry

sesja
[in] Obiekt CSession , który ma być skojarzony z nowym poleceniem.

Wartość zwracana

Standardowy HRESULT.

Uwagi

Ta metoda tworzy polecenie przy użyciu określonego obiektu sesji.

CCommand::GetParameterInfo

Pobiera listę parametrów polecenia, ich nazwy i typy.

Składnia

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

Parametry

Zobacz ICommandWithParameters::GetParameterInfo w dokumentacji programisty OLE DB.

Wartość zwracana

Standardowy HRESULT.

CCommand::Prepare

Weryfikuje i optymalizuje bieżące polecenie.

Składnia

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

Parametry

cExpectedRuns
[in] Liczba oczekiwanych wykonań polecenia.

Wartość zwracana

Standardowy HRESULT.

Uwagi

Ta metoda opakowuje metodę OLE DB ICommandPrepare::P repare.

CCommand::ReleaseCommand

Zwalnia metodę dostępu parametru, a następnie zwalnia samo polecenie.

Składnia

void CCommandBase::ReleaseCommand() throw();

Uwagi

ReleaseCommand jest używany w połączeniu z Close. Aby uzyskać szczegółowe informacje o użyciu, zobacz Zamknij .

CCommand::SetParameterInfo

Określa natywny typ każdego parametru polecenia.

Składnia

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

Parametry

Zobacz ICommandWithParameters::SetParameterInfo w dokumentacji programisty OLE DB.

Wartość zwracana

Standardowy HRESULT.

CCommand::Unprepare

Odrzuca bieżący plan wykonywania polecenia.

Składnia

HRESULT CCommandBase::Unprepare() throw();

Wartość zwracana

Standardowy HRESULT.

Uwagi

Ta metoda opakowuje metodę OLE DB ICommandPrepare::Unprepare.

Zobacz też

Szablony konsumentów OLE DB
Szablony konsumentów OLE DB — dokumentacja