Ereignisparameter

Jeder Ereignishandler verfügt über einen Statusparameter, der den Ereignishandler steuert. Bei Abschlussereignissen wird dieser Parameter ebenfalls verwendet, um den Erfolg oder den Misserfolg des Vorgangs anzugeben, der das Ereignis generiert hat. Die meisten Abschlussereignisse verfügen darüber hinaus über einen Fehlerparameter, um Informationen zu jedem möglicherweise aufgetretenen Fehler bereitzustellen, und mindestens einen Objektparameter, der auf die zum Ausführen des Vorgangs verwendeten ADO-Objekte verweist. Das Ereignis ExecuteComplete enthält beispielsweise Objektparameter für die Objekte Command, Recordset und Connection, die dem Ereignis zugeordnet sind. Im folgenden Visual Basic-Beispiel sehen Sie die Objekte pCommand-, pRecordset und pConnection, die die Objekte Command, Recordset und Connection darstellen, die von der Execute-Methode verwendet werden.

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)  

Mit Ausnahme des Fehler-Objekts werden dieselben Parameter an die Will-Ereignisse übergeben. Dadurch können Sie jedes der Objekte untersuchen, die in dem ausstehenden Vorgang verwendet werden und festlegen, ob der Vorgang abgeschlossen werden darf.

Einige Ereignishandler verfügen über den Parameter Reason, der zusätzliche Informationen dazu bereitstellt, warum das Ereignis aufgetreten ist. Beispielsweise können die Ereignisse WillMove und MoveComplete aufgrund einer der Navigationsmethoden (MoveNext, MovePrevious usw.) auftreten, die aufgerufen werden, oder als Ergebnis einer erneuten Abfrage.

Statusparameter

Wenn die Ereignishandlerroutine aufgerufen wird, wird der Parameter Status auf einen der folgenden Werte festgelegt.

Wert	Beschreibung
adStatusOK	Übergeben an Will- und Complete-Ereignisse. Dieser Wert bedeutet, dass der Vorgang, der das Ereignis verursacht hat, erfolgreich abgeschlossen wurde.
adStatusErrorsOccurred	Nur an Complete-Ereignisse übergeben. Dieser Wert bedeutet, dass der Vorgang, der das Ereignis verursacht hat, nicht erfolgreich war oder dass ein Will-Ereignis den Vorgang abgebrochen hat. Weitere Informationen finden Sie im Parameter Error.
adStatusCantDeny	Nur an Will-Ereignisse übergeben. Dieser Wert bedeutet, dass der Vorgang nicht vom Will-Ereignis abgebrochen werden kann. Er muss durchgeführt werden.

Wenn Sie in Ihrem Will-Ereignis festlegen, dass der Vorgang fortgesetzt werden soll, lassen Sie den Parameter Status unverändert. Solange der eingehende Statusparameter nicht auf adStatusCantDeny festgelegt wurde, können Sie den ausstehenden Vorgang jedoch abbrechen, indem Sie Status in adStatusCancel ändern. Wenn Sie dies tun, ist der Parameter Status des Complete-Ereignisses, das dem Vorgang zugeordnet ist, auf adStatusErrorsOccurred festgelegt. Das an das Complete-Ereignis übergebene Error-Objekt enthält den Wert adErrOperationCancelled.

Wenn Sie kein Ereignis mehr verarbeiten möchten, können Sie Status auf adStatusUnwantedEvent festlegen, woraufhin Ihre Anwendung keine Benachrichtigung über dieses Ereignis mehr erhält. Beachten Sie jedoch, dass einige Ereignisse aus mehreren Gründen ausgelöst werden können. In diesem Fall müssen Sie adStatusUnwantedEvent für jeden möglichen Grund angeben. Wenn Sie beispielsweise den Empfang von Benachrichtigungen über ausstehende RecordChange-Ereignisse beenden möchten, müssen Sie den Parameter Status auf adStatusUnwantedEvent für adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete und adRsnFirstChange festlegen, für den Fall, dass sie auftreten.

Wert	Beschreibung
adStatusUnwantedEvent	Anforderung, dass dieser Ereignishandler keine weiteren Benachrichtigungen erhält.
adStatusCancel	Anforderung zum Abbrechen des Vorgangs, der gerade ansteht.

Fehlerparameter

Der Parameter Fehler ist ein Verweis auf ein ADO-Error-Objekt. Wenn der Parameter Status auf adStatusErrorsOccurred festgelegt ist, enthält das Error-Objekt Details darüber, warum der Vorgang fehlgeschlagen ist. Wenn das mit einem Complete-Ereignis verknüpfte Will-Ereignis den Vorgang abgebrochen hat, indem der Parameter Status auf adStatusCancel festgelegt wurde, wird das Error-Objekt immer auf adErrOperationCancelled festgelegt.

Objektparameter

Jedes Ereignis empfängt mindestens ein Objekt, das die Objekte darstellt, die an dem Vorgang beteiligt sind. Das Ereignis ExecuteComplete empfängt beispielsweise ein Command-Objekt, ein Recordset-Objekt und ein Connection-Objekt.

Grundparameter

Der GrundparameteradReason enthält zusätzliche Informationen darüber, warum es zu dem Ereignis gekommen ist. Ereignisse mit einem AdReason-Parameter können mehrmals aufgerufen werden, auch für denselben Vorgang, und zwar jedes Mal aus einem anderen Grund. Der Ereignishandler WillChangeRecord wird beispielsweise für Vorgänge aufgerufen, die gerade dabei sind, die Einfügung, Löschung oder Änderung eines Datensatzes auszuführen oder rückgängig zu machen. Wenn Sie ein Ereignis nur verarbeiten möchten, wenn es aus einem bestimmten Grund auftritt, können Sie den Parameter AdReason verwenden, um die Vorkommen zu filtern, die Sie nicht interessieren. Wenn Sie beispielsweise Datensatzänderungsereignisse nur verarbeiten möchten, wenn sie auftreten, weil ein Datensatz hinzugefügt wurde, können Sie wie folgt vorgehen.

' 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 diesem Fall kann eine Benachrichtigung potenziell aus jedem der anderen Gründe erfolgen. Sie erfolgt jedoch aus jedem Grund nur einmal. Nachdem die Benachrichtigung einmal aus jedem Grund erfolgt ist, erhalten Sie nur noch eine Benachrichtigung, wenn ein neuer Datensatz hinzugefügt wurde.

Im Gegensatz dazu müssen Sie adStatus auf adStatusUnwantedEvent nur einmal festlegen, um anzufordern, dass ein Ereignishandler ohne den adReason-Parameter den Empfang von Ereignisbenachrichtigungen beendet.

Weitere Informationen

ADO-Ereignishandler – Zusammenfassung
ADO-Ereignisinstanziierung nach Sprache
Zusammenwirken der Ereignishandler
Typen von Ereignissen