Il wiki della programmazione - ADO - Command

ADO - Command

L'oggetto Command consente l'invio di comandi al database.

I comandi possono essere query, ma non sono limitati a questo: possono essere preparazione di query ed associazioni di parametri con stringhe di query.
Il linguaggio attuale di comando che è supportato è strettamente dipendente dal driver in uso, la maggioranza dei database relazionali che sono supportati utilizzano una qualche variante dello standard SQL92 (vedere la sezione relativa ai dialetti SQL).
L'oggetto Command può sia accedere ad una nuova connessione sia utilizzare una connessione esistente per eseguire le proprie operazioni, dipende da cosa viene specificato nella proprietà ActiveConnection. Se tale proprietà è impostata su una connesione esistente, tale connessione è utilizzata, se tale proprietà è impostata su una stringa di connessione, è usata tale stringa per attivare una nuova connessione.

L'esecuzione di stringhe di query può generare uno o più RecordSet come risposta (SELECT * FROM...), oppure può non ritornare nessun RecordSet (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP).

Una query può essere specificata impostando la proprietà CommandText. Una query può essere un'istruzione SQL standard di manipolazione del database o il richiamo di una Stored Procedure.
Il tipo di query è specificato impostando la proprietà CommandType con una delle apposite costanti.
Quando il comando è un comando SQL, deve essere utilizzato un CommandType adCmdText.
Se è usata adCmdStoredProc, l'oggetto Command esegue la query mediante la sequenza ODBC {call procedure=name}.
Se si specifica adCmdTable, si suppone che la query sia il nome di una tabella; in questo caso la query è convertita in SELECT * FROM per reperirne tutte le righe.
Specificando adCmdUnknown, l'oggetto Command cerca di stabilire il tipo di query inviato, questo potrebbe portare ad un degrado delle prestazioni.

È possibile utilizzare la proprietà Prepared, per effettuare la "preparazione" delle query prima della vera e propria esecuzione. In questo modo prima della esecuzione viene preparato il Piano di Query, questo migliora sensibilmente le prestazini della query se la stessa deve essere eseguita più volte.
La proprietà Prepared diviene utile anche quando si deve eseguire ripetutamente una query con parametri, modificando i valori dei parametri ogni volta. L'oggetto Parameter può essere creato attraverso il metodo CreateParameter.
Questo esempio esegue una semplice SELECT che ritorna un recordset:

Questo esempio esegue una stored procedure che non ritorna un RecordSet.

Il nome della Stored Procedure è "myAdoProc" ed è inserito nella proprietà CommandText.

Proprietà

ActiveConnection

Indica l'oggetto Connection a cui appartiene attualmente l'oggetto Command.

Impostazioni e valori restituiti

Imposta o restituisce un valore String contenente la definizione per una connessione o un oggetto Connection. L'impostazione predefinita è un riferimento all'oggetto Null.

Osservazioni

Utilizzare la proprietà ActiveConnection per determinare l'oggetto Connection tramite il quale l'oggetto Command specificato è eseguito.
Se si cerca di richiamare il metodo Execute in un oggetto Command prima di aver impostato questa proprietà a un oggetto Connection aperto o una stringa di connessione valida, è restituito un errore.

Microsoft Visual Basic

L'impostazione della proprietà ActiveConnection su Nothing implica l'eliminazione dell'associazione tra l'oggetto Command e l'oggetto Connection corrente e il conseguente rilascio da parte del provider di eventuali risorse associate della fonte dati. Successivamente è possibile associare l'oggetto Command allo stesso oggetto Connection o a un altro oggetto. Alcuni provider consentono di modificare l'impostazione della proprietà da un oggetto Connection a un altro senza impostare dapprima la proprietà su Nothing.
Se l'insieme Parameters dell'oggetto Command contiene parametri forniti dal provider e se si imposta ActiveConnection su Nothing o su un altro oggetto Connection, l'insieme è cancellato. Se si inseriscono oggetti Parameter creati manualmente nell'insieme Parameters dell'oggetto Command e si imposta la proprietà ActiveConnection su Nothing o su un altro oggetto Connection, l'insieme Parameters non è modificato.
La chiusura di un oggetto Connection a cui è associato un oggetto Command consente di impostare la proprietà ActiveConnection su Nothing. Impostando questa proprietà su un oggetto Connection chiuso, è restituito un errore.

CommandTimeout

Indica il tempo da attendere prima di ritornare un errore di "tempo scaduto per l'operazione". Il valore deve essere indicato in secondi. Il default è di 30 secondi.

CommandText

Imposta o restituisce un valore String contenente un comando di provider, quale un'istruzione SQL, un nome di tabella o una chiamata a una stored procedure. Il valore predefinito è una stringa di lunghezza zero.
Se la proprietà Prepared è impostata su True e l'oggetto Command è legato a una connessione aperta durante l'impostazione della proprietà CommandText, quando è chiamato il metodo Execute o Open ADO prepara la query, vale a dire una forma compilata della query memorizzata dal provider.
A seconda dell'impostazione della proprietà CommandType, ADO può modificare la proprietà CommandText. È possibile leggere la proprietà CommandText in qualsiasi momento per visualizzare il testo del comando che è utilizzato da ADO durante l'esecuzione.

CommandType

Indica il tipo di oggetto command, è possibile utilizzare uno o una combinazione di più dei valori seguenti:

• adCmdText: Definisce CommandText come la definizione testuale di un comando o una chiamata di stored procedure.
• adCmdTable: Definisce CommandText come un nome di tabella le cui colonne sono tutte restituite tramite una query SQL generata internamente.
• adCmdTableDirect: Definisce CommandText come un nome di tabella le cui colonne sono tutte restituite.
• adCmdStoredProc: Definisce CommandText come un nome di stored procedure.
• adCmdUnknown: Predefinita. Il tipo di comando della proprietà CommandText non è conosciuto.
• adCommandFile: Definisce CommandText come il nome di file di un Recordset che deve rimanere fisso.
• adExecuteNoRecords: Definisce CommandText come un comando o una stored procedure che non restituisce alcuna riga, quale un comando che inserisce solamente dati. Le righe trovate sono scartate e non restituite. Sempre associata a adCmdText o adCmdStoredProc.

Se il valore della proprietà CommandType corrisponde a adCmdUnknown (valore predefinito), è possibile che si verifichi una riduzione delle prestazioni in quanto ADO deve eseguire delle chiamate al provider per determinare se la proprietà CommandText è un'istruzione SQL, una stored procedure o un nome di tabella. Se si conosce il tipo di comando in uso, l'impostazione della proprietà CommandType indica il codice appropriato.
Se la proprietà CommandType non corrisponde al tipo di comando indicato nella proprietà CommandText, si verifica un errore quando si chiama il metodo Execute.
La costante adExecuteNoRecords ottimizza le prestazioni riducendo il carico di elaborazione interna. Questa costante non è mai isolata ma è sempre associata a adCmdText o adCmdStoredProc (ad esempio, adCmdText+adExecuteNoRecords). Con il metodo Recordset.Open non è possibile utilizzare la costante adExecuteNoRecords né un oggetto Command. Qualora ciò si verificasse, sarebbe segnalato un errore.

Prepared

Indica se salvare o meno una versione compilata di un comando prima dell'esecuzione.
Valori possibili: TRUE o FALSE.

Osservazioni

Utilizzare la proprietà Prepared se si desidera che il provider salvi una versione preparata o compilata della query specificata nella proprietà CommandText prima di eseguire per la prima volta un oggetto Command. Questa operazione rallenta la prima esecuzione del comando, ma una volta compilato il comando, il provider ne utilizza la versione compilata per le esecuzioni successive, consentendo in tal modo di ottenere un miglioramento generale delle prestazioni.
Se la proprietà è impostata su False, il provider esegue direttamente l'oggetto Command senza crearne una versione compilata.
Se il provider non supporta la preparazione dei comandi, è possibile che sia restituito un errore quando la proprietà viene impostata su True. Se non è restituito alcun errore, la richiesta di compilazione del comando è ignorata e la proprietà Prepared è impostata su False.

State

La proprietà State può essere utilizzata per determinare lo stato corrente di un determinato oggetto in qualsiasi momento. Si tratta di una proprietà di sola lettura.

• adStateClosed: Predefinita. L'oggetto è chiuso.
• adStateOpen: L'oggetto è aperto.

Metodi

Execute

Esegue la query, l'istruzione SQL, la stored procedure o il testo specifico del provider.

Sintassi

Per una stringa di comando che non restituisce valori:

Per una stringa di comando che restituisce righe:

In questo caso la Execute costruisce e ritorna un oggetto di tipo Recordset.

Parametri

• Record: Variabile Long a cui il provider restituisce il numero di record interessati dall'operazione (opzionale).
• Parametri: Array di valori dei parametri passati con un'istruzione SQL (opzionale). I parametri di output non restituiranno valori corretti quando vengono passati in questo argomento.
• Opzioni: Valore Long che indica come il provider deve valutare l'argomento Comando (opzionale). Può essere una delle seguenti costanti:
  • adCmdText: Indica che il provider deve valutare Comando come una definizione in formato testo di un comando.
  • adCmdTable: Indica che ADO deve generare una query SQL per restituire tutte le righe della tabella indicata in Comando.
  • adCmdTableDirect: Indica che il provider deve restituire tutte le righe della tabella indicata in Comando.
  • adCmdTable: Indica che il provider deve valutare Comando come un nome di tabella.
  • adCmdStoredProc: Indica che il provider deve valutare Comando come una stored procedure.
  • adCmdUnknown: Indica che il tipo di comando nell'argomento Comando non è conosciuto.
  • adExecuteAsync: Indica che il comando deve essere eseguito in modalità asincrona.
  • adFetchAsync: Indica che sulle righe rimanenti dopo la quantità iniziale specificata nella proprietà CacheSize deve essere eseguito il fetch in modalità asincrona.

Utilizzando il metodo Execute su un oggetto Command si esegue la query specificata nella proprietà CommandText dell'oggetto. Se la proprietà CommandText specifica una query che restituisce righe, qualsiasi risultato generato dall'esecuzione è memorizzato in un nuovo oggetto Recordset. Se il comando non è una query che restituisce righe, il provider restituisce un oggetto Recordset chiuso. In alcuni linguaggi applicativi è possibile ignorare tale valore restituito se non si desidera alcun Recordset.
Se la query ha dei parametri, sono utilizzati i valori correnti dei parametri dell'oggetto Command, a meno che questi non siano sostituiti dai valori dei parametri passati con la chiamata del metodo Execute. È possibile ignorare un sottoinsieme di parametri omettendo i nuovi valori per alcuni dei parametri quando si chiama il metodo Execute. L'ordine in cui i parametri vengono specificati è lo stesso ordine in cui vengono passati dal metodo. Se ad esempio vi sono quattro o più parametri e si desidera passare nuovi valori solo per il primo e il quarto parametro, è necessario passare Array(var1,,,var4) come argomento Parametri.
Nota
I parametri di output non restituiscono valori corretti quando vengono passati nell'argomento Parametri.
L'oggetto Recordset restituito è sempre un cursore a scorrimento in avanti di sola lettura. Se è necessario un oggetto Recordset con più funzionalità, creare innanzitutto un oggetto Recordset con le impostazioni delle proprietà desiderate, quindi utilizzare il metodo Open dell'oggetto Recordset per eseguire la query e restituire il tipo di cursore desiderato.

CreateParameter

Crea un nuovo oggetto Parameter con le proprietà specificate.

Sintassi

Parametri

• Nome: Elemento String che rappresenta il nome dell'oggetto Parameter (opzionale).
• Tipo: Valore Long che specifica il tipo di dati dell'oggetto Parameter (opzionale).
• Direzione: Valore Long che specifica il tipo di oggetto Parameter (opzionale).
• Dimensione: Valore Long che specifica la lunghezza massima per il valore del parametro in caratteri o byte (opzionale).
• Valore: valore da assegnare al parametro (opzionale).

Osservazioni

Utilizzare il metodo CreateParameter per creare un nuovo oggetto Parameter con il nome, il tipo, la direzione, la dimensione e il valore specificati. Qualsiasi valore passato negli argomenti è scritto nelle proprietà Parameter corrispondenti.
Questo metodo non accoda automaticamente l'oggetto Parameter all'insieme Parameters di un oggetto Command. In questo modo è possibile impostare ulteriori proprietà i cui valori sono convalidati da ADO quando si accoda l'oggetto Parameter all'insieme.
Se si specifica un tipo di dati a lunghezza variabile nell'argomento Tipo, è necessario passare un argomento Dimensione o impostare la proprietà Size dell'oggetto Parameter prima di accodarlo all'insieme Parameters, altrimenti si verifica un errore.

Cancel

Annulla l'esecuzione di una chiamata asincrona del metodo Execute in attesa.

Sintassi

Utilizzare il metodo Cancel per terminare l'esecuzione di una chiamata asincrona del metodo Execute, ovvero il metodo chiamato con l'opzione adConnectAsync, adExecuteAsync o adFetchAsync. Se l'opzione adRunAsync non è stata utilizzata nel metodo che si sta tentando di terminare, Cancel restituisce un errore in fase di esecuzione.

Riferimenti

La pagina principale di ADO
L'oggetto Connection
La collezione di proprietà dell'oggetto Command
La collezione di parametri dell'oggetto Command
I valori numerici delle costanti ADO

Categories

ADO
Database