События объекта Recordset
Только два объекта ADO обладают событиями - Connection и Recordset. События могут возникать перед началом выполнения той или иной команды, что позволяет проверить возможность ее выполнения и произвести отмену выполнения, не дожидаясь появления ошибки. У объекта Recordset таких событий четыре:
- Event WillChangeField(cFields As Long, Fields, adStatus As EventStatusEnum, pRecordset As Recordset),
- Event WillChangeRecord(adReason As EventReasonEnum, cRecords As Long, adStatus As EventStatusEnum, pRecordset As Recordset),
- Event WillChangeRecordset(adReason As EventReasonEnum, adStatus As EventStatusEnum, pRecordset As Recordset),
- Event WillMove(adReason As EventReasonEnum, adStatus As EventStatusEnum, pRecordset As Recordset).
Эти события возникают перед тем, как выполняемая операция изменит поле записи, саму запись, например при выполнении операций AddNew или Delete, набор записей, например, при выполнении пакетного обновления, или при перемещении курсора на новую запись. Параметры, передаваемые событию, имеют понятный смысл:
- pRecordset - задает указатель на набор записей,
- adStatus - определяет состояние, в котором находится операция. Перед началом выполнения операции свойству Status целесообразно присвоить значение adStatusCancel. В обработчике события можно проверить значение этого свойства, если оно имеет значение adStausOk, то операция выполняется нормально.
- AdReason - определяет выполняемую операцию, являющуюся причиной появления события.
- cFields и Fields - задают соответственно номер поля в массиве Fields, который содержит поля, подлежащие изменениям.
- cRecords - номер изменяемой записи.
Большая часть событий связана с окончанием выполнения команды. Вот четыре события, которые дополняют события Will:
- Event FieldChangeComplete(cFields As Long, Fields, pError As Error, adStatus As EventStatusEnum, pRecordset As Recordset),
- Event RecordChangeComplete(adReason As EventReasonEnum, cRecords As Long, pError As Error, adStatus As EventStatusEnum, pRecordset As Recordset),
- Event RecordsetChangeComplete(adReason As EventReasonEnum, pError As Error, adStatus As EventStatusEnum, pRecordset As Recordset),
- Event MoveComplete(adReason As EventReasonEnum, pError As Error, adStatus As EventStatusEnum, pRecordset As Recordset).
У всех этих событий помимо уже описанных параметров обработчику события передается еще один параметр pError - указатель на объект Error, позволяющий провести обработку ошибок, если они возникли в ходе выполнения операции.
У объекта Recordset есть еще три события:
- Event EndOfRecordset(fMoreData As Boolean, adStatus As EventStatusEnum, pRecordset As Recordset). Событие возникает при выполнении операции MoveNext, когда при перемещении по набору достигнут его конец. В обработчике события можно предусмотреть добавление новых записей в конец набора, и повторить выполнение операции. Заметьте, параметр fMoreData следует установить в этом случае как Variant_True.
- Event FetchProgress(Progress As Long, MaxProgress As Long, adStatus As EventStatusEnum, pRecordset As Recordset), Event FetchComplete(pError As Error, adStatus As EventStatusEnum, pRecordset As Recordset). Первое из этих событий периодически вызывается, чтобы уведомить сколь много записей было доставлено во время выполнения долгой асинхронной операции. Второе событие возникает по завершении операции доставки записей. Параметр Progress указывает число доставленных записей, а MaxProgress - число ожидаемых для получения записей.