OCICPP::Lob class Reference

List of all members.

Public Methods
	Lob ()
	Lob (OCISvcCtx svcctx, OCILobLocator lob_desc, OCIError *err, int type, int cache_mode)
void	init (OCISvcCtx svcctx, OCILobLocator lob_desc, OCIError *err, int type, int cache_mode)
void	init (OCIEnv env, OCISvcCtx svcctx, OCIError *err)
	~Lob ()
void	drop ()
void	seek (unsigned offset, int dir)
unsigned	tell ()
unsigned	read (void *buff, int blen)
unsigned	write (const void *buff, int blen)
void	trunc (unsigned new_len)
void	loadFromBFile (BFile &bfile, unsigned int amount, unsigned int dst_offset, unsigned int src_offset)
void	setCacheMode (int mode)
unsigned	getLen () const
void	copyFrom (Lob &src_lob, unsigned amount, unsigned dst_off, unsigned src_off)
void	copyFrom (BFile &src_file, unsigned amount, unsigned dst_off, unsigned src_off)
void	copyFrom (TLob &src_file, unsigned amount, unsigned dst_off, unsigned src_off)
Friends
class	TLob
class	Cursor

Detailed Description

A brief example for interaction with a lob. Lets assume, there is a table IMAGES created already (e.g. by issuing the command "create table IMAGES ( KEY integer, IMAGE blob )". Of course, a storage class should be included, so that the large object(s) can be stored appropriately. After that, you may write (with an initialized pointer con to a Connection-object):

  using namespace OCICPP;

  con->execUpdate( "insert into IMAGES (KEY,IMAGE) values ( 42, EMPTY_BLOB())" );
  Cursor cur;
  con->execQuery( "select * from IMAGES where KEY=42 for update", cur );
  Lob lob;
  cur.fetch();
  cur.getBLOB( "IMAGE", lob );
  lob.write( "something", 9 );
  cur.drop();

In detail, a new row is inserted into the IMAGES table (identified by 42 ). The table, as mentioned above, stores an integer column as well as a binary large object (BLOB) column.

For those of you familiar with Oracle Servers, it may not be an insight that the column IMAGE is initialized with an empty BLOB (by specifying EMPTY_BLOB()/EMPTY_CLOB() as the content of this column). It would be a mistake to leave this content out of the insert statement, since the a NULL-value would be inserted and a NULL-LOB may not be used for reading from or writing to.

Afterwards, the newly inserted column is being selected for update, which is mandatory, if a value from this column is to be modified while the cursor points to it. The Lob-instance lob is being initilized from the Cursor's current column IMAGE and afterwards 'something' is written into this BLOB. Alternatively, a real image or some other binary data may be stored there.

Constructor & Destructor Documentation

OCICPP::Lob::Lob (

)

Create an unbound large object. This object may be used to be initialized from a Cursor's BLOB / CLOB column, e.g..

Member Function Documentation

void OCICPP::Lob::copyFrom (	*TLob & src_lob,*
	*unsigned amount,*
	*unsigned dst_off,*
	*unsigned src_off* )**

Copies data from a temporary Lob src_lob

See also:: copyFrom(Lob &,unsigned,unsigned,unsigned)

This functions is only available for Oracle 8i and above

void OCICPP::Lob::copyFrom (	*BFile & src_file,*
	*unsigned amount,*
	*unsigned dst_off,*
	*unsigned src_off* )**

Copies data from a BFile src_file

See also:: copyFrom(Lob &,unsigned,unsigned,unsigned)

void OCICPP::Lob::copyFrom (	*Lob & src_lob,*
	*unsigned amount,*
	*unsigned dst_off,*
	*unsigned src_off* )**

Copies data from Lob src_lob

Both locators must be of the same type (they are both must be BLOB or CLOB)

Lob cache must not be enabled for either locator.

The amount parameter indicates the maximum amount to copy.

If the end of the source LOB is reached before the specified amount is copied, the operation terminates without error.

See also:: setCacheMode(), getLen(), loadFromBFile()

void OCICPP::Lob::drop (

)

Free a previously initalized large object. A lob freed in this manner may be reused afterwards.

Todo:: not implemented

unsigned OCICPP::Lob::getLen (

) const

Retreive the total amount of data stored within this lob.

void OCICPP::Lob::loadFromBFile (	*BFile & bfile,*
	*unsigned amount,*
	*unsigned int dst_offset,*
	*unsigned int src_offset* )**

Load/copy all or a portion of the file into an internal LOB.

No character set conversions are performed when copying the FILE data to a CLOB/NCLOB.

If the destination's start position is beyond the end of the current data, zero-byte fillers (for BLOBs) or spaces (for CLOBs) are written into the destination LOB from the end of the data to the beginning of the newly written data from the source. The destination LOB is extended to accommodate the newly written data if it extends beyond the current length of the destination LOB.

It is an error to extend the destination LOB beyond the maximum length allowed (4 gigabytes)

The amount parameter indicates the maximum amount to load. If the end of the source FILE is reached before the specified amount is loaded,the operation terminates without error.

unsigned OCICPP::Lob::read (	*void buf,**
	*int buf_len* )**

Read a sequence of buf_len bytes from the lob into the buffer buf. The amount of bytes actually transfered is being returned.

void OCICPP::Lob::seek (	*unsigned new_offset,*
	*int dir* )**

Set the position for reading/writing within a large object.

Parameters:

dir	may be SET, CUR or END . SET new_offset from begining of the lob. new_offset may not be greater than Lob's length ( getLen() ). CUR modifies the access point within the lob relative to the current position. current position + new_offset may not exceed the lob's length END sets the position from the end of the lob.
new_offset	is the new distance relative to the given direction dir

void OCICPP::Lob::setCacheMode (

int mode )

Todo:: not implemented

unsigned OCICPP::Lob::tell (

)

Retuns the current position from the start of the lob. For this position, the inequation 0 <= tell() < getLen() holds.

void OCICPP::Lob::trunc (

unsigned new_len )

Truncates the lob to a specified to a length of new_len bytes. The function throws an exception if new_len is greater than the current LOB's length.

unsigned OCICPP::Lob::write (	*const void buf,**
	*int buf_len* )**

Write a sequence of buf_len bytes into the lob from the buffer buf. The amount of bytes actually transfered is being returned.

OCICPP::Lob Class Reference

Public Methods

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation