FirebirdSQL logo

IBatch

Интерфейс IBatch — позволяет обрабатывать несколько наборов параметров при выполнении одного оператора.

  1. add

    void add(StatusType* status, unsigned count, const void* inBuffer)

    Добавляет количество сообщений из inBuffer в пакет. Общий размер сообщений, которые можно добавить в пакет,ограничен параметром TAG_BUFFER_BYTES_SIZE при создании пакета.

  2. addBlob

    void addBlob(StatusType* status,
                 unsigned length, const void* inBuffer,
                 ISC_QUAD* blobId,
                 unsigned bpbLength, const unsigned char* bpb)

    Добавляет в пакет один BLOB длиной length байт из inBuffer, идентификатор BLOB находится по адресу blobId.Если большой двоичный объект должен быть создан с параметрами, отличными от параметров по умолчанию, то может бытьпередан BPB (формат соответствует формату, используемому в Attachment::createBlob).Общий размер встроенных больших двоичных объектов, которые можно добавить в пакет (включая необязательные BPB,заголовки BLOB, размер сегментов с учётом выравнивания) ограничен параметром TAG_BUFFER_BYTES_SIZE при создании пакета(влияет на все методы, ориентированные на BLOB, кроме registerBlob()).

  3. appendBlobData

    void appendBlobData(StatusType* status, unsigned length, const void* inBuffer)

    Расширяет последний добавленный BLOB: добавляет к нему байты длинной length, взятые по адресу inBuffer.

  4. addBlobStream

    addBlobStream(StatusType* status, unsigned length, const void* inBuffer)

    Добавляет данные BLOB (это может быть несколько объектов или часть одного BLOB) в пакет. Заголовок каждого BLOB в потокевыравнивается по границе getBlobAlignment() и содержит 3 поля: первое - 8-байтовый идентификатор BLOB (в формате ISC_QUAD),второе - 4-байтная длина BLOB, третье - 4-байтная длина BPB. Заголовок большого двоичного объекта не должен пересекатьграницы буфера в этом вызове функции. Данные BPB помещаются сразу после заголовка, затем идут данные BLOB-объектов.Длина большого двоичного объекта включает BPB (если он присутствует). Все данные могут быть распределены междунесколькими вызовами addBlobStream(). Данные BLOB-объекта, в свою очередь, могут быть структурированы в случаесегментированного BLOB-объекта, см. главу "Пакетное изменение данных".

  5. registerBlob

    void registerBlob(StatusType* status, const ISC_QUAD* existingBlob, ISC_QUAD* blobId)

    Позволяет использовать в пакете BLOB, добавленные с помощью стандартного интерфейса IBlob. Эта функция содержит 2параметра ISC_QUAD*, важно их не смешивать – второй параметр (existingBlob) является указателем на идентификатор BLOB,уже добавленный вне области действия пакета, третий (blobId) указывает на идентификатор BLOB, который будет помещен в сообщение в этом пакете'.

  6. execute

    IBatchCompletionState* execute(StatusType* status, ITransaction* transaction)

    Выполняет пакет с параметрами, переданными ему в сообщениях. Если параметр MULTIERROR не установлен в блоке параметровпри создании пакета, выполнение пакета будет остановлено после первой ошибки, в режиме MULTIERROR может произойтинеограниченное количество ошибок, после ошибки выполнение продолжается со следующего сообщения. Эта функция возвращаетинтерфейс IBatchCompletionState, который содержит всю запрошеннуюинформацию о результатах выполнения пакета.

  7. cancel

    void cancel(StatusType* status)

    Очищает буферы сообщений и BLOB, возвращая пакет в состояние, в котором он находился сразу после создания.Обратите внимание: интерфейс IBatch с подсчетом ссылок не содержит какой-либо специальной функции для его закрытия,для этого используйте release().

  8. getBlobAlignment

    unsigned getBlobAlignment(StatusType* status)

    Возвращает необходимое выравнивание для данных, помещаемых в буфер функцией addBlobStream().

  9. getMetadata

    IMessageMetadata* getMetadata(StatusType* status)

    Возвращает формат метаданных, используемых в пакетных сообщениях.

  10. setDefaultBpb

    void setDefaultBpb(StatusType* status, unsigned parLength, const unsigned char* par)

    Задает BPB, который будет использоваться для всех BLOB-объектов, в которых отсутствует BPB не по умолчанию.Должен вызываться перед добавлением любого сообщения или BLOB в пакет.

  11. getInfo

    void getInfo(StatusType* status,
                 unsigned itemsLength, const unsigned char* items,
                 unsigned bufferLength, unsigned char* buffer)

    Запрашивает информацию о пакете.

Тег для блока параметров:

  • VERSION1

Теги для скоплений в блоке параметров:

  • TAG_MULTIERROR (0/1) – может иметь более одного сообщения с ошибками;

  • TAG_RECORD_COUNTS (0/1) - учет измененных записей по сообщениям;

  • TAG_BUFFER_BYTES_SIZE (integer) - максимально возможный размер буфера на сервере (по умолчанию 16Мб, максимум 256Мб);

  • TAG_BLOB_POLICY - политика, используемая для хранения BLOB-объектов;

  • TAG_DETAILED_ERRORS (integer) - сколько векторов с подробной информацией об ошибках хранится в состоянии завершения (по умолчанию 64, максимум 256).

Политики, используемые для хранения BLOB:

  • BLOB_NONE – нельзя использовать встроенные BLOB-объекты (registerBlob() работает в любом случае);

  • BLOB_ID_ENGINE - BLOB добавляются один за другим, BLOB-идентификаторы генерируются движком firebird;

  • BLOB_ID_USER - BLOB добавляются один за другим, BLOB-идентификаторы генерируются пользователем;

  • BLOB_STREAM - BLOB-объекты добавляются в поток.

Элементы, допустимые в вызове getInfo():

  • INF_BUFFER_BYTES_SIZE – фактический максимально возможный размер буфера (устанавливается через TAG_BUFFER_BYTES_SIZE);

  • INF_DATA_BYTES_SIZE - размер уже добавленных сообщений;

  • INF_BLOBS_BYTES_SIZE - размер уже добавленных BLOB;

  • INF_BLOB_ALIGNMENT - требуемое выравнивание для данных BLOB (дублирует getBlobAlignment).

IPluginConfig

Интерфейс IPluginConfig — передается фабрике плагинов при созданииэкземпляра плагина (с конкретной конфигурацией).

  1. getConfigFileName

    const char* getConfigFileName()

    Возвращает рекомендованное имя файла, в котором ожидается сохранениеконфигурации для плагина.

  2. getDefaultConfig

    IConfig* getDefaultConfig(StatusType* status)

    Конфигурация плагина, загруженная по стандартным правилам.

  3. getFirebirdConf

    IFirebirdConf* getFirebirdConf(StatusType* status)

    Возвращает главную конфигурацию Firebird с учётом настроек для базыданных, с которой будет работать новый экземпляр плагина.

  4. setReleaseDelay

    void setReleaseDelay(StatusType* status, ISC_UINT64 microSeconds)

    Используемые плагином для настройки рекомендуемой задержки, в течениекоторой модуль плагина не будет выгружен менеджером плагинов послеосвобождения последнего экземпляра плагина из этого модуля.

IPluginFactory

Интерфейс IPluginFactory — должен быть реализован автором плагина принаписании плагина.

  1. createPlugin

    IPluginBase* createPlugin(StatusType* status, IPluginConfig* factoryParameter)

    Создает новый экземпляр плагина с переданной рекомендуемойконфигурацией.

IPluginManager

Интерфейс IPluginManager — API диспетчера плагинов.

  1. registerPluginFactory

    void registerPluginFactory(unsigned pluginType,
                               const char* defaultName,
                               IPluginFactory* factory)

    Регистрирует именованную фабрику плагинов данного типа.

  2. registerModule

    void registerModule(IPluginModule* cleanup)

    Регистрирует модуль плагина.

  3. unregisterModule

    void unregisterModule(IPluginModule* cleanup)

    Разрегистрирует модуль плагина.

  4. getPlugins

    IPluginSet* getPlugins(StatusType* status,
                           unsigned pluginType,
                           const char* namesList,
                           IFirebirdConf* firebirdConf)

    Возвращает интерфейс IPluginSet, предоставляющий доступ к спискуплагинов данного типа. Имена включенных плагинов берутся из namesList,если отсутствует (NULL), то из настроек конфигурации для данного типаpluginType. Если указан параметр firebirdConf, то он используется длявсех целей конфигурации (включая получение списка плагинов и переход кметоду PluginFactory::createPlugin()), если отсутствует (NULL), тоиспользуется настройка по умолчанию (из firebird.conf).

  5. getConfig

    IConfig* getConfig(StatusType* status, const char* filename)

    Возвращает интерфейс IConfig для заданного имени файла конфигурации.Может использоваться плагинами для доступа к файлам конфигурации состандартным форматом, но не с именем по умолчанию.

  6. releasePlugin

    void releasePlugin(IPluginBase* plugin)

    Освобождение данного плагина. Должен использоваться для плагинов вместопростой release() из-за необходимости выполнять дополнительныедействия с владельцем плагина до фактического освобождения.

Константы, определенные интерфейсом IPluginManager (типы плагинов):

  • TYPE_PROVIDER

  • TYPE_AUTH_SERVER

  • TYPE_AUTH_CLIENT

  • TYPE_AUTH_USER_MANAGEMENT

  • TYPE_EXTERNAL_ENGINE

  • TYPE_TRACE

  • TYPE_WIRE_CRYPT

  • TYPE_DB_CRYPT

  • TYPE_KEY_HOLDER

  • TYPE_REPLICATOR