Paramètres d’événement

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 Commande, 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, Recordsetet Connection objets 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 survenir lorsqu'une des méthodes de navigation (MoveNext, MovePrevious, etc.) est appelée, ou à la suite d'un nouvel envoi de requête.

Paramètre d’état

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

Valeur	Description
adStatusOK	Transmis aux événements Will et Complete. Cette valeur signifie que l’opération à l’origine de l’événement s’est terminée correctement.
desErreursDeStatutPublicitaireSontSurvenues	Transmis uniquement aux événements Complete. Cette valeur signifie que l’opération à l’origine de l’événement n’a pas réussi ou qu’un événement "Will" a annulé l’opération. Pour plus d’informations, consultez le paramètre Error.
adStatusCantDeny	Transmis 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 effectué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 procédez ainsi, 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 contiendra 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 notifications d’événements RecordChange en attente, vous devez définir le paramètre Status sur adStatusUnwantedEvent pour adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDeleteet adRsnFirstChange lorsqu’ils se produisent.

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

Paramètre d’erreur

Le paramètre Error est une référence à un objet ADO Error. Lorsque le paramètre Status est défini sur adStatusErrorsOccurred, l’objet Error contient des détails sur la raison de l’échec de l’opération. 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 d’objet

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 Motif

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 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 qui ne vous intéressent pas. Par exemple, si vous souhaitez traiter les événements de modification d’enregistrement uniquement lorsqu’ils se produisent parce qu’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 se produire pour chacune des autres raisons. Toutefois, elle ne se produit qu’une seule fois pour chaque raison. Une fois la notification effectuée pour chaque raison, vous recevrez une notification uniquement pour l’ajout d’un nouvel enregistrement.

En revanche, vous devez définir adStatus sur adStatusUnwantedEvent pour 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

Synthèse du gestionnaire d’événements ADO
instanciation d’événements ADO par langage
comment les gestionnaires d’événements fonctionnent ensemble
types d’événements