Параметры событий

Область применения: Access 2013, Office 2013

Каждый обработчик событий имеет параметр состояния, который управляет обработчиком событий. Для событий Complete этот параметр также используется для указания успешного или неудачного выполнения операции, которая вызвала событие. Большинство событий Complete также имеют параметр ошибки, предоставляющий сведения о любой возможной ошибке, а также один или несколько параметров объекта, ссылающихся на объекты ADO, используемые для выполнения операции. Например, событие ExecuteComplete включает параметры объекта для объектов Command, Recordset и Connection , связанных с событием. В следующем примере Microsoft Visual Basic можно увидеть объекты pCommand, pRecordset и pConnection, которые представляют объекты Command, Recordset и Connection , используемые методом 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) 

За исключением объекта Error , те же параметры передаются в события Will. Это позволяет изучить каждый из объектов, которые будут использоваться в ожидающей операции, и определить, следует ли разрешить выполнение операции.

Некоторые обработчики событий имеют параметр Reason , который предоставляет дополнительные сведения о том, почему произошло событие. Например, события WillMove и MoveComplete могут возникать из-за вызова любого из методов навигации (MoveNext, MovePrevious и т. д.) или в результате запроса.

Параметр Status

При вызове подпрограммы обработчика событий параметру Status присваивается одно из следующих значений.

Значение	Описание
adStatusOK	Передается в события Will и Complete. Это значение означает, что операция, вызвавшей событие, успешно завершена.
adStatusErrorsOccurred	Передается только в события Complete. Это значение означает, что операция, которая вызвала событие, была неудачной или событие Will отменило операцию. Дополнительные сведения см . в параметре Error .
adStatusCantDeny	Передается только в события Will. Это значение означает, что операция не может быть отменена событием Will. Он должен быть выполнен.

Если в событии Will вы определили, что операция должна продолжаться, оставьте параметр Status без изменений. Однако до тех пор, пока параметру входящего состояния не задано значение adStatusCantDeny, можно отменить ожидающую операцию, изменив значение Status на adStatusCancel. В этом случае для события Complete, связанного с операцией, параметр Status имеет значение adStatusErrorsOccurred. Объект Error, переданный событию Complete, будет содержать значение adErrOperationCancelled.

Если вы больше не хотите обрабатывать событие, можно задать для параметра Состояниезначение adStatusUnwantedEvent , и ваше приложение больше не будет получать уведомление об этом событии. Однако помните, что некоторые события могут быть вызваны по нескольким причинам. В этом случае для каждой возможной причины необходимо указать adStatusUnwantedEvent . Например, чтобы прекратить получать уведомления о ожидающих событиях RecordChange , необходимо задать для параметра Statusзначение adStatusUnwantedEvent для adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete и adRsnFirstChange по мере их возникновения.

Значение	Описание
adStatusUnwantedEvent	Запросите, чтобы этот обработчик событий не получал дополнительных уведомлений.
adStatusCancel	Запрос на отмену операции, которая будет выполнена.

Параметр ошибки

Параметр Error является ссылкой на объект ADO Error . Если для параметра Status задано значение adStatusErrorsOccurred, объект Error содержит сведения о том, почему операция завершилась сбоем. Если событие Will, связанное с событием Complete, отменило операцию, задав для параметра Status значение adStatusCancel, объект error всегда имеет значение adErrOperationCancelled.

Параметр объекта

Каждое событие получает один или несколько объектов, представляющих объекты, участвующие в операции. Например, событие 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 прекратил получать уведомления о событиях.