FirebirdSQL logo

Системные пакеты предоставляют служебные хранимые процедуры и функции.

List of System Packages
[fblangref-build-in-package-blob-util-pkg]

Утилиты для манипуляции BLOB

[fblangref-build-in-package-profiler-pkg]

Профилировщик

[fblangref-build-in-packages-time-zone-util-pkg]

Утилиты поддержки часовых поясов

Пакет RDB$BLOB_UTIL

Пакет RDB$BLOB_UTIL предназначен для управления BLOB-объектами так, как это не могут сделать стандартные функции Firebirdтакие, как BLOB_APPEND и SUBSTRING, или они работают очень медленно.

Эти подпрограммы работают с двоичными данными напрямую, даже с текстовыми BLOB.

Функция RDB$BLOB_UTIL.NEW_BLOB

Функция RDB$BLOB_UTIL.NEW_BLOB используется для создания нового BLOB. Он возвращает BLOB, подходящий для добавления данных, как это делает BLOB_APPEND.

Преимущество по сравнению с BLOB_APPEND заключается в том, что можно установить собственные параметры SEGMENTED и TEMP_STORAGE.

Функция BLOB_APPEND всегда создаёт BLOB во временном хранилище. Это может быть не лучшим подходом,если созданный BLOB будет храниться в постоянной таблице, поскольку для этого потребуется копирование.

Возвращённый BLOB из этой функции, даже если TEMP_STORAGE = FALSE, может использоваться с BLOB_APPEND для добавления данных.

Table 1. Входные параметры функции RDB$BLOB_UTIL.NEW_BLOB
Параметр Тип Описание

SEGMENTED

BOOLEAN NOT NULL

Тип BLOB. Если TRUE - будет создан сегментированный BLOB, FALSE - потоковый.

TEMP_STORAGE

BOOLEAN NOT NULL

В каком хранилище создаётся BLOB. TRUE - во временном, FALSE - в постоянном (для записи в обычную таблицу).

Тип возвращаемого результата

BLOB SUB_TYPE BINARY

Функция RDB$BLOB_UTIL.OPEN_BLOB

Функция RDB$BLOB_UTIL.OPEN_BLOB используется для открытия существующего BLOB для чтения.Она возвращает дескриптор (целое число, связанное с транзакцией), подходящий для использования с другими функциями этого пакета,такими как SEEK, READ_DATA и CLOSE_HANDLE.

Table 2. Входные параметры функции RDB$BLOB_UTIL.OPEN_BLOB
Параметр Тип Описание

BLOB

BLOB NOT NULL

Входной BLOB.

Тип возвращаемого результата

INTEGER

Функция RDB$BLOB_UTIL.IS_WRITABLE

Функция RDB$BLOB_UTIL.IS_WRITABLE возвращает TRUE, если BLOB подходит для добавления данных без копирования с использованием BLOB_APPEND.

Table 3. Входные параметры функции RDB$BLOB_UTIL.IS_WRITABLE
Параметр Тип Описание

BLOB

BLOB NOT NULL

Проверяемый BLOB.

Тип возвращаемого результата

BOOLEAN

Функция RDB$BLOB_UTIL.READ_DATA

Функция RDB$BLOB_UTIL.READ_DATA используется для чтения фрагментов данных из дескриптора BLOB,открытого с помощью RDB$BLOB_UTIL.OPEN_BLOB. Когда BLOB полностью прочитан и данных больше нет, она возвращает NULL.

Если в LENGTH передаётся положительное число, то возвращается VARBINARY максимальной длины LENGTH.

Если в LENGTH передаётся NULL, то возвращается только сегмент BLOB с максимальной длиной 32765.

Table 4. Входные параметры функции RDB$BLOB_UTIL.READ_DATA
Параметр Тип Описание

HANDLE

INTEGER NOT NULL

Дескриптор открытого BLOB.

LENGTH

INTEGER

Количество байт, которое необходимо прочитать.

Тип возвращаемого результата

VARBINARY(32765)

Функция RDB$BLOB_UTIL.SEEK

Функция RDB$BLOB_UTIL.SEEK используется для установки позиции для следующего READ_DATA. Она возвращает новую позицию.

Параметр MODE может быть 0 (с начала), 1 (с текущей позиции) или 2 (с конца).

Когда параметр MODE равен 2, OFFSET должен быть нулевым или отрицательным.

Table 5. Входные параметры функции RDB$BLOB_UTIL.SEEK
Параметр Тип Описание

HANDLE

INTEGER NOT NULL

Дескриптор открытого BLOB.

MODE

INTEGER NOT NULL

Режим поиска.

OFFSET

INTEGER NOT NULL

Смещение, байт.

Тип возвращаемого результата

INTEGER

Процедура RDB$BLOB_UTIL.CANCEL_BLOB

Процедура RDB$BLOB_UTIL.CANCEL_BLOB используется для немедленного освобождения временного BLOB-объекта, например созданного с помощью BLOB_APPEND.

Обратите внимание, что если тот же BLOB используется после отмены, с использованием той же переменной или другой с той же ссылкой на идентификатор BLOB,то будет вызвана ошибка "invalid blob id error".

Table 6. Входные параметры процедуры RDB$BLOB_UTIL.CANCEL_BLOB
Параметр Тип Описание

BLOB

BLOB NOT NULL

BLOB для отмены.

Процедура RDB$BLOB_UTIL.CLOSE_HANDLE

Процедура RDB$BLOB_UTIL.CLOSE_HANDLE используется для закрытия дескриптора BLOB, открытого с помощью RDB$BLOB_UTIL.OPEN_BLOB.

Незакрытые дескрипторы закрываются автоматически только при завершении транзакции.

Table 7. Входные параметры процедуры RDB$BLOB_UTIL.CLOSE_HANDLE
Параметр Тип Описание

HANDLE

INTEGER NOT NULL

Дескриптор BLOB для закрытия.

Примеры использования RDB$BLOB_UTIL

Example 1. Создание BLOB во временном пространстве и возврат его в EXECUTE BLOCK
execute block returns (b blob)
as
begin
    -- Create a BLOB handle in the temporary space.
    b = rdb$blob_util.new_blob(false, true);

    -- Add chunks of data.
    b = blob_append(b, '12345');
    b = blob_append(b, '67');

    suspend;
end
Example 2. Открытие BLOB и его возврат по частям в EXECUTE BLOCK
execute block returns (s varchar(10))
as
    declare b blob = '1234567';
    declare bhandle integer;
begin
    -- Open the BLOB and get a BLOB handle.
    bhandle = rdb$blob_util.open_blob(b);

    -- Get chunks of data as string and return.

    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Here EOF is found, so it returns NULL.
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Close the BLOB handle.
    execute procedure rdb$blob_util.close_handle(bhandle);
end
Example 3. Поиск в BLOB
set term !;

execute block returns (s varchar(10))
as
    declare b blob;
    declare bhandle integer;
begin
    -- Create a stream BLOB handle.
    b = rdb$blob_util.new_blob(false, true);

    -- Add data.
    b = blob_append(b, '0123456789');

    -- Open the BLOB.
    bhandle = rdb$blob_util.open_blob(b);

    -- Seek to 5 since the start.
    rdb$blob_util.seek(bhandle, 0, 5);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Seek to 2 since the start.
    rdb$blob_util.seek(bhandle, 0, 2);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Advance 2.
    rdb$blob_util.seek(bhandle, 1, 2);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;

    -- Seek to -1 since the end.
    rdb$blob_util.seek(bhandle, 2, -1);
    s = rdb$blob_util.read_data(bhandle, 3);
    suspend;
end!

set term ;!
Example 4. Поверка доступен ли BLOB для записи
create table t(b blob);

set term !;

execute block returns (bool boolean)
as
    declare b blob;
begin
    b = blob_append(null, 'writable');
    bool = rdb$blob_util.is_writable(b);
    suspend;

    insert into t (b) values ('not writable') returning b into b;
    bool = rdb$blob_util.is_writable(b);
    suspend;
end!

set term ;!