Parámetros de eventos

Cada controlador de eventos tiene un parámetro de estado que controla al controlador de eventos. En el caso de los eventos Complete, este parámetro también se usa para indicar si se completó correctamente o no la operación que generó el evento. La mayoría de los eventos Complete también tienen un parámetro de error para proporcionar información sobre cualquier error que se haya producido y uno o varios parámetros de objeto que hacen referencia a los objetos de ADO usados para realizar la operación. Por ejemplo, el evento ExecuteComplete incluye parámetros de objeto para los objetos Command, Recordset y Connection asociados al evento. En el ejemplo siguiente de Visual Basic, puede ver los objetos pCommand, pRecordset y pConnection que representan los objetos Command, Recordset y Connection que usa el 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)  

Excepto para el objeto Error, los mismos parámetros se pasan a los eventos Will. Esto le permite examinar cada uno de los objetos que se usarán en la operación pendiente y determinar si se debe permitir que finalice la operación.

Algunos controladores de eventos tienen un parámetro Reason, que proporciona información adicional sobre por qué se produjo el evento. Por ejemplo, los eventos WillMove y MoveComplete pueden producirse debido a que se llama a cualquiera de los métodos de navegación (MoveNext, MovePrevious, etc.) o como resultado de una nueva consulta.

Parámetro Status

Cuando se llama a la rutina del controlador de eventos, el parámetro Status se establece en uno de los valores siguientes.

Valor	Descripción
adStatusOK	Se pasa a los eventos Will y Complete. Este valor significa que la operación que provocó el evento se completó correctamente.
adStatusErrorsOccurred	Solo se pasa a eventos Complete. Este valor significa que la operación que provocó el evento no se realizó correctamente o un evento Will canceló la operación. Consulte el parámetro Error para obtener más detalles.
adStatusCantDeny	Solo se pasa a eventos Will. Este valor significa que el evento Will no puede cancelar la operación. Se debe realizar.

Si determina en el evento Will que la operación debe continuar, deje el parámetro Status sin cambios. Siempre que el parámetro de estado entrante no se haya establecido en adStatusCantDeny, sin embargo, puede cancelar la operación pendiente mediante el cambio de Status a adStatusCancel. Al hacerlo, el evento Complete asociado a la operación tiene el parámetro Status establecido en adStatusErrorsOccurred. El objeto Error pasado al evento Complete contendrá el valor adErrOperationCancelled.

Si ya no quiere procesar un evento, puede establecer Status en adStatusUnwantedEvent y la aplicación ya no recibirá notificaciones de ese evento. Sin embargo, recuerde que algunos eventos se pueden generar por más de un motivo. En ese caso, debe especificar adStatusUnwantedEvent por cada motivo posible. Por ejemplo, para dejar de recibir notificaciones de eventos RecordChange pendientes, debe establecer el parámetro Status en adStatusUnwantedEvent para adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete y adRsnFirstChange a medida que se producen.

Valor	Descripción
adStatusUnwantedEvent	Solicite que este controlador de eventos no reciba más notificaciones.
adStatusCancel	Solicite la cancelación de la operación que está a punto de producirse.

Parámetro Error

El parámetro Error es una referencia a un objeto Error de ADO. Cuando el parámetro Status se establece en adStatusErrorsOccurred, el objeto Error contiene detalles sobre por qué se produjo un error en la operación. Si el evento Will asociado a un evento Complete ha cancelado la operación al establecer el parámetro Status en adStatusCancel, el objeto de error siempre se establece en adErrOperationCancelled.

Parámetro Object

Cada evento recibe uno o varios objetos que representan los objetos implicados en la operación. Por ejemplo, el evento ExecuteComplete recibe un objeto Command, un objeto Recordset y un objeto Connection.

Parámetro Reason

El parámetro Reason, adReason, proporciona información adicional sobre por qué se produjo el evento. Los eventos con un parámetro adReason se pueden llamar varias veces, incluso para la misma operación, por un motivo diferente cada vez. Por ejemplo, se llama al controlador de eventos WillChangeRecord para las operaciones que están a punto de hacer o deshacer la inserción, eliminación o modificación de un registro. Si quiere procesar un evento solo cuando se produce por un motivo determinado, puede usar el parámetro adReason para filtrar las repeticiones que no le interesen. Por ejemplo, si quiere procesar eventos de cambio de registro solo cuando se producen porque se ha agregado un registro, puede usar algo parecido a lo siguiente.

' 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  

En este caso, la notificación puede producirse por cada uno de los otros motivos. Sin embargo, solo se producirá una vez por cada motivo. Después de que la notificación se haya producido una vez por cada motivo, recibirá una notificación solo para la adición de un nuevo registro.

Por el contrario, debe establecer adStatus en adStatusUnwantedEvent solo una vez para solicitar que un controlador de eventos sin un parámetro adReason deje de recibir notificaciones de eventos.

Consulte también

Conexión ADO y los eventos de conjunto de registros
Creación de instancias de eventos de ADO según el lenguaje
Cómo funcionan conjuntamente los controladores de eventos
Tipos de eventos