Parâmetros de evento

Cada manipulador de eventos tem um parâmetro de status que o controla. Para eventos Complete, esse parâmetro também é usado para indicar o sucesso ou a falha da operação que gerou o evento. A maioria dos eventos Completos também tem um parâmetro de erro para fornecer informações sobre qualquer erro que possa ter ocorrido e um ou mais parâmetros de objeto que se referem aos objetos ADO usados para executar a operação. Por exemplo, o evento ExecuteComplete inclui os parâmetros de objeto dos objetos Command, Recordset e Connection associados ao evento. No exemplo do Visual Basic a seguir, você pode ver os objetos pCommand, pRecordset e pConnection que representam os objetos Command, Recordset e Connection usados pelo método 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)  

Exceto pelo objeto Error, os mesmos parâmetros são passados para os eventos Will. Isso permite examinar cada um dos objetos que serão usados na operação pendente e determinar se a conclusão da operação deve ser autorizada.

Alguns manipuladores de eventos têm um parâmetro Reason, que fornece informações adicionais sobre o motivo pelo qual evento ocorreu. Por exemplo, os eventos WillMove e MoveComplete podem ocorrer devido a qualquer um dos métodos de navegação (MoveNext, MovePrevious e assim por diante) chamados ou como resultado de uma repetição de consulta.

Parâmetro de Status

Quando a rotina do manipulador de eventos é chamada, o parâmetro Status é definido como um dos valores a seguir.

Valor	Descrição
adStatusOK	Passado para eventos Will e Complete. Esse valor significa que a operação que causou o evento foi concluída com êxito.
adStatusErrorsOccurred	Passado somente para eventos Complete. Esse valor significa que a operação que causou o evento não foi concluída com êxito ou que um evento Will cancelou a operação. Verifique o parâmetro Error, para obter mais detalhes.
adStatusCantDeny	Passado somente para eventos Will. Esse valor significa que a operação não pode ser cancelada pelo evento Will. Ela deve ser executada.

Se você determinar no evento Will que a operação deve continuar, deixe o parâmetro Status inalterado. No entanto, desde que o parâmetro de status de entrada não tenha sido definido como adStatusCantDeny, você pode cancelar a operação pendente, alterando Status para adStatusCancel. Quando você faz isso, o parâmetro Status do evento Complete associado à operação é definido como adStatusErrorsOccurred. O objeto Error passado para o evento Complete conterá o valor adErrOperationCancelled.

Se você não quiser mais processar um evento, poderá definir Status como adStatusUnwantedEvent e o aplicativo não receberá mais a notificação desse evento. No entanto, lembre-se de que alguns eventos podem ser gerados por mais de um motivo. Nesse caso, você deve especificar adStatusUnwantedEvent para cada motivo possível. Por exemplo, para interromper o recebimento da notificação de eventos pendentes RecordChange, você deve definir o parâmetro Status como adStatusUnwantedEvent, para adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete e adRsnFirstChange, à medida que ocorrerem.

Valor	Descrição
adStatusUnwantedEvent	Solicitação para que esse manipulador de eventos não receba mais notificações.
adStatusCancel	Solicitação do cancelamento da operação que está prestes a ocorrer.

Parâmetro Error

O parâmetro Error é uma referência a um objeto Error ADO. Quando o parâmetro Status é definido como adStatusErrorsOccurred, o objeto Error contém detalhes sobre o motivo pelo qual a operação falhou. Se o evento Will associado a um evento Complete tiver cancelado a operação, definindo o parâmetro Status como adStatusCancel, o objeto de erro sempre será definido como adErrOperationCancelled.

Parâmetro Object

Cada evento recebe um ou mais objetos que representam os objetos envolvidos na operação. Por exemplo, o evento ExecuteComplete recebe um objeto Command, um objeto Recordset e um objeto Connection.

Parâmetro Reason

O parâmetro Reason, adReason, fornece informações adicionais sobre o motivo pelo qual o evento ocorreu. Os eventos com um parâmetro adReason podem ser chamados várias vezes, até mesmo para a mesma operação, por um motivo diferente a cada vez. Por exemplo, o manipulador de eventos WillChangeRecord é chamado para operações que estão prestes a fazer ou desfazer a inserção, exclusão ou modificação de um registro. Se você quiser processar um evento somente quando ocorrer por um motivo específico, poderá usar o parâmetro adReason para filtrar as ocorrências em que você não está interessado. Por exemplo, se você quiser processar eventos de alteração de registro, somente quando ocorrerem porque um registro foi adicionado, você poderá usar algo semelhante ao seguinte.

' 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  

Nesse caso, é possível que a notificação ocorra devido a cada um dos outros motivos. No entanto, ocorrerá apenas uma vez para cada motivo. Depois que a notificação tiver ocorrido uma vez para cada motivo, você receberá notificação somente pela adição de um novo registro.

Por outro lado, você precisa definir adStatus como adStatusUnwantedEvent apenas uma vez, para solicitar que um manipulador de eventos sem um parâmetro adReason pare de receber notificações de evento.

Confira também

Resumo do manipulador de eventos ADO
Instanciação de evento ADO por linguagem
Como os manipuladores de eventos funcionam em conjunto
Tipos de eventos