Skip Headers

Oracle® C++ Call Interface Programmer's Guide
10g Release 1 (10.1)

Part Number B10778-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

Bfile Class

The Bfile class defines the common properties of objects of type BFILE. A BFILE is a large binary file stored in an operating system file outside of the Oracle database. A Bfile object contains a logical pointer to a BFILE, not the BFILE itself.

Methods of the Bfile class enable you to perform specific tasks related to Bfile objects.

Methods of the ResultSet and Statement classes, such as getBfile() and setBfile(), enable you to access an SQL BFILE value.

The only methods valid on a NULL Bfile object are setName(), isNull(), and operator=() .

An uninitialized Bfile object can be initialized by:


See Also:


Table 10-5 Summary of Bfile Methods

Method Summary
Bfile()
Bfile class constructor.
close()
Close a previously opened BFILE.
closeStream()
Close the stream obtained from the BFILE.
fileExists()
Test whether the BFILE exists.
getDirAlias()
Return the directory object of the BFILE.
getFileName()
Return the name of the BFILE.
getStream()
Return data from the BFILE as a Stream object.
getUStringDirAlias()
Return a UString containing the directory object associated with the BFILE.
getUStringFileName()
Return a UString containing the file name associated with the BFILE.
isInitialized()
Test whether the Bfile object is initialized.
isNull()
Test whether the Bfile object is atomically NULL.
isOpen()
Test whether the BFILE is open.
length()
Return the number of bytes in the BFILE.
open()
Open the BFILE with read-only access.
operator=()
Assign a BFILE locator to the Bfile object.
operator==()
Test whether two Bfile objects are equal.
operator!=()
Test whether two Bfile objects are not equal.
operator==()
Read a specified portion of the BFILE into a buffer.
setName()
Set the directory object and file name of the BFILE.
setNull()
Set the Bfile object to atomically NULL.


Bfile()

Bfile class constructor.

Syntax Description
Bfile();
Creates a NULL Bfile object.
Bfile(
   const Connection *connectionp);
Create an uninitialized Bfile object.
Bfile(
   const Bfile &srcBfile);
Create a copy of a Bfile object.

Parameter Description
connectionp
The connection pointer
srcBfile
The source Bfile object


close()

Closes a previously opened Bfile.


Syntax
void close();


closeStream()

Closes the stream obtained from the Bfile.


Syntax
void closeStream(
   Stream *stream); 
Parameter Description
stream
The stream to ne closed.


fileExists()

Tests whether the BFILE exists. If the BFILE exists, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool fileExists() const;


getDirAlias()

Returns a string containing the directory object associated with the BFILE.


Syntax
string getDirAlias() const;


getFileName()

Returns a string containing the file name associated with the BFILE.


Syntax
string getFileName() const;


getStream()

Returns a Stream object read from the BFILE. If a stream is already open, it is disallowed to open another stream on the Bfile object. The stream must be closed before performing any Bfile object operations.


Syntax
Stream* getStream(
   unsigned int offset = 1,
   unsigned int amount = 0);
Parameter Description
offset
The starting position at which to begin reading data from the BFILE. If offset is not specified, the data is written from the beginning of the BLOB. Valid values are numbers greater than or equal to 1.
amount
The total number of bytes to be read from the BFILE; if amount is 0, the data will be read in a streamed mode from input offset until the end of the BFILE.


getUStringDirAlias()

Return a UString containing the directory object associated with the BFILE.


Note:

The UString object is in UTF16 character set. The environment associated with BFILE should be associated with UTF16 charset.


Syntax
UString getUStringDirAlias() const;

getUStringFileName()

Return a UString containing the file name associated with the BFILE.


Note:

The UString object is in UTF16 charset. The environment associated with BFILE should be associated with UTF16 charset.


Syntax
UString getUStringFileName() const;

isInitialized()

Tests whether the Bfile object has been initialized. If the Bfile object has been initialized, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool isInitialized() const;


isNull()

Tests whether the Bfile object is atomically NULL. If the Bfile object is atomically NULL, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool isNull() const;


isOpen()

Tests whether the BFILE is open. The BFILE is considered to be open only if it was opened by a call on this Bfile object. (A different Bfile object could have opened this file as more than one open can be performed on the same file by associating the file with different Bfile objects). If the BFILE is open, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool isOpen() const;


length()

Returns the number of bytes (inclusive of the end of file marker) in the BFILE.


Syntax
unsigned int length() const;


open()

Opens an existing BFILE for read-only access. This function is meaningful the first time it is called for a Bfile object.


Syntax
void open();


operator=()

Assigns a Bfile object to the current Bfile object. The source Bfile object is assigned to this Bfile object only when this Bfile object gets stored in the database.


Syntax
Bfile& operator=(
   const Bfile &srcBfile);
Parameter Description
srcBfile
The Bfile object to be assigned to the current Bfile object.


operator==()

Compares two Bfile objects for equality. The Bfile objects are equal if they both refer to the same BFILE. If the Bfile objects are NULL, then FALSE is returned. If the Bfile objects are equal, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool operator==(
   const Bfile &srcBfile) const;
Parameter Description
srcBfile
The Bfile object to be compared with the current Bfile object.


operator!=()

Compares two Bfile objects for inequality. The Bfile objects are equal if they both refer to the same BFILE. If the Bfile objects are not equal, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool operator!=(
   const Bfile &srcBfile) const;
Parameter Description
srcBfile
The Bfile object to be compared with the current Bfile object.


read()

Reads a part or all of the BFILE into the buffer specified, and returns the number of bytes read.


Syntax
unsigned int read(
   unsigned int amt,
   unsigned char *buffer,
   unsigned int bufsize,
   unsigned int offset = 1) const;
Parameter Description
amt
The number of bytes to be read. Valid values are numbers greater than or equal to 1.
buffer
The buffer that the BFILE data is to be read into. Valid values are numbers greater than or equal to amt.
buffsize
The size of the buffer that the BFILE data is to be read into. Valid values are numbers greater than or equal to amt.
offset
The starting position at which to begin reading data from the BFILE. If offset is not specified, the data is written from the beginning of the BFILE.


setName()

Sets the directory object and file name of the BFILE.

Syntax Description
void setName(
   const string &dirAlias,
   const string &fileName);
Sets the directory object and file name of the BFILE.
void setName(
   const UString &dirAlias,
   const UString &fileName);
Sets the directory object and file name of the BFILE (Unicode support). The client Environment should be initialized in OCCIUTIF16 mode.

Parameter Description
dirAlias
The directory object to be associated with the BFILE.
fileName
The file name to be associated with the BFILE.


setNull()

Sets the Bfile object to atomically NULL.


Syntax
void setNull();