Como os manipuladores de eventos funcionam em conjunto

A menos que você esteja programando no Visual Basic, todos os manipuladores de eventos para eventos Connection e Recordset precisam ser implementados, independentemente de você realmente processar todos os eventos. A quantidade de trabalho de implementação que você precisa fazer depende da linguagem de programação. Para saber mais, confira Instanciação de eventos do ADO por linguagem.

Manipuladores de eventos emparelhados

Cada manipulador de eventos Will tem um manipulador de eventos Complete associado. Por exemplo, quando seu aplicativo altera o valor de um campo, o manipulador de eventos WillChangeField é chamado. Se a alteração for aceitável, seu aplicativo deixará o parâmetro adStatus inalterado e a operação será executada. Quando a operação for concluída, um evento FieldChangeComplete notificará seu aplicativo de que a operação foi concluída. Se tiver sido concluído com êxito, adStatus conterá adStatusOK; caso contrário, adStatus conterá adStatusErrorsOccurred e você precisará verificar o objeto Error para determinar a causa do erro.

Quando WillChangeField é chamado, você pode determinar que a alteração não deve ser feita. Nesse caso, defina adStatus como adStatusCancel. A operação é cancelada e o evento FieldChangeComplete recebe um valor adStatus de adStatusErrorsOccurred. O objeto Error contém adErrOperationCancelled para que o manipulador FieldChangeComplete saiba que a operação foi cancelada. No entanto, você precisa verificar o valor do parâmetro adStatus antes de alterá-lo, pois a definição de adStatus como adStatusCancel não terá efeito se o parâmetro foi definido como adStatusCantDeny na entrada do procedimento.

Às vezes, uma operação pode gerar mais de um evento. Por exemplo, o objeto Recordset emparelhou eventos para alterações de Field e alterações de Record. Quando seu aplicativo altera o valor de um Field, o manipulador de eventos WillChangeField é chamado. Se ele determinar que a operação pode continuar, o manipulador de eventos WillChangeRecord também será acionado. Se esse manipulador também permitir que o evento continue, a alteração será feita e os manipuladores de eventos FieldChangeComplete e RecordChangeComplete serão chamados. A ordem na qual os manipuladores de eventos Will para determinada operação são chamados não é definida, ou seja, você deve evitar escrever código que dependa de chamar manipuladores em uma sequência específica.

Em instâncias em que vários eventos Will são gerados, um dos eventos pode cancelar a operação pendente. Por exemplo, quando seu aplicativo altera o valor de um Field, os manipuladores de eventos WillChangeField e WillChangeRecord normalmente seriam chamados. No entanto, se a operação for cancelada no primeiro manipulador de eventos, seu manipulador Complete associado será imediatamente chamado com adStatusOperationCancelled. O segundo manipulador nunca é chamado. Se, no entanto, o primeiro manipulador de eventos permitir que o evento prossiga, o outro manipulador de eventos será chamado. Se, em seguida, ele cancelar a operação, ambos os eventos Complete serão chamados como nos exemplos anteriores.

Manipuladores de eventos não emparelhados

Desde que o status passado para o evento não seja adStatusCantDeny, você pode desativar as notificações de evento para qualquer evento com o retorno de adStatusUnwantedEvent no parâmetro Status. Por exemplo, quando o manipulador de eventos Complete for chamado pela primeira vez, você poderá retornar adStatusUnwantedEvent. Posteriormente, você receberá apenas eventos Will. No entanto, alguns eventos podem ser disparados por mais de um motivo. Nesse caso, o evento terá um parâmetro Reason. Ao retornar adStatusUnwantedEvent, você deixará de receber notificações para esse evento somente quando elas ocorrerem por esse motivo específico. Em outras palavras, você potencialmente receberá uma notificação por cada motivo possível para que o evento possa ser disparado.

Manipuladores de eventos Will únicos podem ser úteis quando você deseja examinar os parâmetros que serão usados em uma operação. Você pode modificar esses parâmetros de operação ou cancelar a operação.

Como alternativa, deixe a notificação de evento Complete habilitada. Quando o primeiro manipulador de eventos Will for chamado, retorne adStatusUnwantedEvent. Posteriormente, você receberá apenas eventos Complete.

Manipuladores de eventos Complete únicos podem ser úteis para gerenciar operações assíncronas. Cada operação assíncrona tem um evento Complete apropriado.

Por exemplo, pode levar muito tempo para preencher um objeto Recordset grande. Se o aplicativo for gravado adequadamente, você poderá iniciar uma operação Recordset.Open(...,adAsyncExecute) e continuar com outros processamentos. Eventualmente, você será notificado quando o Recordset for preenchido por um evento ExecuteComplete.

Manipuladores de eventos únicos e vários objetos

A flexibilidade de uma linguagem de programação como o Visual C++ permite a você ter vários eventos de processo de manipulador de eventos de vários objetos. Por exemplo, você pode ter um evento de processo do manipulador de eventos Disconnect de vários objetos Connection. Se uma das conexões terminar, o manipulador de eventos Disconnect será chamado. Você pode informar qual conexão causou o evento porque o parâmetro de objeto do manipulador de eventos seria definido como o objeto Connection correspondente.

Observação

Essa técnica não pode ser usada no Visual Basic porque essa linguagem pode correlacionar apenas um objeto a um manipulador de eventos.

Confira também

Resumo do manipulador de eventos ADO
Instanciação de evento ADO por linguagem
Parâmetros de evento
Tipos de eventos