Release 9.2.0.4
Part Number B10961-01
 Contents |
 Index |
| Oracle® Data Provider for .NET Developer's Guide Release 9.2.0.4 Part Number B10961-01 |
|
Oracle.DataAccess.Types Namespace (ODP.NET Types), 14 of 19
An OracleBFile is an object that has a reference to BFILE data. It provides methods for performing operations on BFiles.
Object
MarshalByRefObject
Stream
OracleBFile
// C# public sealed class OracleBFile : Stream, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
OracleBFile is supported for applications running against Oracle8.x and higher.
[C#] ... // assume: // 1. A valid connection is made // 2. contains a file c:\MyDir\MyFile.txt OracleBFile oraBFile = new OracleBFile(con, "c:\\MyDir", "MyFile.txt"); // Open the oraBFile oraBFile.Open(); // Read some data ... int byteRead = oraBFile.Read(buffer, bufferOffset, amountToBeRead); // Search for the 2nd occurrence of a byte pattern '123' // from oraBFile starting at offset 1 byte[] pattern = new byte[3] { 1,2,3 }; int positionFound = oraBFile.Search(pattern, 1, 2); // Close the BFile oraBFile.CloseFile(); ...
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
OracleBFile members are listed in the following tables:
OracleBFile constructors are listed in Table 5-147.
| Constructor | Description |
|---|---|
|
Creates an instance of the |
OracleBFile static fields are listed in Table 5-148.
| Field | Description |
|---|---|
|
The static field holds the maximum number of bytes a |
OracleBFile static methods are listed in Table 5-149.
| Methods | Description |
|---|---|
|
|
Inherited from |
OracleBFile instance properties are listed in Table 5-150.
OracleBFile instance methods are listed in Table 5-151.
OracleBFile constructors create new instances of the OracleBFile class.
This constructor creates an instance of the OracleBFile class with an OracleConnection object.
This constructor creates an instance of the OracleBFile class with an OracleConnection object, the location of the BFILE, and the name of the BFILE.
This constructor creates an instance of the OracleBFile class with an OracleConnection object.
// C# public OracleBFile(OracleConnection con);
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The connection must be opened explicitly by the application. OracleBFile does not open the connection implicitly.
This constructor creates an instance of the OracleBFile class with an OracleConnection object, the location of the BFILE, and the name of the BFILE.
// C# public OracleBFile(OracleConnection con, string directoryName, string fileName);
con
The OracleConnection object.
directoryName
The directory alias created by the CREATE DIRECTORY SQL statement.
fileName
The name of the external LOB.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The OracleConnection must be opened explicitly by the application. OracleBFile does not open the connection implicitly.
To initialize a BFILE column using an OracleBFile instance as an input parameter of a SQL INSERT statement, directoryName and fileName must be properly set.
OracleBFile static fields are listed in Table 5-152.
| Field | Description |
|---|---|
|
The static field holds the maximum number of bytes a |
This static field holds the maximum number of bytes a BFILE can hold, which is 4,294,967,295 (2^32 - 1) bytes.
// C# public static readonly Int64 MaxSize = 4294967295;
This field is useful in code that checks whether the operation exceeds the maximum length allowed.
OracleBFile static methods are listed in Table 5-153.
| Methods | Description |
|---|---|
|
|
Inherited from |
OracleBFile instance properties are listed in Table 5-154.
Overrides Stream
This instance property indicates whether the LOB stream can be read.
// C# public override bool CanRead{get;}
If the LOB stream can be read, returns true; otherwise, returns false.
Overrides Stream
This instance property indicates whether forward and backward seek operations can be performed.
// C# public override bool CanSeek{get;}
If forward and backward seek operations can be performed, returns true; otherwise, returns false.
Overrides Stream
This instance property indicates whether the LOB object supports writing.
// C# public override bool CanWrite{get;}
BFILE is read only.
BFILE is read-only, therefore, the boolean value is always false.
This instance property indicates the connection used to read from a BFILE.
// C# public OracleConnection Connection {get;}
An object of OracleConnection.
ObjectDisposedException - The object is already disposed.
This instance property indicates the directory alias of the BFILE.
// C# public string DirectoryName {get;set;}
A string.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The value of the DirectoryName changed while the BFILE is open.
The maximum length of a DirectoryName is 30 bytes.
This instance property indicates whether or not the BFILE specified by the DirectoryName and FileName exists.
// C# public bool FileExists {get;}
bool
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Unless a connection, file name, and directory name are provided, this property is set to false by default.
This instance property indicates the name of the BFILE.
// C# public string FileName {get;set}
A string that contains the BFILE name.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The value of the DirectoryName changed while the BFILE is open.
The maximum length of a FileName is 255 bytes.
Changing the FileName property while the BFILE object is opened causes an exception.
This instance property indicates whether the BFILE is empty or not.
// C# public bool IsEmpty {get;}
bool
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the BFILE has been opened by this instance or not.
// C# public bool IsOpen {get;}
A bool.
Overrides Stream
This instance property indicates the size of the BFILE data in bytes.
// C# public override Int64 Length {get;}
Int64
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Overrides Stream
This instance property indicates the current read position in the LOB stream.
// C# public override Int64 Position{get; set;}
An Int64 value that indicates the read position.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The value is less than 0.
This instance property returns the data, starting from the first byte in BFILE, as a byte array.
// C# public byte[] Value{get;}
A byte array.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The length of data is bound by the maximum length of the byte array. The current value of the Position property is not used or changed.
OracleBFile instance methods are listed in Table 5-155.
This instance method creates a copy of an OracleBFile object.
// C# public object Clone();
An OracleBFile object.
ICloneable
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The cloned object has the same property values as that of the object being cloned.
// C# ... //Need a proper casting for the return value when cloned OracleBFile oraBfile_cloned = (OracleBFile) oraBfile.Clone(); ...
Overrides Stream
This instance method closes the current stream and releases any resources associated with it.
// C# public override void Close();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This instance method closes the BFILE referenced by the current BFILE instance.
// C# public void CloseFile();
No error is returned if the BFILE exists, but is not opened.
This instance method compares data referenced by the two OracleBFiles.
// C# public int Compare(Int64 src_offset, OracleBFile obj, Int64 dst_offset, Int64 amount);
src_offset
The offset of the current instance.
obj
The provided OracleBFile object.
dst_offset
The offset of the OracleBFile object.
amount
The number of bytes to compare.
Returns a number that is:
BFILE data of the current instance is less than that of the provided BFILE data.
BFILEs store the same data.
BFILE data of the current instance is greater than that of the provided BFILE data.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount is less than 0.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
The BFILE needs to be opened using OpenFile before the operation.
// C# ... // Assume you have 2 valid files in C:\MyDir OracleBFile myBFile1 = new OracleBFile(con, "c:\\MyDir", "MyFile1.txt"); OracleBFile myBFile2 = new OracleBFile(con, "c:\\MyDir", "MyFile2.txt"); int src_offset = 10; int dst_offset = 20; int amount = 5; int result = myBFile1.Compare(src_offset, myBFile2, dst_offset, amount); if ( result == 0 ) Console.WriteLine("Identical"); else Console.WriteLine("Not Identical"); ...
CopyTo copies data from the current instance to the provided object.
This instance method copies data from the current instance to the provided OracleBlob object.
This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified destination offset.
This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified destination offset.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified source offset, destination offset, and amount of characters.
This instance method copies data from the current instance to the provided OracleBlob object.
// C# public Int64 CopyTo(OracleBlob obj);
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.
This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified destination offset.
// C# public Int64 CopyTo(OracleBlob obj, Int64 dst_offset);
obj
The OracleBlob object to which the data is copied.
dst_offset
The offset (in bytes) at which the OracleBlob object is copied.
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
ArgumentOutOfRangeException - The dst_offset is less than 0.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
If the dst_offset is beyond the end of the OracleBlob data, spaces are written into the OracleBlob until the dst_offset is met.
The offsets are 0-based. No character conversion is performed by this operation.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.
This instance method copies data from the current OracleBFile instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts.
// C# public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset, Int64 amount);
src_offset
The offset (in bytes) in the current instance, from which the data is read.
obj
An OracleBlob object to which the data is copied.
dst_offset
The offset (in bytes) to which the OracleBlob object is copied.
amount
The amount of data to be copied.
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount is less than 0.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
If the dst_offset is beyond the end of the OracleBlob data, spaces are written into the OracleBlob until the dst_offset is met.
The offsets are 0-based. No character conversion is performed by this operation.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object.
// C# public Int64 CopyTo(OracleClob obj);
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified destination offset.
// C# public Int64 CopyTo(OracleClob obj, Int64 dst_offset);
obj
The OracleClob object that the data is copied to.
dst_offset
The offset (in characters) at which the OracleClob object is copied to.
The amount copied.
ObjectDisposedException - The object is already disposed.
ArgumentOutOfRangeException - The dst_offset is less than 0.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
If the dst_offset is beyond the end of the OracleClob data, spaces are written into the OracleClob until the dst_offset is met.
The offsets are 0-based. No character conversion is performed by this operation.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object with the specified source offset, destination offset, and amount of characters.
// C# public Int64 CopyTo(Int64 src_offset,OracleClob obj,Int64 dst_offset,Int64 amount);
src_offset
The offset (in characters) in the current instance, from which the data is read.
obj
An OracleClob object that the data is copied to.
dst_offset
The offset (in characters) at which the OracleClob object is copied to.
amount
The amount of data to be copied.
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount is less than 0.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
If the dst_offset is beyond the end of the current OracleClob data, spaces are written into the OracleClob until the dst_offset is met.
The offsets are 0-based. No character conversion is performed by this operation.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
This instance method releases resources allocated by this object.
// C# public void Dispose();
IDisposable
Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls may lead to exceptions. The object cannot be reused after being disposed.
This instance method compares the LOB references.
// C# public bool IsEqual(OracleBFile obj);
Returns true if the current OracleBFile and the provided OracleBFile object refer to the same external LOB. Returns false otherwise.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Note that this method can return true even if the two OracleBFile objects return false for == or Equals() since two different OracleBFile instances can refer to the same external LOB.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.
This instance method opens the BFILE specified by the FileName and DirectoryName.
// C# public void OpenFile();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Many operations, such as Compare(), CopyTo(), Read(), and Search() require that the BFILE be opened using OpenFile before the operation.
Calling OpenFile on an opened BFILE is not operational.
Overrides Stream
This instance method reads a specified amount of bytes from the OracleBFile instance and populates the buffer.
// C# public override int Read(byte[ ] buffer, int offset, int count);
buffer
The byte array buffer to be populated.
offset
The offset of the byte array buffer to be populated.
count
The amount of bytes to read.
The return value indicates the number of bytes read from the BFILE, that is, the external LOB.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - Either the offset or the count parameter is less than 0 or the offset is greater than or equal to the buffer.Length or the offset and the count together are greater than buffer.Length.
The LOB data is read starting from the position specified by the Position property.
// C# ... byte buffer = new byte[1024]; int bufferOffset = 10; int amountToBeRead = 10; // Read some data int byteRead = oraBFile.Read(buffer, bufferOffset, amountToBeRead); ...
This instance method searches for a binary pattern in the current instance of an OracleBFile.
// C# public int Search(byte[ ] val, Int64 offset, Int64 nth);
val
The binary pattern being searched for.
offset
The 0-based offset (in bytes) starting from which the OracleBFile is searched.
nth
The specific occurrence (1-based) of the match for which the offset is returned.
Returns the absolute offset of the start of the matched pattern (in bytes) for the nth occurrence of the match. Otherwise, 0 is returned.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - Either the offset is less than 0 or nth is less than or equal to 0 or val.Length is greater than 16383 or nth is greater than or equal to OracleBFile.MaxSize or offset is greater than or equal to OracleBFile.MaxSize.
The limit of the search pattern is 16383 bytes.
// C# ... // Search for the 2nd occurrence of a byte pattern '123' // from oraBFile starting at offset 1 byte[] pattern = new byte[3] { 1,2,3 }; int positionFound = oraBFile.Search(pattern, 1, 2); ...
Overrides Stream
This instance method sets the position on the current LOB stream.
// C# public override int64 Seek(Int64 offset, SeekOrigin origin);
offset
A byte offset relative to origin.
origin
A value of type System.IO.SeekOrigin indicating the reference point used to obtain the new position.
Returns an Int64 that indicates the position.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
If offset is negative, the new position precedes the position specified by origin by the number of bytes specified by offset.
If offset is zero, the new position is the position specified by origin.
If offset is positive, the new position follows the position specified by origin by the number of bytes specified by offset.
SeekOrigin.Begin specifies the beginning of a stream.
SeekOrigin.Current specifies the current position within a stream.
SeekOrigin.End specifies the end of a stream.
// C# ... // Set the Position to 5 bytes (with respect to SeekOrigin.Begin), read 10 bytes // out, and put the data in a buffer with offset = 10 bytes byte buffer = new byte[1024]; int bufferOffset = 10; int amountToBeRead = 10; // Seek int newPosition = oraBFile.Seek(5, SeekOrigin.Begin); // Read some data int byteRead = oraBFile.Read(buffer, bufferOffset, amountToBeRead); ...
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|