Classe CCommand

  • Articolo

Fornisce i metodi per impostare ed eseguire un comando.

Sintassi

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

Parametri

TAccessor
Tipo di classe di funzioni di accesso (ad esempio CDynamicParameterAccessor, CDynamicStringAccessor o CEnumeratorAccessor) che si desidera venga utilizzata dal comando. L'impostazione predefinita è CNoAccessor, che specifica che la classe non supporta parametri o colonne di output.

TRowset
Tipo di classe rowset (ad esempio CArrayRowset o CNoRowset) che si desidera venga utilizzata dal comando. Il valore predefinito è CRowset.

TMultiple
Per usare un comando OLE DB che può restituire più risultati, specificare CMultipleResults. In caso contrario, usare CNoMultipleResults. Per informazioni dettagliate, vedere IMultipleResults.

Requisiti

Intestazione: atldbcli.h

Membri

Metodi

Nome Descrizione
Chiudi Chiude il comando corrente.
GetNextResult Recupera il risultato successivo durante l'utilizzo di più set di risultati.
Si apra Esegue ed eventualmente associa il comando.

Metodi ereditati

Nome Descrizione
Crea Crea un nuovo comando per la sessione specificata, quindi imposta il testo del comando.
CreateCommand Crea un nuovo comando.
GetParameterInfo Ottiene un elenco di parametri, i relativi nomi e tipi del comando.
Preparazione Convalida e ottimizza il comando corrente.
ReleaseCommand Rilascia la funzione di accesso parametro se necessario, quindi rilascia il comando.
SetParameterInfo Specifica il tipo nativo di ogni parametro di comando.
Annullare la preparazione Rimuove il piano di esecuzione corrente dei comandi.

Osservazioni:

Usare questa classe quando è necessario eseguire un'operazione basata su parametri o eseguire un comando. Se è sufficiente aprire un set di righe semplice, usare invece CTable .

La classe di funzioni di accesso che si sta utilizzando determina il metodo di associazione dei parametri e dei dati.

Notare che non è possibile utilizzare le stored procedure con il provider OLE BD per Jet, in quanto da questo non supportate. Nelle stringhe delle query sono infatti ammesse solo costanti.

CCommand::Close

Rilascia il set di righe della funzione di accesso associato al comando .

Sintassi

void Close();

Osservazioni:

Un comando usa un set di righe, una funzione di accesso del set di risultati e (facoltativamente) una funzione di accesso ai parametri (a differenza delle tabelle, che non supportano parametri e non necessitano di una funzione di accesso ai parametri).

Quando si esegue un comando, è necessario chiamare sia Close che ReleaseCommand dopo il comando .

Quando si vuole eseguire ripetutamente lo stesso comando, è necessario rilasciare ogni funzione di accesso del set di risultati chiamando prima di chiamare Close Execute. Alla fine della serie, è necessario rilasciare la funzione di accesso al parametro chiamando ReleaseCommand. Un altro scenario comune consiste nel chiamare una stored procedure con parametri di output. In molti provider ,ad esempio il provider OLE DB per SQL Server, i valori dei parametri di output non saranno accessibili fino a quando non si chiude la funzione di accesso del set di risultati. Chiamare Close per chiudere il set di righe restituito e la funzione di accesso del set di risultati, ma non la funzione di accesso ai parametri, consentendo così di recuperare i valori dei parametri di output.

Esempio

L'esempio seguente mostra come chiamare Close e ReleaseCommand quando si esegue più volte lo stesso comando.

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

Recupera il set di risultati successivo, se disponibile.

Sintassi

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

Parametri

pulRowsAffected
[in/out] Puntatore alla memoria in cui viene restituito il numero di righe interessate da un comando.

bBind
[in] Specifica se associare automaticamente il comando dopo l'esecuzione. Il valore predefinito è true, che fa in modo che il comando venga associato automaticamente. L'impostazione di bBind su false impedisce l'associazione automatica del comando in modo che sia possibile eseguire manualmente l'associazione. L'associazione manuale è di particolare interesse per gli utenti OLAP.

Valore restituito

HRESULT standard.

Osservazioni:

Se un set di risultati è stato recuperato in precedenza, questa funzione rilascia il set di risultati precedente e annulla l'associazione delle colonne. Se bBind è true, associa le nuove colonne.

È consigliabile chiamare questa funzione solo se sono stati specificati più risultati impostando il CCommand parametro modello TMultipleCMultipleResults=.

CCommand::Open

Esegue ed eventualmente associa il comando.

Sintassi

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

Parametri

Sessione
[in] Sessione in cui eseguire il comando.

wszCommand
[in] Comando da eseguire, passato come stringa Unicode. Può essere NULL quando si usa CAccessor, nel qual caso il comando verrà recuperato dal valore passato alla macro DEFINE_COMMAND . Per informazioni dettagliate, vedere ICommand::Execute nella Guida di riferimento per programmatori OLE DB.

szCommand
[in] Uguale a wszCommand , ad eccezione del fatto che questo parametro accetta una stringa di comando ANSI. La quarta forma di questo metodo può accettare un valore NULL. Per informazioni dettagliate, vedere "Osservazioni" più avanti in questo argomento.

pPropSet
[in] Puntatore a una matrice di strutture DBPROPSET contenenti proprietà e valori da impostare. Vedere Set di proprietà e gruppi di proprietà nella guida di riferimento per programmatori OLE DB in Windows SDK.

pRowsAffected
[in/out] Puntatore alla memoria in cui viene restituito il numero di righe interessate da un comando. Se *pRowsAffected è NULL, non viene restituito alcun conteggio delle righe. In caso contrario, Open imposta *pRowsAffected in base alle condizioni seguenti:

If Risultato
L'elemento cParamSets di è maggiore di pParams 1 *pRowsAffected rappresenta il numero totale di righe interessate da tutti i set di parametri specificati nell'esecuzione.
Il numero di righe interessate non è disponibile *pRowsAffected è impostato su -1.
Il comando non aggiorna, elimina o inserisce righe *pRowsAffected non è definito.

guidCommand
[in] GUID che specifica la sintassi e le regole generali da usare per il provider nell'analisi del testo del comando. Per informazioni dettagliate, vedere ICommandText::GetCommandText e ICommandText::SetCommandText nella Guida di riferimento per programmatori OLE DB.

bBind
[in] Specifica se associare automaticamente il comando dopo l'esecuzione. Il valore predefinito è true, che fa in modo che il comando venga associato automaticamente. L'impostazione di bBind su false impedisce l'associazione automatica del comando in modo che sia possibile eseguire manualmente l'associazione. L'associazione manuale è di particolare interesse per gli utenti OLAP.

ulPropSets
[in] Numero di strutture DBPROPSET passate nell'argomento pPropSet .

Valore restituito

HRESULT standard.

Osservazioni:

Le prime tre forme di Open accettare una sessione, creare un comando ed eseguire il comando, associando eventuali parametri in base alle esigenze.

La prima forma di accetta una stringa di Open comando Unicode e non ha alcun valore predefinito.

La seconda forma di accetta una stringa di Open comando ANSI e nessun valore predefinito (fornito per la compatibilità con le versioni precedenti con le applicazioni ANSI esistenti).

La terza forma di consente che la stringa di Open comando sia NULL, a causa del tipo int con un valore predefinito NULL. Viene fornito per chiamare Open(session, NULL); o Open(session); perché NULL è di tipo int. Questa versione richiede e asserisce che il int parametro sia NULL.

Usare la quarta forma di Open quando è già stato creato un comando e si vuole eseguire un'unica operazione di preparazione e più esecuzioni.

Nota

Open chiama Execute, che a sua volta chiama GetNextResult.

CCommand::Create

Chiama CCommand::CreateCommand per creare un comando per la sessione specificata, quindi chiama ICommandText::SetCommandText per specificare il testo del comando.

Sintassi

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

Parametri

Sessione
[in] Sessione in cui creare il comando.

wszCommand
[in] Puntatore al testo Unicode della stringa di comando.

szCommand
[in] Puntatore al testo ANSI della stringa di comando.

guidCommand
[in] GUID che specifica la sintassi e le regole generali da usare per il provider nell'analisi del testo del comando. Per una descrizione dei dialetti, vedere ICommandText::GetCommandText nella guida di riferimento per programmatori OLE DB.

Valore restituito

HRESULT standard.

Osservazioni:

La prima forma di accetta una stringa di Create comando Unicode. La seconda forma di accetta una stringa di Create comando ANSI (fornita per la compatibilità con le versioni precedenti con le applicazioni ANSI esistenti).

CCommand::CreateCommand

Crea un nuovo comando.

Sintassi

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

Parametri

Sessione
[in] Oggetto CSession da associare al nuovo comando.

Valore restituito

HRESULT standard.

Osservazioni:

Questo metodo crea un comando usando l'oggetto sessione specificato.

CCommand::GetParameterInfo

Ottiene un elenco di parametri, i relativi nomi e tipi del comando.

Sintassi

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

Parametri

Vedere ICommandWithParameters::GetParameterInfo nella guida di riferimento per programmatori OLE DB.

Valore restituito

HRESULT standard.

CCommand::Prepare

Convalida e ottimizza il comando corrente.

Sintassi

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

Parametri

cExpectedRuns
[in] Numero di volte in cui si prevede di eseguire il comando.

Valore restituito

HRESULT standard.

Osservazioni:

Questo metodo esegue il wrapping del metodo OLE DB ICommandPrepare::P repare.

CCommand::ReleaseCommand

Rilascia la funzione di accesso al parametro, quindi rilascia il comando stesso.

Sintassi

void CCommandBase::ReleaseCommand() throw();

Osservazioni:

ReleaseCommand viene usato insieme a Close. Per informazioni dettagliate sull'utilizzo, vedere Chiudi .

CCommand::SetParameterInfo

Specifica il tipo nativo di ogni parametro di comando.

Sintassi

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

Parametri

Vedere ICommandWithParameters::SetParameterInfo nella guida di riferimento per programmatori OLE DB.

Valore restituito

HRESULT standard.

CCommand::Unprepare

Rimuove il piano di esecuzione corrente dei comandi.

Sintassi

HRESULT CCommandBase::Unprepare() throw();

Valore restituito

HRESULT standard.

Osservazioni:

Questo metodo esegue il wrapping del metodo OLE DB ICommandPrepare::Unprepare.

Vedi anche

Modelli di consumer OLE DB
Riferimenti ai modelli consumer OLE DB