Parâmetros de evento

Cada manipulador de eventos tem um parâmetro de status que controla o manipulador de eventos. Para eventos Completos, esse parâmetro também é usado para indicar o êxito 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 parâmetros de objeto para os objetos Command, Recordsete 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, Recordsete 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)  

Com exceção do 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 operação deve ter permissão para ser concluída.

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

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	Transmitido para ambos os eventos Will e Complete. Esse valor significa que a operação que causou o evento foi concluída com êxito.
errosDeStatusDoAnúncioOcorreu	Somente passado para eventos completos. Esse valor significa que a operação que causou o evento não foi bem-sucedida ou um evento Will cancelou a operação. Verifique o parâmetro Error para obter mais detalhes.
statusAnúncioNãoPodeNegar	Somente eventos passados para Will. Esse valor significa que a operação não pode ser cancelada pelo evento Will. Ele deve ser executado.

Se você determinar em seu evento Will que a operação deve continuar, deixe o parâmetro Status inalterado. Desde que o parâmetro de status de entrada não tenha sido definido como adStatusCantDeny, no entanto, você pode cancelar a operação pendente alterando Status para adStatusCancel. Quando você faz isso, o evento Complete associado à operação tem seu parâmetro Status 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 para adStatusUnwantedEvent e seu aplicativo não receberá mais 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 parar de receber notificações de eventos pendentes de RecordChange, você deve definir o parâmetro Status para adStatusUnwantedEvent para adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDeletee adRsnFirstChange à medida que ocorrem.

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

Parâmetro de erro

O parâmetro Erro é uma referência a um objeto de erro Erro do ADO. Quando o parâmetro Status é definido como adStatusErrorsOccurred, o objeto Error contém detalhes sobre por que 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 de objeto

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 de Razão

O parâmetro Reason, adReason, fornece informações adicionais sobre por que o evento ocorreu. Eventos com um parâmetro adReason podem ser chamados várias vezes, 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 nas quais você não está interessado. Por exemplo, se você quiser processar eventos de alteração de registro somente quando eles 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, a notificação pode ocorrer potencialmente por cada um dos outros motivos. No entanto, isso ocorrerá apenas uma vez por cada motivo. Depois que a notificação tiver ocorrido uma vez por cada motivo, você receberá notificação apenas pela adição de um novo registro.

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

Consulte Também

resumo do manipulador de eventos do ADO
Instanciação de evento ADO por linguagem
como os manipuladores de eventos funcionam juntos
Os tipos de eventos