OCILIB (C and C++ Driver for Oracle)  4.1.0
ocilib::Lob< TLobObjectType, TLobOracleType > 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...
 
TLobObjectType Read (unsigned int length)
 Read a portion of a lob. More...
 
unsigned int Write (const TLobObjectType &content)
 Write the given content at the current position within the lob. More...
 
unsigned int Append (const TLobObjectType &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.
 
Loboperator+= (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 TLobObjectType, int TLobOracleType>
class ocilib::Lob< TLobObjectType, TLobOracleType >

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 3787 of file ocilib.hpp.

Constructor & Destructor Documentation

template<class TLobObjectType , int TLobOracleType>
ocilib::Lob< TLobObjectType, TLobOracleType >::Lob ( const Connection connection)
inline

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 2635 of file ocilib_impl.hpp.

References ocilib::Check(), OCI_LobCreate(), and OCI_LobFree().

Member Function Documentation

template<class TLobObjectType, int TLobOracleType>
TLobObjectType ocilib::Lob< TLobObjectType, TLobOracleType >::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
template<class TLobObjectType , int TLobOracleType>
unsigned int ocilib::Lob< TLobObjectType, TLobOracleType >::Write ( const TLobObjectType &  content)
inline

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 2677 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
unsigned int ocilib::Lob< TLobObjectType, TLobOracleType >::Append ( const TLobObjectType &  content)
inline

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 2696 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
void ocilib::Lob< TLobObjectType, TLobOracleType >::Append ( const Lob< TLobObjectType, TLobOracleType > &  other)
inline

Append the given lob content to the lob.

Parameters
other- source lob

Definition at line 2690 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
bool ocilib::Lob< TLobObjectType, TLobOracleType >::Seek ( SeekMode  seekMode,
big_uint  offset 
)
inline

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 2709 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
big_uint ocilib::Lob< TLobObjectType, TLobOracleType >::GetChunkSize ( ) const
inline

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 2755 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
void ocilib::Lob< TLobObjectType, TLobOracleType >::Truncate ( big_uint  length)
inline

Truncate the lob to a shorter length.

Parameters
length- New length in characters or bytes

Definition at line 2767 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
big_uint ocilib::Lob< TLobObjectType, TLobOracleType >::Erase ( big_uint  offset,
big_uint  length 
)
inline

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 2773 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
void ocilib::Lob< TLobObjectType, TLobOracleType >::Copy ( Lob< TLobObjectType, TLobOracleType > &  dest,
big_uint  offset,
big_uint  offsetDest,
big_uint  length 
) const
inline

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 2779 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
void ocilib::Lob< TLobObjectType, TLobOracleType >::Open ( OpenMode  mode)
inline

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 2791 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
void ocilib::Lob< TLobObjectType, TLobOracleType >::Close ( )
inline

Close explicitly a Lob.

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

Definition at line 2803 of file ocilib_impl.hpp.

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

template<class TLobObjectType , int TLobOracleType>
void ocilib::Lob< TLobObjectType, TLobOracleType >::EnableBuffering ( bool  value)
inline

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 2809 of file ocilib_impl.hpp.

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