Parâmetros de eventos
Aplica-se ao: Access 2013, Office 2013
Cada manipulador de eventos possui um parâmetro de status que o controla. No caso dos eventos Complete, esse parâmetro também é usado para indicar o êxito ou a falha da operação que gerou o evento. A maioria desses eventos também possui um parâmetro de erro que fornece informações sobre qualquer erro que possa ter ocorrido, bem como um ou mais parâmetros de objeto que fazem referência aos objetos ADO usados para executar a operação. Por exemplo o evento ExecuteComplete inclui parâmetros para os objetos Command, Recordset e Connection associados ao evento. Neste exemplo do Microsoft Visual Basic, você poderá 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)
Os mesmos parâmetros são passados para os eventos Will, com exceção do objeto Error. Desse modo, você terá a oportunidade de examinar cada um dos objetos a serem usados na operação pendente e determinar se a operação deverá obter permissão para ser concluída.
Alguns manipuladores de eventos possuem o parâmetro Reason, que fornece informações adicionais sobre o motivo do evento. Por exemplo, os eventos WillMove e MoveComplete podem ocorrer devido à chamada de qualquer um dos métodos de navegação (MoveNext, MovePrevious etc.) ou como resultado de uma repetição de consulta.
Parâmetro Status
Quando a rotina manipuladora de eventos é chamada, o parâmetro Status é definido para um destes valores.
Valor |
Descrição |
|---|---|
adStatusOK |
Passado para os eventos Will e Complete. Este valor indica que a operação que causou o evento foi concluída com êxito. |
adStatusErrorsOccurred |
Passado somente para os eventos Complete. Este valor indica que a operação que causou o evento não teve êxito ou que um evento Will cancelou a operação. Verifique o parâmetro Error para obter mais detalhes. |
adStatusCantDeny |
Passado somente para eventos do Will. Esse valor significa que a operação não pode ser cancelada pelo evento Will. Ela deve ser executada. |
Se você determinar em seu evento Will que a operação deve continuar, não altere o parâmetro Status. Entretanto, se o parâmetro de status de entrada não estiver definido como adStatusCantDeny, você poderá cancelar a operação pendente, alterando Status para adStatusCancel. Em seguida, o evento Complete associado à operação terá seu parâmetro Status definido como adStatusErrorsOccurred. O objeto Error passado para o evento Complete conterá o valor adErrOperationCancelled.
Se não desejar mais processar um evento, você poderá definir Status como adStatusUnwantedEvent para que seu aplicativo não receba mais notificações desse evento. Lembre-se, entretanto, 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 de notificação de eventos RecordChange pendentes, defina o parâmetro Status como adStatusUnwantedEvent para adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete e adRsnFirstChange à medida que eles ocorrerem.
Valor |
Descrição |
|---|---|
adStatusUnwantedEvent |
Solicita que o manipulador de eventos não receba mais notificações. |
adStatusCancel |
Solicita o cancelamento da operação que está prestes a ocorrer. |
Parâmetro Error
O parâmetro Error é uma referência a um objeto Error do ADO. Quando o parâmetro Status é definido como adStatusErrorsOccurred, o objeto Error contém detalhes sobre o motivo da falha da operação. Se o evento Will associado a um evento Complete tiver cancelado a operação definindo o parâmetro Status como adStatusCancel, o objeto error será sempre 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 do evento. Os eventos com esse tipo de parâmetro podem ser chamados várias vezes, inclusive para a mesma operação, e sempre por um motivo diferente. For example, the WillChangeRecord event handler is called for operations that are about to do or undo the insertion, deletion, or modification of a record. Se desejar processar somente um evento no momento em que ele ocorrer por um determinado motivo, você poderá usar o parâmetro adReason para filtrar as ocorrências que não sejam de seu interesse. For example, if you wanted to process record-change events only when they occur because a record was added, you can do something like this:
' 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
Neste caso, a notificação poderá ocorrer para cada um dos outros motivos. Entretanto, ela ocorrerá apenas uma vez para cada um deles. Depois que ela ocorrer uma vez para cada motivo, você somente a receberá caso adicione um novo registro.
Por outro lado, você precisará definir adStatus como adStatusUnwantedEvent somente uma vez para solicitar que um manipulador de eventos sem o parâmetro adReason pare de receber notificações de evento.