Function

Summary

Writes a buffer to a LOB.

Package

sql

Signature

ora-lob-write-buffer lob-locator offset amount buffer &key buffer-offset csid => amount-written, eof-or-error-p

Arguments

lob-locator

A LOB locator.

offset

A non-negative integer or nil.

amount

A non-negative integer.

buffer

A string, or a vector of element type (unsigned-byte 8).

buffer-offset

A non-negative integer.

csid

A.Character Set ID

Values

amount-written

A non-negative integer.

eof-or-error-p

A boolean or an error object.

Description

The function ora-lob-write-buffer writes to the LOB pointed to by lob-locator from buffer.

offset specifies the offset to start writing to. It starts with 1, and specifies characters for CLOB/NCLOB/CFILE and bytes for BLOB/BFILE. If offset is nil then the offset after the end of the previous write operation is used (read operations are ignored). This is especially useful for writing linearly to the LOB.

amount is the amount to write, in characters for CLOB/NCLOB/CFILE and bytes for BLOB/BFILE.

The element type of buffer should match the element type of the LOB locator (see ora-lob-element-type). For this comparison (unsigned-byte 8) and base-char are considered as the same.

If the buffer buffer is not static, there is some additional overhead. For small amounts of data, this is probably insignificant.

buffer-offset specifies where in the buffer to start writing data from. It is an offset in bytes from the beginning of the buffer. The default value of buffer-offset is 0.

csid specifies what Character Set ID the data in the source buffer should be. It defaults to the CSID of the LOB pointed to by lob-locator.

The return value amount-written is the number of elements (characters or bytes) that were written

The LOB is extended as required.

If the return value eof-or-error-p is nil then there is still more to write. If eof-or-error-p is t then it wrote to the end of the LOB. If an error occurred then eof-or-error-p is an error object.

Notes

1. The record from which the LOB came must be locked. See the section Locking.
2. ora-lob-write-buffer is a direct call to OCILobWrite, without callback.
3. ora-lob-write-buffer is available only when the "oracle" module is loaded. See the section Oracle LOB interface for more information.

See also

ora-lob-element-type
ora-lob-write-foreign-buffer