На этом шаге мы рассмотрим методы и события компонента TIBClientDataSet.

    Методы компонента TIBClientDataSet перечислены в таблице 1.

Таблица 1. Методы компонента TIBClientDataSet

Метод	Описание
procedure AddIndex (const Name, Fields: String; Options: TIndexOptions; const DescFields: String= ' '; const CaselnsFields: String = ' '; const GroupingLevel: Integer = 0);	Создает новый индекс (см. ниже)
procedure AppendData (const Data: OleVariant; HitEOF;Boolean);	Добавляет данные Data к существующему локальному НД. Вместо этого метода обычно используется GetNextPacket
procedure AppendRecord (const Values: array of const);	Добавляет новую запись к НД, заполняет ее значениями Values, отсылает на сервер (или помещает в кэш) и делает ее текущей
procedure ApplyRange;	Включает механизм фильтрации записей по ключевым столбцам
function ApplyUpdates (MaxErrors: Integer): Integer;	Обновляет записи в БД: MaxErrors - максимально допустимое количество ошибок. Возвращает истинное количество ошибок
function BookmarkValid (Bookmark: TBookraark): Boolean;	Возвращает True, если закладка Bookmark содержит правильную ссылку
procedure Cancel; override;	Откатывает все неподтвержденные изменения текущей записи
procedure CancelRange;	Отменяет режим фильтрации по ключевым столбцам
procedure CancelUpdates;	Отменяет все неподтвержденные изменения из пакета Delta
function CompareBookmarks (Bookmarkl, Bookmark2: TBookmark): Integer;	Сравнивает две закладки и возвращает -1, 0 или +1, если первая закладка соответственно меньше, равна или больше второй
function ConstraintsDisabled: Boolean;	Разрешает или запрещает компоненту учитывать ограничения на значения столбцов
function CreateBlobStream (Field: TField; Mode: TBlobStreamMode): TStream;override;	Создает поток данных для BLOB-столбца: Field - имя столбца; Mode - режим потока: для чтения (bmRead), записи (bmWrite) или обновления (bmReadWrite) данных
procedure CreateDataSet;	Создает пустой набор данных с параметрами по умолчанию
procedure DeleteIndex (const Name: String);	Удаляет индекс с именем Name
procedure DisableConstraints;	Временно прекращает действие ограничений, наложенных на значения столбцов
procedure EditKey;	Переводит НД в режим dsEditKey и сохраняет поисковый буфер. Этот метод полезно вызывать для комплексного индекса, когда между двумя поисками меняются лишь некоторые столбцы (см. примечание ниже)
procedure EditRangeEnd;	Переводит НД в режим редактирования нижней границы диапазона фильтрации
procedureEditRangeStart;	Переводит НД в режим редактирования верхней границы диапазона фильтрации
procedure EmptyDataSet;	Очищает буфер от всех записей
procedure EnableConstraints;	Отменяет режим, установленный методом DisableConstraints
procedure Execute; virtual;	Выполняет запрос из свойства CommandText
procedure FetchBlobs;	Получает от сервера приложений текущий BLOB-столбец
procedure FetchDetails;	Получает от сервера приложений детальную таблицу
function FetchParams;	Получает от сервера приложений текущие параметры компонентов TQuery или TStoredProc
function FindKey (const KeyValues: array of const): Boolean;	Аналог одноименного метода ТТаblе (см. примечание ниже)
procedure FindNearest (const KeyValues: array of const);	Аналог одноименного метода ТТаblе (см. примечание ниже)
function GetCurrentRecord (Buffer: PChar): Boolean; override;	Копирует текущую запись в буфер Buffer
function GetFieldData (Field: TField; Buffer: Pointer): Boolean; override;	Копирует столбец Field текущей записи в буфер Buffer
type TGroupPosInd = (gbFirst, gbMiddle, gbLast); TGroupPosInds = set of TGroupPosInd; function GetGroupState(Level: Integer): TGroupPosInds;	Возвращает положение текущей записи в группе агрегирования Level: gbFirst - первая в группе минимум из двух записей; gbMiddle - ни первая, ни последняя; gbLast - последняя в группе минимум из двух записей
procedure GetIndexInfo (IndexName: String);	Возвращает информацию об индексе с именем IndexName
functionGetNextPacket: Integer;	Требует от сервера приложений передать следующий пакет записей. Длина пакета определяется свойством PacketRecords. Функция возвращает количество записей, добавленных в свойство Data
function GetOptionalParam (const ParamName:String): OleVariant;	Возвращает из пакета данных пользовательскую информацию с именем ParamName, которая помещена туда методом SetOptionalParam
procedure GotoCurrent (DataSet: TClientDataset);	Синхронизирует курсор текущего набора с курсором набора DataSet
function GotoKey: Boolean;	Ищет запись, определенную предварительным вызовом SetKey или EditKey с последующим вызовом FieldByName, и возвращает True, если запись найдена (см. примечание ниже)
procedure GotoNearest;	Ищет запись, либо точно соответствующую поисковому значению, либо следующую за ней в порядке индекса. Поисковое значение задается методом SetKey или EditKey с последующим вызовом FieldByName (см. примечание ниже)
procedure LoadFromFile (const FileName: String = ' ') ;	Загружает набор данных из файла FileName. Совместно с SaveToFile дает возможность отложенного обновления данных
procedure LoadFromStream (Stream: TStream);	Загружает набор данных из потока Stream
type TLocateOption =(loCaselnsensitive, loPartialKey); TLocateOptions = set of TLocateOption; function Locate (const KeyFields: String; const KeyValues: Variant; Options: TLocateOptions): Boolean; override;	Ищет запись по значениям KeyValues столбцов KeyFields и возвращает True в случае успеха. Параметр Option уточняет условия поиска: loCaseInsensitive - игнорировать разницу в регистре букв; loPartialKey - искать по части ключа
function Lookup (const KeyFields: String; const KeyValues: Variant; const ResultFields: String): Variant; override;	Ищет запись по значениям KeyValues столбцов KeyFields и возвращает значения столбцов ResultFields найденной записи в случае успеха
procedure MergeChangeLog;	Объединяет данные из протокола изменений с реальными данными с помощью вызова ApplayUpdates
procedure Post; override;	Подтверждает изменения в текущей записи
function Reconcile (const Results : OleVariant): Boolean;	Вызывается методом ApplayUpdates провайдера в случае возникновения ошибки: Results - пакет ошибочных записей. Метод возбуждает событие OnReconcileError для каждой записи пакета Results (см. ниже)
procedure RefreshRecord;	Обновляет текущую запись, считывая ее у провайдера. Протокол изменений записи не меняется
procedure RevertRecord;	Восстанавливает текущую запись по протоколу ее изменений
procedure SaveToFile (const FileName: String = ' ') ;	Сохраняет НД в файле FileName
procedure SaveToStream (Stream: TStream; Format: TDataPacketFormat = dfBinary);	Сохраняет НД в потоке
procedure SetAltRecBuffers (Old, New, Cur: PChar) ;	Устанавливает новые значения в столбцы OldValue, HewValue и CurValue текущей записи
procedure SetKey;	Переводит НД в режим dsSetKey для установки нового поискового значения, которое задается следующим вызовом FieldByName (см. примечание ниже)
procedure SetOptionalParam (const ParamName: String; const Value: OleVariant; IncludeInDelta: Boolean = False);	Помещает в пакет данных пользовательскую информацию: ParamName - имя данных; Value - данные; IncludeInDelta содержит True, если данные помещаются в пакет Delta
procedure SetRange (const StartValues, EndValues: array of const);	Устанавливает диапазон поиска по ключам (см. примечание ниже)
procedure SetRangeEnd;	Устанавливает нижнюю границу диапазона поиска (см. примечание ниже)
procedure SetRangeStart;	Устанавливает верхнюю границу диапазона поиска (см. примечание ниже)
function UndoLastChange (FollowChange: Boolean): Boolean;	Отменяет последнюю операцию изменения, удаления или вставки записи. Если FollowChange=True, после отмены текущей становится восстановленная запись
function UpdateStatus: TUpdateStatus; override;	Возвращает статус обновления текущей записи

    Параметры метода AddIndex перечислены ниже:

• Name - имя индекса;
• Fields - список индексных столбцов;
• Options - может включать 0, 1 или 2 флага ixDescending (сортировка по убыванию) и ixCaseInsensitve (сортировка с учетом регистра букв); остальные значения типа TIndexOptions вызовут исключение;
• DescFields - список столбцов, сортируемых по убыванию (игнорируется, если установлен флаг ixDescending);
• CaseInsFields - список столбцов, сортируемых с учетом регистра букв (игнорируется, если установлен флаг ixCaseInsensitve);
• GroupingLevel - уровень вложенности индекса, заданный по умолчанию.

    Метод Reconcile для каждой ошибочной записи генерирует связанное с компонентом специфическое событие:

type TReconcileAction = (raSkip, raAbort, raMerge, raCorrect, 
      raCancel, raRefresh);
TReconcileErrorEvent = procedure (DataSet: TClientDataSet;
    E: EReconcileError; UpdateKind: TUpdateKind; 
    var Action: TReconcileAction) of object;
property OnReconcileError: TReconcileErrorEvent; 

    Здесь:

• DataSet - клиентский НД, содержащий ошибочные записи (текущая запись этого набора и является ошибочной);
• Е - объект исключения;
• UpdateKind - характер обновления ошибочной записи;
• в параметре Action обработчик должен вернуть одно из следующих значений:
  • oraSkip - пропустить ошибочную запись;
  • oraAbort - прекратить режим корректировки;
  • oгаMеrgе - выполнить конкатенацию ошибочной записи с исходной;
  • oraCorrect - запись была скорректирована в обработчике;
  • oraCancel - восстановить запись по протоколу изменений;
  • oraRefresh - восстановить запись, считав ее из БД.

    Обработчик может использовать значения OldValue, NewValue и CurValue для каждого столбца записи, но он не должен изменять текущее положение курсора НД.

    События компонента TlBClientDataSet перечислены в таблице 2.

Таблица 2. События компонента TIBCLientDataSet

Событие	Описание
type TRemoteEvent = procedure (Sender: TObject; var OwnerData: OleVariant) of object; property AfterApplyUpdates: TRemoteEvent;	Возникает после подтверждения изменений, но перед событием OnReconcileError
property AfterExecute: TRemoteEvent;	Возникает после получения НД в результате выполнения метода Execute
property AfterGetParams: TRemoteEvent;	Возникает после получения от провайдера значений параметров в результате выполнения метода FetchParams
property AfterGetRecords: TRemoteEvent;	Возникает после получения от провайдера пакета данных
property AfterRowRequest: TRemoteEvent;	Возникает после получения компонентом детальной информации о текущей записи
type TUpdateKind = (ukModify, uklnsert, ukDelete); type TAfterUpdateRecordEvent = procedure (Sender: TObject; SourceDS: TDataSet; DeltaDS: TCustomClientDataSet; UpdateKind: TUpdateKind) of object; property AfterUpdateRecord: TAfterUpdateRecordEvent;	Возникает после успешного подтверждения каждой записи. Параметр UpdateKind указывает тип подтвержденных изменений: ukModifу - запись модифицировалась; ukInsert - запись вставлена; ukDelete - запись удалена
property BeforeApplyUpdates: TRemoteEvent;	Возникает перед подтверждением изменений
property BeforeExecute: TRemoteEvent;	Возникает перед выполнением метода Execute
property BeforeGetParams: TRemoteEvent;	Возникает перед выполнением метода FetchParams
property BeforeGetRecords: TRemoteEvent;	Возникает перед получением пакета данных от провайдера
property BeforeRowRequest: TRemoteEvent;	Возникает перед получением компонентом детальной информации о текущей записи
type TBeforeUpdateRecordEvent = procedure (Sender: TObject; SourceDS: TDataSet; DeltaDS: TCustomClientDataSet; UpdateKind: TUpdateKind; var Applied: Boolean) of object; property BeforeUpdateRecord: TBeforeUpdateRecordEvent;	Возникает перед подтверждением изменений каждой записи. Параметр Applied отменяет (True) или разрешает (False) подтверждение
type TGetTableNameEvent = procedure (Sender: TObject; DataSet: TDataSet; var TableName: String) of object; property OnGetTableName: TGetTableNameEvent;	Возникает, когда провайдер не может определить имя таблицы, в которой должны подтверждаться изменения. Если НД составлен объединением нескольких таблиц или является результатом обращения к хранимой процедуре, обработчик этого события - единственное средство определения имени таблиц
type TReconcileAction = (raSkip, raAbort, raMerge, raCorrect, raCancel, raRefresh); type TReconcileErrorEvent = procedure (DataSet: TCustomClientDataSet; E: EReconcileError; UpdateKind: TUpdateKind; var Action: TReconcileAction) of object; property OnReconcileError: TReconcileErrorEvent;	Это событие генерируется методом Reconcile для каждой ошибочной записи (см. выше описание метода Reconcile)
type TProviderDataEvent = procedure (Sender: TObject; DataSet: TCustomClientDataSet) of object; property OnUpdateData: TProviderDataEvent;	Возникает непосредственно перед подтверждением изменений, но после события BeforeApplyUpdates
type TResolverResponse = (rrSkip, rrAbort, rrMerge, rrApply, rrlgnore); type TResolverErrorEvent = procedure (Sender: TObject; DataSet: TCustomClientDataSet; E: EUpdateError; UpdateKind: TUpdateKind; var Response: TResolverResponse) of object; property OnUpdateError: TResolverErrorEvent;	Возникает, если провайдер не может подтвердить изменения очередной записи из-за ошибки в данных. Обработчик может скорректировать запись и сообщить провайдеру свое решение по поводу ошибочных данных в параметре Response (см. ниже)

    Допустимые значения параметра Response типа TResolverResponse:

• rrSkip - пропустить ошибочную запись, не подтверждать изменения в ней и сообщить об ошибке;
• rrAbort - завершить процесс подтверждения записи без сообщения об ошибке;
• rrMerge - заменить ошибочные данные значениями из БД;
• rrApply - продолжить подтверждение, так как обработчик скорректировал запись;
• rrIgnore - не подтверждать изменения и не возвращать запись клиентскому НД в пакете ошибочных данных.

    Со следующего шага мы начнем рассматривать пример использования некоторых из перечисленных компонентов.

Предыдущий шаг Содержание Следующий шаг