ocilib::Lob< T, U > Class Template Reference

Object identifying the SQL data type LOB (CLOB, NCLOB and BLOB) More...

`#include <ocilib.hpp>`

Inherits ocilib::HandleHolder< OCI_Lob *>.

## Public Member Functions

| Lob ()
| Create an empty null Lob instance.
| Lob (const Connection &connection)
| Parametrized constructor. More...
T | Read (unsigned int length)
| Read a portion of a lob. More...
unsigned int | Write (const T &content)
| Write the given content at the current position within the lob. More...
unsigned int | Append (const T &content)
| Append the given content to the lob. More...
void | Append (const Lob &other)
| Append the given lob content to the lob. More...
bool | Seek (SeekMode seekMode, big_uint offset)
| Move the current position within the lob for read/write operations. More...
LobType | GetType () const
| return the type of lob
big_uint | GetOffset () const
| Returns the current R/W offset within the lob.
big_uint | GetLength () const
| Returns the number of characters or bytes contained in the lob.
big_uint | GetMaxSize () const
| Returns the lob maximum possible size.
big_uint | GetChunkSize () const
| Returns the current lob chunk size. More...
Connection | GetConnection () const
| Return the lob parent connection.
void | Truncate (big_uint length)
| Truncate the lob to a shorter length. More...
big_uint | Erase (big_uint offset, big_uint length)
| Erase a portion of the lob at a given position. More...
void | Copy (Lob &dest, big_uint offset, big_uint offsetDest, big_uint length) const
| Copy the given portion of the lob content to another one. More...
bool | IsTemporary () const
| Check if the given lob is a temporary lob.
void | Open (OpenMode mode)
| Open explicitly a Lob. More...
void | Flush ()
| Flush the lob content to the server (if applicable)
void | Close ()
| Close explicitly a Lob. More...
void | EnableBuffering (bool value)
| Enable / disable buffering mode on the given lob object. More...
Lob | Clone () const
| Clone the current instance to a new one performing deep copy.
Lob & | operator+= (const Lob &other)
| Appending the given lob content to the current lob content.
bool | operator== (const Lob &other) const
| Indicates if the current lob value is equal to the given lob value.
bool | operator!= (const Lob &other) const
| Indicates if the current lob value is not equal the given lob value.

## Detailed Description

### template<class T, int U>
class ocilib::Lob< T, U >

Object identifying the SQL data type LOB (CLOB, NCLOB and BLOB)

This class wraps the OCILIB object handle OCI_Lob and its related methods

Definition at line 4019 of file ocilib.hpp.

## Constructor & Destructor Documentation

## Lob()

template<class T , int U>

ocilib::Lob< T, U >::Lob | ( | const Connection & | connection | ) |

Parametrized constructor.

Parameters

  connection | - Parent connection

Note
  the lob object must not be accessed anymore once the parent connection object gets out of scope

Definition at line 3000 of file ocilib_impl.hpp.

References ocilib::Check(), ocilib::Lob< T, U >::Lob(), ocilib::MakeRaw(), ocilib::MakeString(), OCI_LobCreate(), OCI_LobFree(), OCI_LobRead(), and ocilib::Lob< T, U >::Read().

## Member Function Documentation

## Read()

template<class T, int U>

T ocilib::Lob< T, U >::Read | ( | unsigned int | length | ) |

Read a portion of a lob.

Parameters

  length | - Maximum number of characters or bytes to read

Returns
  The content read from the lob

Referenced by ocilib::Lob< T, U >::Lob().

## Write()

template<class T , int U>

unsigned int ocilib::Lob< T, U >::Write | ( | const T & | content | ) |

Write the given content at the current position within the lob.

Parameters

  content | - content to write

Returns
  Number of character or bytes written into the lob

Definition at line 3042 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobWrite().

## Append() [1/2]

template<class T , int U>

unsigned int ocilib::Lob< T, U >::Append | ( | const T & | content | ) |

Append the given content to the lob.

Parameters

  content | - content to write

Returns
  Number of character or bytes written into the lob

Definition at line 3061 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobAppend().

## Append() [2/2]

template<class T , int U>

void ocilib::Lob< T, U >::Append | ( | const Lob< T, U > & | other | ) |

Append the given lob content to the lob.

Parameters

  other | - source lob

Definition at line 3055 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobAppendLob().

## Seek()

template<class T , int U>

bool ocilib::Lob< T, U >::Seek | ( | SeekMode | seekMode,
|  | big_uint | offset
| ) |  |

Move the current position within the lob for read/write operations.

Parameters

  seekMode | - Seek mode
  offset | - offset from current position

Note
  Positions start at 0.

Returns
  true on success otherwise false

Definition at line 3074 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobSeek().

## GetChunkSize()

template<class T , int U>

big_uint ocilib::Lob< T, U >::GetChunkSize | ( |  | ) | const

Returns the current lob chunk size.

Note
  This chunk size corresponds to the chunk size used by the LOB data layer when accessing and modifying the LOB value. According to Oracle documentation, performance will be improved if the application issues read or write requests using a multiple of this chunk size

Definition at line 3120 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobGetChunkSize().

## Truncate()

template<class T , int U>

void ocilib::Lob< T, U >::Truncate | ( | big_uint | length | ) |

Truncate the lob to a shorter length.

Parameters

  length | - New length in characters or bytes

Definition at line 3132 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobTruncate().

## Erase()

template<class T , int U>

big_uint ocilib::Lob< T, U >::Erase | ( | big_uint | offset,
|  | big_uint | length
| ) |  |

Erase a portion of the lob at a given position.

Parameters

  offset | - Absolute position in source lob
  length | - Number of bytes or characters to erase

Note
  Absolute position starts at 0. Erasing means that space or null values overwrite the existing LOB value.

Returns
  Number of characters or bytes erased

Definition at line 3138 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobErase().

## Copy()

template<class T , int U>

void ocilib::Lob< T, U >::Copy | ( | Lob< T, U > & | dest,
|  | big_uint | offset,
|  | big_uint | offsetDest,
|  | big_uint | length
| ) |  | const

Copy the given portion of the lob content to another one.

Parameters

  dest | - Destination lob
  offset | - Absolute position in the lob
  offsetDest | - Absolute position in the destination lob
  length | - Number of characters or bytes to copy

Note
  Absolute position starts at 0.

Definition at line 3144 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobCopy().

## Open()

template<class T , int U>

void ocilib::Lob< T, U >::Open | ( | OpenMode | mode | ) |

Open explicitly a Lob.

Parameters

  mode | - open mode

Note
  - A call to Open() is not necessary to manipulate a Lob.
  - If a lob hasn't been opened explicitly, triggers are fired and indexes updated at every read/write/append operation

Definition at line 3156 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobOpen().

## Close()

template<class T , int U>

void ocilib::Lob< T, U >::Close | ( |  | ) |

Close explicitly a Lob.

Note
  - A call to Close() is not necessary to manipulate a Lob.

Definition at line 3168 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobClose().

## EnableBuffering()

template<class T , int U>

void ocilib::Lob< T, U >::EnableBuffering | ( | bool | value | ) |

Enable / disable buffering mode on the given lob object.

Parameters

  value | - Enable/disable buffering mode

Note
  Oracle "LOB Buffering Subsystem" allows client applications to speedup read/write of small buffers on Lobs Objects. Check Oracle Documentation for more details on "LOB Buffering Subsystem". This reduces the number of network round trips and LOB versions, thereby improving LOB performance significantly.

Warning
  According to Oracle documentation the following operations are not permitted on Lobs when buffering is on : Copy(), Append(), Erase(), GetLength(), Truncate()

Definition at line 3174 of file ocilib_impl.hpp.

References ocilib::Check(), and OCI_LobEnableBuffering().