Sdílet prostřednictvím

CCommand – třída

  • Článek

Poskytuje metody pro nastavení a spuštění příkazu.

Syntaxe

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

Parametry

TAccessor
Typ třídy přístupového objektu (například CDynamicParameterAccessor, CDynamicStringAccessornebo CEnumeratorAccessor), který má příkaz použít. Výchozí hodnota je CNoAccessor, která určuje, že třída nepodporuje parametry nebo výstupní sloupce.

TRowset
Typ třídy sady řádků (například CArrayRowset nebo CNoRowset), který má příkaz použít. Výchozí hodnota je CRowset.

TMultiple
Chcete-li použít příkaz OLE DB, který může vrátit více výsledků, zadejte CMultipleResults. V opačném případě použijte CNoMultipleResults. Podrobnosti najdete v tématu IMultipleResults.

Požadavky

Hlavička: atldbcli.h

Členové

Metody

Název Popis
Zavřít Zavře aktuální příkaz.
GetNextResult Načte další výsledek při použití více sad výsledků.
Otevřená Spustí a volitelně vytvoří vazbu příkazu.

Zděděné metody

Název Popis
Vytvořit Vytvoří nový příkaz pro zadanou relaci a pak nastaví text příkazu.
CreateCommand Vytvoří nový příkaz.
GetParameterInfo Získá seznam parametrů příkazu, jejich názvů a jejich typů.
Příprava Ověří a optimalizuje aktuální příkaz.
ReleaseCommand V případě potřeby uvolní přístupový objekt parametru a příkaz uvolní.
SetParameterInfo Určuje nativní typ každého parametru příkazu.
Zrušit přípravu Zahodí aktuální plán provádění příkazů.

Poznámky

Tuto třídu použijte, když potřebujete provést operaci založenou na parametrech nebo provést příkaz. Pokud potřebujete jenom otevřít jednoduchou sadu řádků, použijte místo toho tabulku CTable .

Třída příslušenství, kterou používáte, určuje metodu parametrů vazby a dat.

Všimněte si, že nelze použít uložené procedury s zprostředkovatelem OLE DB pro Jet, protože tento zprostředkovatel nepodporuje uložené procedury (v řetězcích dotazu jsou povoleny pouze konstanty).

CCommand::Close

Uvolní sadu řádků přístupového objektu přidruženou k příkazu.

Syntaxe

void Close();

Poznámky

Příkaz používá sadu řádků, přístupové objekty sady výsledků a (volitelně) přístupové objekty parametrů (na rozdíl od tabulek, které nepodporují parametry a nepotřebují přístup k parametrům).

Při spuštění příkazu byste měli za příkazem volat příkaz Close ReleaseCommand.

Pokud chcete spustit stejný příkaz opakovaně, měli byste uvolnit každý přístup sady výsledků voláním Close před voláním Execute. Na konci řady byste měli uvolnit přístupové objekty parametrů voláním ReleaseCommand. Dalším běžným scénářem je volání uložené procedury s výstupními parametry. U mnoha zprostředkovatelů (například zprostředkovatele OLE DB pro SQL Server) nebudou hodnoty výstupních parametrů přístupné, dokud nezavřete přístup k přístupové sadě výsledků. Volání Close pro zavření vrácené sady řádků a přístupového objektu sady výsledků, ale ne přístupového objektu parametru, takže můžete načíst hodnoty výstupních parametrů.

Příklad

Následující příklad ukazuje, jak můžete volat Close a ReleaseCommand při opakovaném spuštění stejného příkazu.

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

Načte další sadu výsledků, pokud je k dispozici.

Syntaxe

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

Parametry

pulRowsAffected
[in/out] Ukazatel na paměť, kde je vrácen počet řádků ovlivněných příkazem.

bBind
[v] Určuje, jestli se má příkaz po spuštění automaticky svázat. Výchozí hodnota je true, což způsobí, že příkaz bude automaticky vázán. Nastavením bBind false zabráníte automatické vazbě příkazu, abyste mohli vytvořit vazbu ručně. (Ruční vazba je pro uživatele OLAP obzvláště zajímavá.)

Návratová hodnota

Standardní HODNOTA HRESULT.

Poznámky

Pokud byla sada výsledků dříve načtena, uvolní tato funkce předchozí sadu výsledků a zruší vazby sloupců. Pokud je truebBind , vytvoří vazbu nových sloupců.

Tuto funkci byste měli volat pouze v případě, že jste zadali více výsledků nastavením parametru CCommand šablony TMultiple=CMultipleResults.

CCommand::Open

Spustí a volitelně vytvoří vazbu příkazu.

Syntaxe

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

sezení
[v] Relace, ve které se má příkaz spustit.

wszCommand
[v] Příkaz, který se má provést, předaný jako řetězec Unicode. Při použití CAccessormůže být NULL , v takovém případě se příkaz načte z hodnoty předané do DEFINE_COMMAND makra. Podrobnosti najdete v tématu ICommand::Execute v referenčních informacích programátora OLE DB.

szCommand
[v] Stejné jako wszCommand s tím rozdílem, že tento parametr přebírá řetězec příkazu ANSI. Čtvrtá forma této metody může mít hodnotu NULL. Podrobnosti najdete v části Poznámky dále v tomto tématu.

pPropSet
[v] Ukazatel na pole struktur DBPROPSET obsahující vlastnosti a hodnoty, které se mají nastavit. Viz Sady vlastností a skupiny vlastností v odkazech programátorů OLE DB v sadě Windows SDK.

pRowsAffected
[in/out] Ukazatel na paměť, kde je vrácen počet řádků ovlivněných příkazem. Pokud je hodnota *pRowsAffected NULL, nevrátí se žádný počet řádků. Open V opačném případě nastaví *pRowsAffected podle následujících podmínek:

Pokud Pak...
Prvek cParamSets pParams je větší než 1. *pRowsAffected představuje celkový počet řádků ovlivněných všemi sadami parametrů zadanými při provádění.
Počet ovlivněných řádků není k dispozici. *pRowsAffected je nastaven na -1.
Příkaz neaktualizuje, odstraní nebo vloží řádky. *PRowsAffected je nedefinovaný.

GuidCommand
[v] Identifikátor GUID, který určuje syntaxi a obecná pravidla pro zprostředkovatele, která se mají použít při analýze textu příkazu. Podrobnosti naleznete v části ICommandText::GetCommandText a ICommandText::SetCommandText v referenčních informacích programátora OLE DB.

bBind
[v] Určuje, jestli se má příkaz po spuštění automaticky svázat. Výchozí hodnota je true, což způsobí, že příkaz bude automaticky vázán. Nastavením bBind false zabráníte automatické vazbě příkazu, abyste mohli vytvořit vazbu ručně. (Ruční vazba je pro uživatele OLAP obzvláště zajímavá.)

UlPropSets
[v] Počet struktur DBPROPSET předaných v argumentu pPropSet .

Návratová hodnota

Standardní HODNOTA HRESULT.

Poznámky

První tři formy Open převzetí relace, vytvoření příkazu a spuštění příkazu, vytvoření vazby libovolných parametrů podle potřeby.

První forma Open přebírá řetězec příkazu Unicode a nemá žádnou výchozí hodnotu.

Druhá forma Open přebírá řetězec příkazu ANSI a nemá výchozí hodnotu (za předpokladu zpětné kompatibility s existujícími aplikacemi ANSI).

Třetí forma Open umožňuje, aby byl řetězec příkazu NULL, protože typ int s výchozí hodnotou NULL. Je poskytována pro volání Open(session, NULL); nebo Open(session); protože NULL je typu int. Tato verze vyžaduje a potvrzuje, že int parametr má hodnotu NULL.

Použijte čtvrtou formu Open , kdy jste již vytvořili příkaz a chcete provést jednu přípravu a více spuštění.

Poznámka:

Open volání Execute, která následně volá GetNextResult.

CCommand::Create

Volá CCommand::CreateCommand k vytvoření příkazu pro zadanou relaci a potom volá ICommandText::SetCommandText k určení textu příkazu.

Syntaxe

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

sezení
[v] Relace, na které se má příkaz vytvořit.

wszCommand
[v] Ukazatel na text Unicode řetězce příkazu.

szCommand
[v] Ukazatel na text ANSI příkazového řetězce.

GuidCommand
[v] Identifikátor GUID, který určuje syntaxi a obecná pravidla pro zprostředkovatele, která se mají použít při analýze textu příkazu. Popis dialektů naleznete v části ICommandText::GetCommandText v odkazech programátora OLE DB.

Návratová hodnota

Standardní HODNOTA HRESULT.

Poznámky

První forma Create přebírá řetězec příkazu Unicode. Druhá forma Create přebírá řetězec příkazu ANSI (poskytuje zpětnou kompatibilitu s existujícími aplikacemi ANSI).

CCommand::CreateCommand

Vytvoří nový příkaz.

Syntaxe

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

Parametry

sezení
[v] Objekt CSession , který se má přidružit k novému příkazu.

Návratová hodnota

Standardní HODNOTA HRESULT.

Poznámky

Tato metoda vytvoří příkaz pomocí zadaného objektu relace.

CCommand::GetParameterInfo

Získá seznam parametrů příkazu, jejich názvů a jejich typů.

Syntaxe

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

Parametry

Viz ICommandWithParameters::GetParameterInfo v referenční dokumentaci programátora OLE DB.

Návratová hodnota

Standardní HODNOTA HRESULT.

CCommand::Prepare

Ověří a optimalizuje aktuální příkaz.

Syntaxe

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

Parametry

cExpectedRuns
[v] Kolikrát očekáváte, že se má příkaz spustit.

Návratová hodnota

Standardní HODNOTA HRESULT.

Poznámky

Tato metoda zabalí metodu OLE DB ICommandPrepare::P repare.

CCommand::ReleaseCommand

Uvolní přístupový objekt parametru a pak uvolní samotný příkaz.

Syntaxe

void CCommandBase::ReleaseCommand() throw();

Poznámky

ReleaseCommand se používá ve spojení s Close. Podrobnosti o využití najdete v části Zavřít .

CCommand::SetParameterInfo

Určuje nativní typ každého parametru příkazu.

Syntaxe

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

Parametry

Viz ICommandWithParameters::SetParameterInfo v referenční dokumentaci programátora OLE DB.

Návratová hodnota

Standardní HODNOTA HRESULT.

CCommand::Unprepare

Zahodí aktuální plán provádění příkazů.

Syntaxe

HRESULT CCommandBase::Unprepare() throw();

Návratová hodnota

Standardní HODNOTA HRESULT.

Poznámky

Tato metoda zabalí metodu OLE DB ICommandPrepare::Unprepare.

Viz také

Šablony příjemců OLE DB
Referenční dokumentace k šablonám příjemců OLE DB