Oracle® C++ Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10778-01 |
|
|
View PDF |
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:
The setName() method. The BFILE
can then be modified by inserting this BFILE
into the table and then retrieving it using SELECT
... FOR UPDATE.
The write()
method will modify the BFILE
; however, the modified data will be flushed to the table only when the transaction is committed. Note that an insert is not required.
Assigning an initialized Bfile
object to it.
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
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 |
Closes a previously opened Bfile
.
void close();
Closes the stream obtained from the Bfile
.
void closeStream( Stream *stream);
Parameter | Description |
---|---|
stream |
The stream to ne closed. |
Tests whether the BFILE
exists. If the BFILE
exists, then TRUE
is returned; otherwise, FALSE
is returned.
bool fileExists() const;
Returns a string containing the directory object associated with the BFILE
.
string getDirAlias() const;
Returns a string containing the file name associated with the BFILE
.
string getFileName() const;
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.
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 . |
Return a UString
containing the directory object associated with the BFILE
.
Note: TheUString object is in UTF16 character set. The environment associated with BFILE should be associated with UTF16 charset. |
UString getUStringDirAlias() const;
Return a UString
containing the file name associated with the BFILE
.
Note: TheUString object is in UTF16 charset. The environment associated with BFILE should be associated with UTF16 charset. |
UString getUStringFileName() const;
Tests whether the Bfile
object has been initialized. If the Bfile
object has been initialized, then TRUE
is returned; otherwise, FALSE
is returned.
bool isInitialized() const;
Tests whether the Bfile
object is atomically NULL
. If the Bfile
object is atomically NULL
, then TRUE
is returned; otherwise, FALSE
is returned.
bool isNull() const;
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.
bool isOpen() const;
Returns the number of bytes (inclusive of the end of file marker) in the BFILE
.
unsigned int length() const;
Opens an existing BFILE
for read-only access. This function is meaningful the first time it is called for a Bfile
object.
void open();
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.
Bfile& operator=( const Bfile &srcBfile);
Parameter | Description |
---|---|
srcBfile |
The Bfile object to be assigned to the current Bfile object. |
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.
bool operator==( const Bfile &srcBfile) const;
Parameter | Description |
---|---|
srcBfile |
The Bfile object to be compared with the current Bfile object. |
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.
bool operator!=( const Bfile &srcBfile) const;
Parameter | Description |
---|---|
srcBfile |
The Bfile object to be compared with the current Bfile object. |
Reads a part or all of the BFILE
into the buffer specified, and returns the number of bytes read.
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 . |
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 . |
Sets the Bfile object
to atomically NULL
.
void setNull();