事件参数

项目
05/30/2023

每个事件处理程序都有一个控制事件处理程序的 status 参数。对于 Complete 事件，此参数还用于指示生成事件的操作是成功还是失败。大多数 Complete 事件还有一个错误参数，用于提供有关可能发生的任何错误的信息，以及一个或多个对象参数，这些参数引用用于执行操作的 ADO 对象。例如，ExecuteComplete 事件包括与该事件关联的 Command、Recordset 和 Connection 对象的对象参数。在以下 Visual Basic 示例中，可以看到 pCommand、pRecordset 和 pConnection 对象，这些表示由 Execute 方法使用的 Command、Recordset 和 Connection 对象。

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)

除 Error 对象外，相同的参数将传递给 Will 事件。这样，便可以检查待挂起操作中使用的每个对象，并确定是否应允许该操作完成。

某些事件处理程序具有 Reason 参数，该参数提供有关事件发生原因的其他信息。例如，调用任何一种导航方法（MoveNext、MovePrevious 等）或者重新查询都可能导致发生 WillMove 和 MoveComplete 事件。

Status 参数

调用事件处理程序例程时，Status 参数被设置为以下值之一。

值	说明
adStatusOK	传递给 Will 和 Complete 事件。此值表示导致该事件的操作成功完成。
adStatusErrorsOccurred	仅传递给 Complete 事件。此值表示导致该事件的操作不成功，或者 Will 事件取消了该操作。有关详细信息，请查看 Error 参数。
adStatusCantDeny	仅传递给 Will 事件。此值表示 Will 事件无法取消该操作。而必须执行该操作。

如果在 Will 事件中确定操作应继续，则保持 Status 参数不变。只要传入的 status 参数没有设置为 adStatusCantDeny，就可通过将 Status 更改为 adStatusCancel 来取消挂起的操作。执行此操作时，与操作关联的 Complete 事件会将其 Status 参数设置为 adStatusErrorsOccurred。传递给 Complete 事件的 Error 对象将包含值 adErrOperationCancelled。

如果不再需要处理事件，可以将 Status 设置为 adStatusUnwantedEvent，应用程序将不再接收该事件的通知。但是，请记住，某些事件可能会因为多个原因而引发。在这种情况下，必须为每个可能的原因指定 adStatusUnwantedEvent。例如，要停止接收挂起的 RecordChange 事件的通知，当 adRsnAddNew、adRsnDelete、adRsnUpdate、adRsnUndoUpdate、adRsnUndoAddNew、adRsnUndoDelete、adRsnFirstChange 发生时，必须将 Status 参数设置为 adStatusUnwantedEvent。

值	说明
adStatusUnwantedEvent	请求此事件处理程序不再接收任何通知。
adStatusCancel	请求取消即将发生的操作。

Error 参数

Error 参数是对 ADO Error 对象的引用。当 Status 参数设置为 adStatusErrorsOccurred 时，Error 对象将包含有关操作失败原因的详细信息。如果与 Complete 事件相关联的 Will 事件通过将 Status 参数设置为 adStatusCancel 来取消操作，则 Error 对象总是设置为 aderoperationcancelled。

Object 参数

每个事件接收一个或多个对象，这些对象表示操作中涉及的对象。例如，ExecuteComplete 事件接收 Command 对象、Recordset 对象和 Connection 对象。

Reason 参数

Reason 参数 adReason 提供有关事件发生原因的其他信息。带有 adReason 参数的事件可以多次调用，即使是对于相同的操作，每次调用的原因也不同。例如，对于将要执行或撤销插入、删除或修改记录的操作，将调用 WillChangeRecord 事件处理程序。如果希望仅在事件因特定原因发生时处理事件，可以使用 adReason 参数筛选掉不感兴趣的事件。例如，如果希望仅在由于添加了记录而发生记录更改事件时处理这些事件，则可以使用如下所示的方法。

' 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

在这种情况下，由于其他原因可能会发生通知。但是，每种原因只会发生一次。在每种原因发生一次通知之后，将仅收到添加新记录的通知。

相反，仅需将 adStatus 设置为 adStatusUnwantedEvent 一次即可请求没有 adReason 参数的事件处理程序停止接收事件通知。

另请参阅

ADO 事件处理程序摘要
 ADO 事件实例化（按语言）
事件处理程序的协同工作原理
 事件类型