Function

Summary

Reads from a LOB into a buffer.

Package

sql

Signature

ora-lob-read-buffer lob-locator offset amount buffer &key buffer-offset csid => amount-read, 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-read

A non-negative integer.

eof-or-error-p

A boolean or an error object.

Description

The function ora-lob-read-buffer reads into buffer from the LOB pointed to by lob-locator.

offset specifies the offset to start reading from. 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 read operation is used (write operations are ignored). This is especially useful for reading linearly from the LOB.

amount is the amount to read, 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 to put the data. 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 target buffer should be. It defaults to the CSID of the LOB pointed to by lob-locator.

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

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

Notes

1. This is a direct call to OCILobRead, without callback.
2. ora-lob-read-buffer is available only when the "oracle" module is loaded. See the section Oracle LOB interface for more information.

Example

This example sequentially reads the LOB data into a string, starting from offset 10000. It calls a processing function on each chunk of data and then reads in the next chunk starting from where the previous read ended.

(let ((my-buffer (make-string 1000 

                              :element-type 'base-char))

      (offset 10000))

  (loop

   (let ((nread 

          (ora-lob-read-buffer lob-locator

                               offset 

                               1000 

                               my-buffer)))

     (when (zerop nread) ; end of the LOB 

       (return))

     (my-processing-function my-buffer nread))

   (setq offset nil)))   ; so next time it continues

                         ;  from where it finished

See also

ora-lob-element-type
ora-lob-read-foreign-buffer