Paramètres des événements

Chaque gestionnaire d’événements a un paramètre d’état qui contrôle le gestionnaire d’événements. Pour les événements Complete, ce paramètre est également utilisé pour indiquer la réussite ou l’échec de l’opération qui a généré l’événement. La plupart des événements Complete ont également un paramètre d’erreur pour fournir des informations sur toute erreur qui peut s’être produite, et un ou plusieurs paramètres d’objet qui font référence aux objets ADO utilisés pour effectuer l’opération. Par exemple, l’événement ExecuteComplete inclut des paramètres d’objet pour les objets Command, Recordset et Connection associés à l’événement. Dans l’exemple Visual Basic suivant, vous pouvez voir les objets pCommand, pRecordset et pConnection qui représentent les objets Command, Recordset et Connection utilisés par la méthode 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)  

À l’exception de l’objet Error, les mêmes paramètres sont passés aux événements Will. Cela vous permet d’examiner chacun des objets qui seront utilisés dans l’opération en attente et de déterminer si l’opération doit être autorisée à se terminer.

Certains gestionnaires d’événements ont un paramètre Reason, qui fournit des informations supplémentaires sur la raison pour laquelle l’événement s’est produit. Par exemple, les événements WillMove et MoveComplete peuvent se produire en raison de l’une des méthodes de navigation (MoveNext, MovePrevious, et ainsi de suite) appelées ou en raison d’une nouvelle requête.

Paramètres Status

Lorsque la routine de gestionnaire d’événements est appelée, le paramètre Status est défini sur l’une des valeurs suivantes.

Valeur	Description
adStatusOK	Transfert aux événements Will et Complete. Cette valeur signifie que l’opération qui a provoqué l’achèvement de l’événement a réussi.
adStatusErrorsOccurred	Transfert aux événements Complete uniquement. Cette valeur signifie que l’opération qui a provoqué l’échec de l’événement ou qu’un événement Will a annulé l’opération. Vérifiez le paramètre Error pour plus d’informations.
adStatusCantDeny	Transfer aux événements Will uniquement. Cette valeur signifie que l’opération ne peut pas être annulée par l’événement Will. Elle doit être exécutée.

Si vous déterminez dans votre événement Will que l’opération doit continuer, laissez le paramètre Status inchangé. Tant que le paramètre d’état entrant n’a pas été défini sur adStatusCantDeny, toutefois, vous pouvez annuler l’opération en attente en modifiant Status en adStatusCancel. Lorsque vous effectuez cette opération, l’événement Complete associé à l’opération a son paramètre Status défini sur adStatusErrorsOccurred. L’objet Error passé à l’événement Complete contient la valeur adErrOperationCancelled.

Si vous ne souhaitez plus traiter un événement, vous pouvez définir Status sur adStatusUnwantedEvent et votre application ne recevra plus de notification de cet événement. Toutefois, n’oubliez pas que certains événements peuvent être déclenchés pour plusieurs raisons. Dans ce cas, vous devez spécifier adStatusUnwantedEvent pour chaque raison possible. Par exemple, pour arrêter la réception de notification d’événements RecordChange en attente, vous devez définir le paramètre Status sur adStatusUnwantedEvent pour adRsnAddNew, adRsnDelete, adRsnUpdate,adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete et adRsnFirstChange comme ils se produisent.

Valeur	Description
adStatusUnwantedEvent	Demandez à ce que ce gestionnaire d’événements ne reçoive aucune notification supplémentaire.
adStatusCancel	Demandez l’annulation de l’opération sur le point de se produire.

Paramètre Error

Le paramètre Error est une référence à un objet Error ADO. Lorsque le paramètre Status est défini sur adStatusErrorsOccurred, l’objet Error contient des détails sur la raison pour laquelle l’opération a échoué. Si l’événement Will associé à un événement Complete a annulé l’opération en définissant le paramètre Status sur adStatusCancel, l’objet d’erreur est toujours défini sur adErrOperationCancelled.

Paramètre Object

Chaque événement reçoit un ou plusieurs objets représentant les objets impliqués dans l’opération. Par exemple, l’événement ExecuteComplete reçoit un objet Command, un objet Recordset et un objet Connection.

Paramètre Reason

Le paramètre Reason, adReason, fournit des informations supplémentaires sur la raison pour laquelle l’événement s’est produit. Les événements avec un paramètre adReason peuvent être appelés plusieurs fois, même pour la même opération, pour une raison différente chaque fois. Par exemple, le gestionnaire d’événements WillChangeRecord est appelé pour les opérations qui sont sur le point d’effectuer ou d’annuler l’insertion, la suppression ou la modification d’un enregistrement. Si vous souhaitez traiter un événement uniquement lorsqu’il se produit pour une raison particulière, vous pouvez utiliser le paramètre adReason pour filtrer les occurrences dont vous n’êtes pas intéressé. Par exemple, si vous souhaitez traiter les événements de modification d’enregistrement uniquement lorsqu’ils se produisent, car un enregistrement a été ajouté, vous pouvez utiliser quelque chose comme suit.

' 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  

Dans ce cas, la notification peut potentiellement se produire pour chacune des autres raisons. Toutefois, elle ne se produit qu’une seule fois pour chaque raison. Une fois que la notification s’est produite une fois pour chaque raison, vous recevrez une notification uniquement pour l’ajout d’un nouvel enregistrement.

En revanche, vous devez définir adStatus sur adStatusUnwantedEvent une seule fois pour demander qu’un gestionnaire d’événements sans paramètre adReason cesse de recevoir des notifications d’événements.

Voir aussi

Présentation rapide du gestionnaire d’événements ADO
Instanciation des événements ADO par langage
Fonctionnement conjoint des gestionnaires d’événements
Types d’événements