Freetutes.com

VB6 beginners tutorial - Learn VB6

Advanced VB6 tutorial - Learn Advanced VB6

Systems Analysis - System analysis and Design tutorial for Software Engineering


You are here: Visual Basic > Advanced VB6 tutorial > Chapter 8

Recordset Events - Visual Basic 6

As mentioned in the section titled "Connection Object Events," the Recordset is one of but two ADO objects that support events and that you can declare using the WithEvents keyword.

Recordset event names and functionality follow a similar pattern to those of Connection events: They are mostly divided into two groups. One group, the Will events, happens just before some action is about to take place; the other group, the Complete events, happens just after an action has occurred.

The EndOfRecordset Event

This event fires when the cursor attempts to move past the first or last row of the Recordset and the BOF or EOF property becomes True.

You can use this event to add new records at the end of the Recordset when the record pointer attempts to navigate beyond the last record.

The EndOfRecordset event's parameters are as follows:

  • fMoreData - A Boolean that you must set to True if you add records during the course of this event procedure. This signals ADO to find a new end of the Recordset.

  • adStatus - If it is adStatusOK, you can set the value of adStatus to adStatusCancel (the EOF action is cancelled), to adStatusCantDeny (meaning that you can't cancel this event in the future) or adStatusUnwantedEvent (meaning that the event won't fire again).

  • pRecordset - Points to the current Recordset that raised this event (not needed in VB programming).

The Will Events

These Recordset events' names all begin with the word Will (hence, the term Will events). Each Will event happens just before some action on the Recordset.

A list of the Recordset's Will events follows:

  • WillChangeField

  • WillChangeRecord

  • WillChangeRecordset

  • WillMove

Probably the most important parameter of each Will event is the adStatus parameter: It tells you what the current status of the Recordset is, but, more interestingly, you can change its value in the event procedure to either

  • prevent the pending action from occurring (set adStatus to adStatusCancel)

    or

  • change the event's behavior for the rest of the current session: set adStatus to adStatusUnwantedEvent to stop the event from firing again for this Recordset.

A brief description of each Will event and its parameters follows:
  • WillMove - Fires when the current row is about to change.

    adReason - An integer specifying the reason that the move is going to occur. Possible values for this parameter in the context of a move are these: adRsnMoveFirst, adRsnMoveLast, adRsnMoveNext, adRsnMovePrevious, adRsnMove, adRsnRequery.

    adStatus - See earlier discussion.

    pRecordset - Pointer to current Recordset (not used in VB).

  • WillChangeField - Fires when some action will cause one or more fields in the record buffer to change. This could be due to a user edit with the ADO Data Control or due to an assignment of a field's value in your code.

    cFields - Number of fields that will be affected, same as number of elements of the Fields parameter.

    Fields - Variant array of Field objects representing the fields in this record to be changed with this event.

    adStatus - See earlier discussion.

    pRecordset - Pointer to current Recordset (not used in VB).

  • WillChangeRecord - Fires when one or more records in the underlying data are to be changed through deletion, addition, or writing changes from the record buffer to the underlying data.

    adReason - An integer specifying the reason that records are going to be changed. Possible values for this parameter in the context of a record change are these: adRsnAddNew, adRsnDelete, adRsnFirstChange, adRsnUndoAddNew, adRsnUndoDelete, adRsnUndoUpdate, adRsnUpdate.

    cRecords - Number of records that will be affected with this event.

    adStatus - See earlier discussion.

    pRecordset - Pointer to current Recordset (not used in VB).

  • WillChangeRecordset - Fires before some action that will change the entire Recordset across the board, including setting the Recordset to Nothing.

    adReason - An integer specifying the reason that the Recordset is going to be changed. Possible values for this parameter in the context of a Recordset change are these: adRsnRequery, adRsnResynch, adRsnClose, adRsnOpen.

    adStatus - See earlier discussion.

    pRecordset - Pointer to current Recordset (not used in VB).

The Complete Events

There is a correspondingly named Complete event for each of the Recordset's Will events described earlier. Just as a Will event fires before the actual completion of an action, so a Complete event fires after the action has completed. The names of the Complete events are as follows:

  • ChangeFieldComplete

  • ChangeRecordComplete

  • ChangeRecordsetComplete

  • MoveComplete

The Complete events all take the same parameters in the same order as their respective Will events, with one addition: A pError parameter that comes just before the adStatus parameter in all four event pairs and contains an Error object that gives information about any error that occurred.

You can, of course, find out whether an error occurred by checking the adStatus parameter for the value adStatusErrorsOccurred.

See Also


  

<< Previous | Contents | Next >>

Home | About Us | Privacy Policy | Contact Us

Copyright © Freetutes.com | All Rights Reserved