ora-lob-get-buffer

ora-lob-get-buffer Function

Summary

Gets a buffer for efficient I/O with foreign functions.

Package

sql

Signature

ora-lob-get-buffer lob-locator &key for-writing offset => amount/size, foreign-buffer, eof-or-error-p

Arguments

`lob-locator`⇩	A LOB locator.
`for-writing`⇩	A generalized boolean.
`offset`⇩	A non-negative integer or `nil`.

Values

`amount/size`⇩	A non-negative integer.
`foreign-buffer`⇩	A FLI pointer.
`eof-or-error-p`⇩	A boolean or an error object.

Description

The function ora-lob-get-buffer gets a buffer from lob-locator for efficient I/O with foreign functions.

If for-writing is nil, then ora-lob-get-buffer fills an internal buffer and returns three values: amount/size is how much it filled, foreign-buffer points to the actual buffer, and eof-or-error-p is the return value from the call to ora-lob-read-foreign-buffer. The offset offset is passed directly ora-lob-read-foreign-buffer.

If for-writing is true, then ora-lob-get-buffer returns two values: amount/size is the size of the foreign buffer and foreign-buffer points to the actual buffer, which then can be passed to ora-lob-write-foreign-buffer.

The default value of for-writing is nil.

The buffer that is used by ora-lob-get-buffer is always the same for the LOB locator, it is used by ora-lob-read-buffer and ora-lob-write-buffer, and is freed automatically when the LOB locator is freed. Thus until you finish with the buffer, you cannot use ora-lob-read-buffer or ora-lob-write-buffer or call ora-lob-get-buffer again or free the LOB locator.

Notes

ora-lob-get-buffer is available only when the "oracle" module is loaded. See the section 23.11 Oracle LOB interface for more information.

Examples

This first example illustrates reading using the buffer obtained by ora-lob-get-buffer. You have a foreign function:

my_chunk_processor(char *data, int size)

with this FLI definition:

(fli:define-foreign-function my_chunk_processor
    ((data :pointer)
     (size :int)))

You can pass all the data from the LOB locator to this function. Assuming no other function reads from it, it will start from the beginning.

(loop
 (multiple-value-bind (amount buffer eof-or-error-p)
     (ora-lob-get-buffer lob)
   (when (zerop amount) (return))
   (my_chunk_processor buffer amount ))

This second example illustrates writing with the buffer obtained by ora-lob-get-buffer. You have a foreign function that fills a buffer with data, and you want to write it to a LOB. First you should lock the record, and if required trim the LOB locator.

(multiple-value-bind (size buffer)
    (ora-lob-get-buffer lob-locator
                        :for-writing t
                        ;; start at the beginning
                        :offset 1)    
  (loop (let ((amount (my-fill-buffer buffer size)))
          (when (zerop amount) (return))
          (ora-lob-write-foreign-buffer 
           lob-locator nil
           amount buffer size))))