---

OCICPP::BFile Class Reference

Binary external Files within the Oracle Server's filesystem. More...

List of all members.

Public Methods
	BFile ()
	BFile (OCISvcCtx *svcctx, OCILobLocator *lob_desc, OCIError *err)
void	init (OCISvcCtx *svcctx, OCILobLocator *lob_desc, OCIError *err)
void	init (OCIEnv *env, OCISvcCtx *,OCIError *err, const string &dir, const string &fname)
	~BFile ()
void	drop ()
void	seek (unsigned offset, int dir)
unsigned	tell ()
void	open ()
void	close ()
unsigned	read (void *buff, int blen)
unsigned	getLen () const
Friends
class	Lob
class	TLob

---

Detailed Description

Binary external Files within the Oracle Server's filesystem.

BFiles are a mean of representing large objects within the Oracle Server. Alternatives are Lob and TLob. The main difference between BFiles od the one side and Lobs and TLobs on the other is, that the BFile does not reside within the database's tablespaces (whereas Lobs and TLobs do). A BFile is located within the server's filesystem and thus has to be accessed there.

Storing data externally has some consequences:

• The operating system is responsible for storing these files
• The is no way the Oracle Server can preserve these files
• Since there is a maximum number of open file handles, one can never be sure to have access to a BFile, even if it exists
• BFiles are (currently?) read-only

On the other hand, there are some advantages:

• The BFile does not populate the database tables (which may resolve in smaller databases)
• BFiles are a mean of separating classical database content (in terms of entities that have a relation) from multimedia data (which typically is a rather large amount of data)

Oracle states, that there is hardly any measurable performace difference between the large-object datatypes Lob, TLob and BFile, which leaves the decission of the type to be used to the user again. However, current policy seems to discourage the usage of BFiles.

However, they can be very useful (according to the documentation writters humble opinion) if used carefully (and even reduce work). Imagine a database storing mainly textual data, where additionally some images or even audio- or video-sequences are incorporated. Lets again assume that the whole application is designed in client-server architecture, so that there is a big database which may be accessed from (many, perhaps browser) clients. BFiles then offer the capability to map data not stored within the database throught the Oracle-Layer to the client, so that there is no need to code a broker of any kind - this leaves one backend less.

Let's look, if there's a Video-Archive identified by ZUSE and retreive the length of the BFILE-column called DATA (Error-Handling within this example is admittedly a little too rought...)

  using namespace OCICPP;

  int len = 0;
  try {
    Cursor cur;
    con->execQuery( "select * from MM_ARCHIVE WHERE TYPE='V' and ID='ZUSE'",
                    cur );
    if ( cur.fetch() ) {
      BFile bfile;
      cur.getFILE( "DATA", bfile );
      bfile.open();
      len = bfile.getLen();
      bfile.close();
      bfile.drop();
    }
    cur.drop();
  } catch ( OraError ) {
  }

For additional information on how to create BFILE entities within the database, please refer to the Oracle Server Documentation (BFILENAME and CREATE DIRECTORY ).

---

Constructor & Destructor Documentation

OCICPP::BFile::BFile ( )

Construct an unbound bfile entity.

OCICPP::BFile::~BFile ( )

Destruct a bfile entity.

---

Member Function Documentation

void OCICPP::BFile::close ( )

Close a previously opened BFile. This operation sets one file handle free again on the Oracle Server again.

void OCICPP::BFile::drop ( )

Drop a BFile entity. The Oracle Descriptior is freed on demand leaving the BFile instance ready for being reused.

unsigned OCICPP::BFile::getLen ( ) const

Retreive the total amount of data stored within this BFile.

void OCICPP::BFile::open ( )

Open a BFile. Before accessing, such a BFile has to be opened. Please keep in mind, that there is maximum number of simultaneously opened file handles withing the Oracle Server process.

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

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

void OCICPP::BFile::seek ( unsigned new_offset, int dir )

Set the position for reading/writing within a bfile. Parameters: dir   may be SET, CUR or END . SET new_offset from begining of the BFile. offset may not be greater than Bfile's length ( getLen() ). CUR modifies the access point within the BFile relative to the current position. current position + offset may not exceed the BFile's length END sets the position from the end of the BFile. new_offset   is the new distance relative to the given direction dir

unsigned OCICPP::BFile::tell ( )

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

---

The documentation for this class was generated from the following files:

• BFile.cpp
• BFile.h

---