Parametri evento

Ogni gestore eventi ha un parametro di stato che controlla il gestore eventi. Per gli eventi Complete, questo parametro viene usato anche per indicare l'esito positivo o negativo dell'operazione che ha generato l'evento. La maggior parte degli eventi Complete include anche un parametro di errore per fornire informazioni su qualsiasi errore che potrebbe essersi verificato e uno o più parametri oggetto che fanno riferimento agli oggetti ADO usati per eseguire l'operazione. Ad esempio, l'evento ExecuteComplete include i parametri oggetto per gli oggetti Command, Recordset e Connection associati all'evento. Nell'esempio seguente di Visual Basic è possibile visualizzare gli oggetti pCommand, pRecordset e pConnection che rappresentano gli oggetti Command, Recordset e Connection usati dal metodo Execute.

Private Sub connEvent_ExecuteComplete(ByVal RecordsAffected As Long, _  
     ByVal pError As ADODB.Error, _  
     adStatus As ADODB.EventStatusEnum, _  
     ByVal pCommand As ADODB.Command, _  
     ByVal pRecordset As ADODB.Recordset, _  
     ByVal pConnection As ADODB.Connection)  

Ad eccezione dell'oggetto Error, vengono passati gli stessi parametri agli eventi Will. In questo modo è possibile esaminare ognuno degli oggetti che verranno usati nell'operazione in sospeso e determinare se consentire il completamento dell'operazione.

Alcuni gestori eventi hanno un parametro Reason, che fornisce informazioni aggiuntive sul motivo per cui si è verificato l'evento. Ad esempio, gli eventi WillMove e MoveComplete possono verificarsi a causa della chiamata di uno dei metodi di spostamento (MoveNext, MovePrevious e così via) o come risultato di una requery.

Parametro Status

Quando viene chiamata la routine del gestore eventi, il parametro Status viene impostato su uno dei valori seguenti.

Valore	Descrizione
adStatusOK	Passato a entrambi gli eventi Will e Complete. Questo valore indica che l'operazione che ha causato l'evento è stata completata correttamente.
adStatusErrorsOccurred	Passato solo agli eventi Complete. Questo valore indica che l'operazione che ha causato l'evento non è riuscita o che un evento Will ha annullato l'operazione. Per altre informazioni, controllare il parametro Error.
adStatusCantDeny	Passato solo agli eventi Will. Questo valore indica che l'operazione non può essere annullata dall'evento Will. Deve essere eseguita.

Se nell'evento Will si stabilisce che l'operazione deve continuare, lasciare invariato il parametro Status. Se il parametro di stato in ingresso non è stato impostato su adStatusCantDeny, è tuttavia possibile annullare l'operazione in sospeso modificando Status in adStatusCancel. Quando si esegue questa operazione, il parametro Status dell'evento Complete associato all'operazione è impostato su adStatusErrorsOccurred. L'oggetto Error passato all'evento Complete conterrà il valore adErrOperationCancelled.

Se non si vuole più elaborare un evento, è possibile impostare Status su adStatusUnwantedEvent e l'applicazione non riceverà più la notifica di tale evento. Tuttavia, tenere presente che alcuni eventi possono essere generati per più motivi. In tal caso, è necessario specificare adStatusUnwantedEvent per ogni motivo possibile. Ad esempio, per non ricevere più la notifica degli eventi RecordChange in sospeso, è necessario impostare il parametro Status su adStatusUnwantedEvent per adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete e adRsnFirstChange quando si verificano.

Valore	Descrizione
adStatusUnwantedEvent	Richiede che questo gestore eventi non riceva ulteriori notifiche.
adStatusCancel	Richiede l'annullamento dell'operazione che sta per verificarsi.

Parametro Error

Il parametro Error è un riferimento a un oggetto ADO Error. Quando il parametro Status è impostato su adStatusErrorsOccurred, l'oggetto Error contiene dettagli sul motivo per cui l'operazione non è riuscita. Se l'evento Will associato a un evento Complete ha annullato l'operazione impostando il parametro Status su adStatusCancel, l'oggetto Error viene sempre impostato su adErrOperationCancelled.

Parametro degli oggetti

Ogni evento riceve uno o più oggetti che rappresentano gli oggetti coinvolti nell'operazione. Ad esempio, l'evento ExecuteComplete riceve un oggetto Command, un oggetto Recordset e un oggetto Connection.

Parametro Reason

Il parametro Reason, adReason, fornisce informazioni aggiuntive sul motivo per cui si è verificato l'evento. Gli eventi con un parametro adReason possono essere chiamati più volte, anche per la stessa operazione, per un motivo diverso ogni volta. Ad esempio, il gestore eventi WillChangeRecord viene chiamato per le operazioni che stanno per eseguire o annullare l'inserimento, l'eliminazione o la modifica di un record. Se si vuole elaborare un evento solo quando si verifica per un motivo specifico, è possibile usare il parametro adReason per filtrare le occorrenze non interessate. Ad esempio, se si desidera elaborare gli eventi di modifica dei record solo quando si verificano perché è stato aggiunto un record, il codice da usare potrebbe essere simile al seguente.

' BeginEventExampleVB01  
Private Sub rsTest_WillChangeRecord(ByVal adReason As ADODB.EventReasonEnum, ByVal cRecords As Long, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)  
   If adReason = adRsnAddNew Then  
       ' Process event  
       '...  
   Else  
       ' Cancel event notification for all  
       ' other possible adReason values.  
       adStatus = adStatusUnwantedEvent  
   End If  
End Sub  
' EndEventExampleVB01  

In questo caso, la notifica può verificarsi potenzialmente per ognuno degli altri motivi. Tuttavia, si verificherà una sola volta per ogni motivo. Dopo che la notifica si è verificata una volta per ogni motivo, si riceverà una notifica solo per l'aggiunta di un nuovo record.

Al contrario, è necessario impostare adStatus su adStatusUnwantedEvent una sola volta per richiedere che un gestore eventi senza un parametro adReason non riceva più le notifiche degli eventi.

Vedi anche

Riepilogo dei gestori eventi ADO
Creazione di istanze evento ADO per linguaggio
Interazione tra i gestori eventi
Tipi di eventi