Postgres Pro Enterprise : Документация: 18: F.17. dbms_lob — работа с большими объектами : Компания Postgres Professional

F.17. dbms_lob — работа с большими объектами
Пред.	Наверх	Приложение F. Дополнительные модули и расширения, поставляемые в `postgrespro-ent-18-contrib`	Начало	След.

F.17. dbms_lob — работа с большими объектами #

F.17.1. Установка
F.17.2. Типы данных
F.17.3. Вспомогательные функции
F.17.4. Функции и процедуры dbms_lob
F.17.5. Пример

dbms_lob — это расширение Postgres Pro, позволяющее работать с большими объектами (LOB): BLOB, CLOB, BFILE и временными LOB. Расширение можно использовать для обращения к определённым частям больших объектов или большим объектам целиком и управления ими. Функциональность, предоставляемая этим модулем, во многом пересекается с функциональностью пакета DBMS_LOB в Oracle.

Примечание

Обратите внимание, что расширение dbms_lob зависит как от pgpro_bfile, так и от pgpro_sfile. Эти расширения необходимо установить до создания dbms_lob, либо можно установить все зависимости автоматически с помощью команды:

CREATE EXTENSION dbms_lob CASCADE;

F.17.1. Установка #

Расширение dbms_lob включено в состав Postgres Pro Enterprise как стандартное расширение. Чтобы задействовать dbms_lob, создайте расширение с помощью следующего запроса:

CREATE EXTENSION dbms_lob;

F.17.2. Типы данных #

Расширение dbms_lob работает с несколькими типами данных:

Тип bfile предоставляется расширением pgpro_bfile.

CREATE TYPE BFILE AS (
    dir_id int,
    file_name text
);

Таблица F.8. Параметры bfile

Параметр	Описание
`dir_id`	Идентификатор каталога, в котором хранится `bfile`.
`file_name`	Имя файла, из которого нужно прочитать `bfile`.

Тип blob хранит двоичные данные и имеет тот же интерфейс, что и BLOB в Oracle. Предоставляется расширением pgpro_sfile.

CREATE TYPE dbms_lob.blob AS (
    temp_data   bytea,
    mime        text,
    sf          @extschema:pgpro_sfile@.sfile
);

Таблица F.9. Параметры blob

Параметр	Описание
`sf`	Объект типа `sfile` на диске, в котором хранятся объекты BLOB.
`temp_data`	Временные данные BLOB, хранящиеся в памяти.
`mime`	Вспомогательные данные, которые определяют тип данных, хранящихся в BLOB.

Тип clob является эквивалентом CLOB и NCLOB в Oracle. Поддерживается только кодировка UTF-8.

CREATE TYPE CLOB AS (
    t       text,
    istemp  bool,
    mime    text
);

Таблица F.10. Параметры clob

Параметр	Описание
`t`	Объект типа `text` на диске, в котором хранятся данные.
`istemp`	Определяет, является ли объект временным.
`mime`	Вспомогательные данные, которые определяют тип данных, хранящихся в CLOB.

F.17.3. Вспомогательные функции #

bfilename(dirname text, filename text) returns bfile #: Создаёт объект bfile, связанный с физическим файлом в файловой системе. Здесь dirname — это имя объекта каталога, созданного функцией bfile_directory_create(), где находится файл filename.
empty_blob() returns blob #: Создаёт пустой объект blob, содержащий объект типа sfile без данных. Его можно заполнить данными с помощью функций записи.
empty_clob() returns clob #: Создаёт пустой объект clob, содержащий пустую строку. Его можно заполнить данными с помощью функций записи.
to_blob(b bytea) returns blob to_blob(f bfile, mime_type text) returns blob #: Преобразует объекты типа bytea в объекты типа blob. Если исходным файлом является bfile, можно указать тип данных mime.
to_clob(t text) returns clob to_clob(t varchar) returns clob to_clob(b bfile, int csid, mime text) returns clob #: Преобразует текстовые объекты в объекты типа clob. Если исходным файлом является bfile, его данные считываются и преобразуются в тип clob. Поддерживается только кодировка UTF-8.
to_raw(b blob) returns clob to_raw(b bfile) returns clob #: Копирует данные из файла типа blob или bfile в файл типа bytea. Обрабатывается только первый ГБ данных.

F.17.4. Функции и процедуры dbms_lob #

F.17.4.1. Открытие и закрытие больших объектов #

open(file_loc IN OUT bfile, open_mode IN int) open(lob_loc IN OUT blob, open_mode IN int) open(lob_loc IN OUT clob, open_mode IN int) #: Открывает объект типа bfile. Параметр open_mode указывает, в каком режиме будет открыт файл: чтения/записи или только для чтения. Для типа bfile поддерживается исключительно режим только для чтения (0). Функции open(blob) и open(clob) не выполняют никаких действий и необходимы только для обеспечения совместимости синтаксиса.
isopen(file_loc IN bfile) isopen(lob_loc IN blob) isopen(lob_loc IN clob) #: Проверяет, открыт ли объект типа bfile. Возвращает 1, если LOB открыт, и 0 в противном случае. Функции isopen(blob) и isopen(clob) всегда возвращают 1 и необходимы только для обеспечения совместимости синтаксиса.
close(file_loc IN OUT bfile) close(lob_loc IN OUT blob) close(lob_loc IN OUT clob) #: Проверяет, открыт ли объект bfile, и если да, то закрывает его. Функции close(blob) и close(clob) не выполняют никаких действий и необходимы только для совместимости синтаксиса.
createtemporary(lob_loc IN OUT blob, cache IN bool, dur IN int default 10) createtemporary(lob_loc IN OUT clob, cache IN bool, dur IN int default 10) #: Создаёт временный объект LOB, в котором данные типа blob хранятся как данные типа bytea, а данные типа clob — как данные типа text.
freetemporary(lob_loc IN OUT blob) freetemporary(lob_loc IN OUT clob) #: Освобождает ресурсы, связанные с временным большим объектом.

F.17.4.2. Чтение LOB #

getlength(file_loc IN bfile) getlength(lob_loc IN blob) getlength(lob_loc IN clob) #: Возвращает длину blob или bfile в байтах или clob в символах.
read(file_loc IN bfile, amount IN OUT int, offset IN int, buffer OUT bytea) read(lob_loc IN blob, amount IN OUT int, offset IN int, buffer OUT bytea) read(lob_loc IN clob, amount IN OUT int, offset IN int, buffer OUT text) #: Считывает часть LOB и записывает указанное количество байтов (для blob/bfile) или символов (для clob) в буфер (buffer), начиная с абсолютного смещения (offset) от начала LOB. Обратите внимание, что для чтения с начала файла необходимо указать для параметра offset значение 1.
get_storage_limit(lob_loc IN blob) get_storage_limit(lob_loc IN clob) #: Возвращает размер хранилища LOB для указанного LOB.
substr(file_loc IN bfile, amount IN int, offset IN int) substr(lob_loc IN blob, amount IN int, offset IN int) substr(lob_loc IN clob, amount IN int, offset IN int) #: Возвращает количество (amount) байтов (для blob/bfile) или символов (для clob) LOB, начиная с абсолютного смещения (offset) от начала LOB.
instr(file_loc IN bfile, pattern IN int, offset IN bigint default 1, nth IN bigint default 1) instr(lob_loc IN blob, pattern IN int, offset IN bigint default 1, nth IN bigint default 1) instr(lob_loc IN clob, pattern IN int, offset IN bigint default 1, nth IN bigint default 1) #: Возвращает соответствующую позицию n-го (nth) вхождения шаблона (pattern) в LOB, начиная с указанного смещения (offset). Возвращает 0, если шаблон pattern не найден. Поиск осуществляется только в первом ГБ данных.

F.17.4.3. Изменение LOB #

write(lob_loc IN OUT blob, amount IN int, offset IN bigint, buffer IN bytea) write(lob_loc IN OUT clob, amount IN int, offset IN int, buffer IN text) #

Записывает заданный объём данных (amount) во внутренний LOB, начиная с абсолютного смещения (offset) от начала LOB. Данные берутся из параметра buffer. Если указанное значение offset превышает текущий размер LOB, значение дополняется нулевыми байтами для blob или пробелами для clob.

Если buffer длиннее, чем amount, записывается только указанное количество байт (для blob) или символов (для clob). Это гарантирует, что во внутренний LOB будет записано ровно amount данных.

writeappend(lob_loc IN OUT blob, amount IN int, buffer IN bytea) writeappend(lob_loc IN OUT clob, amount IN int, buffer IN text) #

Записывает указанный объём (amount) данных в конец внутреннего LOB. Данные записываются из буфера, указанного в параметре buffer.

erase(lob_loc IN OUT blob, amount IN OUT int, offset IN bigint default 1) erase(lob_loc IN OUT clob, amount IN OUT int, offset IN int default 1) #

Удаляет весь внутренний LOB или часть внутреннего LOB. Когда данные стираются из середины LOB, записываются нулевые байтовые заполнители (для временных blob) или пробелы (для clob). Постоянные объекты типа blob могут быть удалены только целиком.

trim(lob_loc IN OUT blob, newlen IN bigint) trim(lob_loc IN OUT clob, newlen IN int) #

Обрезает значение внутреннего LOB до длины, указанной в параметре newlen. Необходимо указать длину в байтах для временного blob и длину в символах для clob. Применимо для постоянного blob, только если новая длина равна нулю, что означает удаление объекта.

F.17.4.4. Операции с несколькими LOB #

compare(lob_1 IN bfile, lob_2 IN bfile, amount IN bigint, offset_1 IN bigint default 1, offset_2 IN bigint default 1) returns int compare(lob_1 IN blob, lob_2 IN blob, amount IN int default 1024*1024*1024-8, offset_1 IN bigint default 1, offset_2 IN bigint default 1) returns int compare(lob_1 IN clob, lob_2 IN clob, amount IN int default (1024*1024*1024-8)/2, offset_1 IN int default 1, offset_2 IN int default 1) returns int #: Сравнивает два полных LOB или части двух LOB. Можно сравнивать только LOB, имеющие одинаковые типы данных. Для bfile и blob выполняется двоичное сравнение. Для clob файлы сравниваются в соответствии с текущим правилом сортировки базы данных.
append(lob_1 IN OUT blob, lob_2 IN blob) append(lob_1 IN OUT clob, lob_2 IN clob) #: Добавляет содержимое исходного внутреннего LOB в целевой LOB. Исходный LOB добавляется полностью.
copy(dest_lob IN OUT blob, src_lob IN blob, amount IN bigint, dest_offset IN bigint default 1, src_offset IN bigint default 1) returns int copy(dest_lob IN OUT clob, src_lob IN clob, amount IN int, dest_offset IN int default 1, src_offset IN int default 1) returns int #: Копирует весь или часть исходного внутреннего LOB в целевой внутренний LOB. Можно указать смещение как для исходного, так и для целевого LOB, а также количество байтов или символов для копирования.
converttoblob(dest_lob IN OUT blob, src_clob IN clob, amount IN int, dest_offset IN OUT bigint, src_offset IN OUT int, blob_csid IN int, lang_context IN OUT int, warning OUT int) #: Считывает символьные данные из исходного clob, преобразует эти данные в указанный набор символов, записывает преобразованные данные в целевой blob в двоичном формате и возвращает новые смещения. Поддерживается только кодировка UTF-8.
converttoclob(dest_lob IN OUT clob, src_blob IN blob, amount IN int, dest_offset IN OUT int, src_offset IN OUT bigint, blob_csid IN int, lang_context IN OUT int, warning OUT int) #: Считывает двоичные данные из исходного blob, преобразует их в кодировку UTF-8 и записывает преобразованные символьные данные в целевой clob.

F.17.4.5. Устаревшие API #

fileexists(file_loc IN bfile) returns int #: Проверяет, действительно ли существует в файловой системе файл, на который указывает заданный указатель bfile. Реализовано как bfile_fileexists.
fileopen(file_loc IN OUT bfile, open_mode IN int) returns int #: Открывает указанный bfile в режиме только для чтения. Реализовано как функция bfile_open.
fileisopen(file_loc IN bfile) returns int #: Проверяет, открыт ли указанный bfile.
loadfromfile(dest_lob IN OUT blob, src_bfile IN bfile, amount IN int default 1024*1024*1024-8, dest_offset IN bigint default 1, src_offset IN bigint default 1) #: Преобразует данные из указанного bfile в blob.
fileclose(file_loc IN OUT bfile) #: Закрывает ранее открытый bfile. Реализовано как функция bfile_close.
filecloseall() #: Закрывает все файлы bfile, открытые в сеансе. Реализовано как bfile_close_all.
filegetname(file_loc IN bfile, dir_alias OUT text, filename OUT text) #: Определяет объект каталога и имя файла. Эта функция показывает только имя объекта каталога и имя файла, назначенные указателю, а не подтверждает факт существования физического файла или каталога. Реализовано как функция bfile_directory_get_alias_by_id.

F.17.4.6. Прочие параметры #

loadblobfromfile(dest_lob IN OUT blob, src_bfile IN bfile, amount IN int default 1024*1024*1024-8, dest_offset IN bigint default 1, src_offset IN bigint default 1) returns int #: Синоним для loadfromfile().
loadclobfromfile(dest_lob IN OUT clob, src_bfile IN bfile, amount IN int, dest_offset IN OUT int, src_offset IN OUT bigint, bfile_csid IN int, lang_context IN OUTint, warning OUTint) #: Загружает данные из bfile во внутренний clob.
setcontenttype(lob_loc IN OUT blob, contenttype IN text) setcontenttype(lob_loc IN OUT clob, contenttype IN text) #: Устанавливает строку типа содержимого, связанную с LOB.
getcontenttype(lob_loc IN blob) returns text getcontenttype(lob_loc IN clob) returns text #: Возвращает строку типа содержимого, связанную с LOB.
getchunksize(lob_loc IN blob) returns text getchunksize(lob_loc IN clob) returns text #: Возвращает объём пространства, используемого в порции LOB для хранения значения LOB.

F.17.5. Пример #

DO
$$
DECLARE
  cur_clob  dbms_lob.clob;
  buffer    text;
  amount    int := 3000;
BEGIN
  cur_clob := dbms_lob.empty_clob();
  cur_clob.t := 'just some sample text';
  raise notice 'clob length: %', dbms_lob.getlength(cur_clob);
  call dbms_lob.read(cur_clob, amount, 1, buffer);
  raise notice 'all clob read: %', buffer;
  amount := 6;
  call dbms_lob.read(cur_clob, amount, 4, buffer);
  raise notice 'clob read from 4 position for 6 symbols: %', buffer;
  raise notice 'storage limit: %', dbms_lob.get_storage_limit(cur_clob);
  raise notice 'clob substr from 6 position for 8 symbols: %', dbms_lob.substr(cur_clob, 8, 6);
  raise notice 'third postion of letter s in clob: %', dbms_lob.instr(cur_clob, 's', 1, 3);

  call dbms_lob.write(cur_clob, 6, 4, 'foobar');
  raise notice 'new clob contents: %', cur_clob.t;
  call dbms_lob.write(cur_clob, 3, 25, 'baz');
  raise notice 'new clob contents: %', cur_clob.t;

  call dbms_lob.writeappend(cur_clob, 4, 'test');
  raise notice 'new clob contents: %', cur_clob.t;

  amount := 3;
  call dbms_lob.erase(cur_clob, amount, 2);
  raise notice 'amount of symbols deleted: %', amount;
  raise notice 'new clob contents: %', cur_clob.t;
  call dbms_lob.erase(cur_clob, amount, 30);
  raise notice 'amount of symbols deleted: %', amount;
  raise notice 'new clob contents: %', cur_clob.t;

  call dbms_lob.trim_(cur_clob, 22);
  raise notice 'new clob contents: %', cur_clob.t;
END;
$$;
--output
NOTICE:  clob length: 21
NOTICE:  all clob read: just some sample text
NOTICE:  clob read from 4 position for 6 symbols: t some
NOTICE:  storage limit: 536870908
NOTICE:  clob substr from 6 position for 8 symbols: some sam
NOTICE:  third postion of letter s in clob: 11
NOTICE:  new clob contents: jusfoobar sample text
NOTICE:  new clob contents: jusfoobar sample text   baz
NOTICE:  new clob contents: jusfoobar sample text   baztest
NOTICE:  amount of symbols deleted: 3
NOTICE:  new clob contents: j   oobar sample text   baztest
NOTICE:  amount of symbols deleted: 2
NOTICE:  new clob contents: j   oobar sample text   bazte
NOTICE:  new clob contents: j   oobar sample text

Пред.	Наверх	След.
dblink_build_sql_update	Начало	F.18. dict_int — пример словаря текстового поиска для целых чисел

F.17. dbms_lob — operate on large objects
Prev	Up	Appendix F. Additional Supplied Modules and Extensions Shipped in `postgrespro-ent-18-contrib`	Home	Next

F.17. dbms_lob — operate on large objects #

F.17.1. Installation
F.17.2. Data Types
F.17.3. Utility Functions
F.17.4. dbms_lob Functions and Procedures
F.17.5. Example

dbms_lob is a Postgres Pro extension that allows operating on LOBs: BLOB, CLOB, BFILE, and temporary LOBs. The extension can be used to access and manipulate specific parts of a LOB or complete LOBs. The functionality provided by this module overlaps substantially with the functionality of Oracle's DBMS_LOB package.

Note

Note that the dbms_lob extension depends on both pgpro_bfile and pgpro_sfile. You must install these extensions before creating dbms_lob, or you can install all dependencies automatically with:

CREATE EXTENSION dbms_lob CASCADE;

F.17.1. Installation #

The dbms_lob extension is a built-in extension included into Postgres Pro Enterprise. To enable dbms_lob, create the extension using the following query:

CREATE EXTENSION dbms_lob;

F.17.2. Data Types #

The dbms_lob extension works with several data types:

The bfile type is provided by pgpro_bfile.
```
CREATE TYPE BFILE AS (
    dir_id int,
    file_name text
);
```
Table F.8. bfile Parameters
Parameter Description
dir_id The ID of the directory where the bfile is stored.
file_name The name of the file to read the bfile from.
The blob type stores binary data and has the same interface as Oracle's BLOB. It is provided by pgpro_sfile.
```
CREATE TYPE dbms_lob.blob AS (
    temp_data   bytea,
    mime        text,
    sf          @extschema:pgpro_sfile@.sfile
);
```
Table F.9. blob Parameters
Parameter Description
sf sfile object on disk, which contains BLOB.
temp_data Temporary BLOB data stored in memory.
mime Auxiliary data defining the type of data stored in BLOB.
The clob type is the equivalent of Oracle's CLOB and NCLOB. Only the UTF-8 encoding is supported.
```
CREATE TYPE CLOB AS (
    t       text,
    istemp  bool,
    mime    text
);
```
Table F.10. clob Parameters
Parameter Description
t text object on disk, which stores data.
istemp Defines if the object is temporary.
mime Auxiliary data defining the type of data stored in CLOB.

Parameter	Description
`dir_id`	The ID of the directory where the `bfile` is stored.
`file_name`	The name of the file to read the `bfile` from.

Parameter	Description
`sf`	`sfile` object on disk, which contains BLOB.
`temp_data`	Temporary BLOB data stored in memory.
`mime`	Auxiliary data defining the type of data stored in BLOB.

Parameter	Description
`t`	`text` object on disk, which stores data.
`istemp`	Defines if the object is temporary.
`mime`	Auxiliary data defining the type of data stored in CLOB.

F.17.3. Utility Functions #

bfilename(dirname text, filename text) returns bfile #: Creates a bfile object associated with a physical file in the file system. Here dirname is the name of the directory object created with bfile_directory_create() where the file filename is located.
empty_blob() returns blob #: Creates an empty blob object, which contains an sfile without data. It can be populated with data using write functions.
empty_clob() returns clob #: Creates an empty clob object, which contains an empty string. It can be populated with data using write functions.
to_blob(b bytea) returns blob to_blob(f bfile, mime_type text) returns blob #: Converts a bytea object to a blob. If the original file is bfile, the mime data type can be specified.
to_clob(t text) returns clob to_clob(t varchar) returns clob to_clob(b bfile, int csid, mime text) returns clob #: Converts text objects to clob objects. If the original file is bfile, its data is read and converted into clob. Only the UTF-8 encoding is supported.
to_raw(b blob) returns clob to_raw(b bfile) returns clob #: Copies the data from a blob or bfile file into a bytea. Only the first GB of data is processed.

F.17.4. dbms_lob Functions and Procedures #

F.17.4.1. Opening and Closing LOBs #

open(file_loc IN OUT bfile, open_mode IN int) open(lob_loc IN OUT blob, open_mode IN int) open(lob_loc IN OUT clob, open_mode IN int) #: open(bfile) opens a bfile object. The open_mode parameter specifies if the file is to be open in read/write or read-only mode. For bfile, only read-only mode is supported (0). The functions open(blob) and open(clob) do nothing and exist only for syntax compatibility.
isopen(file_loc IN bfile) isopen(lob_loc IN blob) isopen(lob_loc IN clob) #: isopen(bfile) checks if a bfile object is open. Returns 1 if the LOB is open, otherwise 0. The functions isopen(blob) and isopen(clob) always return 1 and exist only for syntax compatibility.
close(file_loc IN OUT bfile) close(lob_loc IN OUT blob) close(lob_loc IN OUT clob) #: close(bfile) checks if a bfile object is open, and if it is, closes it. The functions close(blob) and close(clob) do nothing and exist only for syntax compatibility.
createtemporary(lob_loc IN OUT blob, cache IN bool, dur IN int default 10) createtemporary(lob_loc IN OUT clob, cache IN bool, dur IN int default 10) #: Creates a temporary LOB, with blob data stored as bytea and clob data stored as text.
freetemporary(lob_loc IN OUT blob) freetemporary(lob_loc IN OUT clob) #: Releases resources associated with the temporary LOB.

F.17.4.2. Reading LOBs #

getlength(file_loc IN bfile) getlength(lob_loc IN blob) getlength(lob_loc IN clob) #: Returns the length of a blob or bfile in bytes or a clob in characters.
read(file_loc IN bfile, amount IN OUT int, offset IN int, buffer OUT bytea) read(lob_loc IN blob, amount IN OUT int, offset IN int, buffer OUT bytea) read(lob_loc IN clob, amount IN OUT int, offset IN int, buffer OUT text) #: Reads a piece of a LOB, and writes the specified amount of bytes (blob/bfile) or characters (clob) into the buffer parameter, starting from an absolute offset from the beginning of the LOB. Note that offset 1 should be specified to read from the beginning.
get_storage_limit(lob_loc IN blob) get_storage_limit(lob_loc IN clob) #: Returns the LOB storage limit for the specified LOB.
substr(file_loc IN bfile, amount IN int, offset IN int) substr(lob_loc IN blob, amount IN int, offset IN int) substr(lob_loc IN clob, amount IN int, offset IN int) #: Returns amount of bytes (blob/bfile) or characters (clob) of a LOB, starting from an absolute offset from the beginning of the LOB.
instr(file_loc IN bfile, pattern IN int, offset IN bigint default 1, nth IN bigint default 1) instr(lob_loc IN blob, pattern IN int, offset IN bigint default 1, nth IN bigint default 1) instr(lob_loc IN clob, pattern IN int, offset IN bigint default 1, nth IN bigint default 1) #: Returns the matching position of the nth occurrence of the pattern in the LOB, starting from the specified offset. Returns 0 if the pattern is not found. Only the first GB of data is searched.

F.17.4.3. Updating LOBs #

write(lob_loc IN OUT blob, amount IN int, offset IN bigint, buffer IN bytea) write(lob_loc IN OUT clob, amount IN int, offset IN int, buffer IN text) #

Writes a specified amount of data into the internal LOB, starting from the absolute offset from the beginning of the LOB. The data is taken from the buffer. If the specified offset exceeds the current size of the LOB, the value is padded with zero bytes (for blob) or spaces (for clob).

If buffer is longer than amount, only the specified number of bytes (for blob) or characters (for clob) is written. This ensures that exactly amount of data is written into the internal LOB.

writeappend(lob_loc IN OUT blob, amount IN int, buffer IN bytea) writeappend(lob_loc IN OUT clob, amount IN int, buffer IN text) #

Writes a specified amount of data to the end of an internal LOB. The data is written from the buffer parameter.

erase(lob_loc IN OUT blob, amount IN OUT int, offset IN bigint default 1) erase(lob_loc IN OUT clob, amount IN OUT int, offset IN int default 1) #

Erases an entire internal LOB or part of an internal LOB. When data is erased from the middle of a LOB, zero-byte fillers (temporary blob) or spaces (clob) are written. Non-temporary blob objects can only be deleted as a whole.

trim(lob_loc IN OUT blob, newlen IN bigint) trim(lob_loc IN OUT clob, newlen IN int) #

Trims the value of the internal LOB to the length you specify in the newlen parameter. Specify the length in bytes for temporary blob, and specify the length in characters for clob. For non-temporary blob, works only if the new length is 0, which means erasing the object.

F.17.4.4. Operations with Multiple LOBs #

compare(lob_1 IN bfile, lob_2 IN bfile, amount IN bigint, offset_1 IN bigint default 1, offset_2 IN bigint default 1) returns int compare(lob_1 IN blob, lob_2 IN blob, amount IN int default 1024*1024*1024-8, offset_1 IN bigint default 1, offset_2 IN bigint default 1) returns int compare(lob_1 IN clob, lob_2 IN clob, amount IN int default (1024*1024*1024-8)/2, offset_1 IN int default 1, offset_2 IN int default 1) returns int #: Compares two entire LOBs or parts of two LOBs. You can only compare LOBs of the same datatype. For bfile and blob, binary comparison is performed. For clob, files are compared according to the current database collation.
append(lob_1 IN OUT blob, lob_2 IN blob) append(lob_1 IN OUT clob, lob_2 IN clob) #: Appends the contents of a source internal LOB to a destination LOB. It appends the complete source LOB.
copy(dest_lob IN OUT blob, src_lob IN blob, amount IN bigint, dest_offset IN bigint default 1, src_offset IN bigint default 1) returns int copy(dest_lob IN OUT clob, src_lob IN clob, amount IN int, dest_offset IN int default 1, src_offset IN int default 1) returns int #: Copies all, or a part of, a source internal LOB to a destination internal LOB. You can specify the offsets for both the source and destination LOBs, and the number of bytes or characters to copy.
converttoblob(dest_lob IN OUT blob, src_clob IN clob, amount IN int, dest_offset IN OUT bigint, src_offset IN OUT int, blob_csid IN int, lang_context IN OUT int, warning OUT int) #: Reads character data from a source clob, converts the character data to the specified character set, writes the converted data to a destination blob in binary format, and returns the new offsets. Only the UTF-8 encoding is supported.
converttoclob(dest_lob IN OUT clob, src_blob IN blob, amount IN int, dest_offset IN OUT int, src_offset IN OUT bigint, blob_csid IN int, lang_context IN OUT int, warning OUT int) #: Reads binary data from a source blob, converts it into UTF-8 encoding, and writes the converted character data to a destination clob.

F.17.4.5. Legacy API #

fileexists(file_loc IN bfile) returns int #: Finds out if a specified bfile locator points to a file that actually exists on the server file system. Implemented as bfile_fileexists.
fileopen(file_loc IN OUT bfile, open_mode IN int) returns int #: Opens the specified bfile for read-only access. Implemented as bfile_open.
fileisopen(file_loc IN bfile) returns int #: Finds out whether the specified bfile was opened.
loadfromfile(dest_lob IN OUT blob, src_bfile IN bfile, amount IN int default 1024*1024*1024-8, dest_offset IN bigint default 1, src_offset IN bigint default 1) #: Converts data from the specified bfile to blob.
fileclose(file_loc IN OUT bfile) #: Closes the previously opened bfile. Implemented as bfile_close.
filecloseall() #: Closes all bfile files opened in the session. Implemented as bfile_close_all.
filegetname(file_loc IN bfile, dir_alias OUT text, filename OUT text) #: Determines the directory object and filename. This function only indicates the directory object name and filename assigned to the locator, not if the physical file or directory actually exists. Implemented as bfile_directory_get_alias_by_id.

F.17.4.6. Other Operations #

loadblobfromfile(dest_lob IN OUT blob, src_bfile IN bfile, amount IN int default 1024*1024*1024-8, dest_offset IN bigint default 1, src_offset IN bigint default 1) returns int #: Synonym for loadfromfile().
loadclobfromfile(dest_lob IN OUT clob, src_bfile IN bfile, amount IN int, dest_offset IN OUT int, src_offset IN OUT bigint, bfile_csid IN int, lang_context IN OUTint, warning OUTint) #: Loads data from a bfile to an internal clob.
setcontenttype(lob_loc IN OUT blob, contenttype IN text) setcontenttype(lob_loc IN OUT clob, contenttype IN text) #: Sets the content type string associated with the LOB.
getcontenttype(lob_loc IN blob) returns text getcontenttype(lob_loc IN clob) returns text #: Returns the content type string associated with the LOB.
getchunksize(lob_loc IN blob) returns text getchunksize(lob_loc IN clob) returns text #: Returns the amount of space used in the LOB chunk to store the LOB value.

F.17.5. Example #

DO
$$
DECLARE
  cur_clob  dbms_lob.clob;
  buffer    text;
  amount    int := 3000;
BEGIN
  cur_clob := dbms_lob.empty_clob();
  cur_clob.t := 'just some sample text';
  raise notice 'clob length: %', dbms_lob.getlength(cur_clob);
  call dbms_lob.read(cur_clob, amount, 1, buffer);
  raise notice 'all clob read: %', buffer;
  amount := 6;
  call dbms_lob.read(cur_clob, amount, 4, buffer);
  raise notice 'clob read from 4 position for 6 symbols: %', buffer;
  raise notice 'storage limit: %', dbms_lob.get_storage_limit(cur_clob);
  raise notice 'clob substr from 6 position for 8 symbols: %', dbms_lob.substr(cur_clob, 8, 6);
  raise notice 'third postion of letter s in clob: %', dbms_lob.instr(cur_clob, 's', 1, 3);

  call dbms_lob.write(cur_clob, 6, 4, 'foobar');
  raise notice 'new clob contents: %', cur_clob.t;
  call dbms_lob.write(cur_clob, 3, 25, 'baz');
  raise notice 'new clob contents: %', cur_clob.t;

  call dbms_lob.writeappend(cur_clob, 4, 'test');
  raise notice 'new clob contents: %', cur_clob.t;

  amount := 3;
  call dbms_lob.erase(cur_clob, amount, 2);
  raise notice 'amount of symbols deleted: %', amount;
  raise notice 'new clob contents: %', cur_clob.t;
  call dbms_lob.erase(cur_clob, amount, 30);
  raise notice 'amount of symbols deleted: %', amount;
  raise notice 'new clob contents: %', cur_clob.t;

  call dbms_lob.trim_(cur_clob, 22);
  raise notice 'new clob contents: %', cur_clob.t;
END;
$$;
--output
NOTICE:  clob length: 21
NOTICE:  all clob read: just some sample text
NOTICE:  clob read from 4 position for 6 symbols: t some
NOTICE:  storage limit: 536870908
NOTICE:  clob substr from 6 position for 8 symbols: some sam
NOTICE:  third postion of letter s in clob: 11
NOTICE:  new clob contents: jusfoobar sample text
NOTICE:  new clob contents: jusfoobar sample text   baz
NOTICE:  new clob contents: jusfoobar sample text   baztest
NOTICE:  amount of symbols deleted: 3
NOTICE:  new clob contents: j   oobar sample text   baztest
NOTICE:  amount of symbols deleted: 2
NOTICE:  new clob contents: j   oobar sample text   bazte
NOTICE:  new clob contents: j   oobar sample text

Prev	Up	Next
dblink_build_sql_update	Home	F.18. dict_int — example full-text search dictionary for integers