Release 9.2.0.2
Part Number A96160-01
 Contents |
 Index |
| Oracle Data Provider for .NET Developer's Guide Release 9.2.0.2 Part Number A96160-01 |
|
Oracle.DataAccess.Types Namespace (ODP.NET Types), 15 of 17
An OracleBlob object is an object that has a reference to BLOB data. It provides methods for performing operations on BLOBs.
Object
MarshalByRefObject
Stream
OracleBlob
// C# public sealed class OracleBlob : Stream, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
[C#] ... // assume: A valid connection is made OracleBlob oraBlob = new OracleBlob(con); // Read some data ... int byteRead = oraBlob.Read(buffer, bufferOffset, amountToBeRead); // Search for the 2nd occurrence of a byte pattern '123' // from the oraBlob starting at offset 1 byte[] pattern = new byte[3] { 1,2,3 }; int positionFound = oraBlob.Search(pattern, 1, 2); // Append 2 bytes {4,5} to the oraBlob oraBlob.Append(new byte[3] {4,5,6}, 1, 2); // Write 64 bytes, starting at buffer offset 512 byte[4096] buffer = new byte[4096]; ... oraBlob.Write(buffer, 512, 64); // Erase 64 bytes of data starting at offset=1024 oraBlob.Erase(1024,64); ...
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccesss.dll
OracleBlob members are listed in the following tables:
OracleBlob constructors are listed in Table 5-156.
| Constructor | Description |
|---|---|
|
Creates an instance of the |
OracleBlob static fields are listed in Table 5-157.
| Field | Description |
|---|---|
|
Holds the maximum number of bytes a |
OracleBlob static methods are listed in Table 5-158.
| Methods | Description |
|---|---|
|
|
Inherited from |
OracleBlob instance properties are listed in Table 5-159.
OracleBlob instance methods are listed in Table 5-160.
OracleBlob constructors are listed in Table 5-156.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object.
// C# public OracleBlob(OracleConnection con);
InvalidOperationException - The OracleConnection is not opened.
The connection must be opened explicitly by the application. OracleBlob does not open the connection implicitly.
The temporary BLOB utilizes the provided connection to store BLOB data. Caching is not turned on by this constructor.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching.
// C# public OracleBlob(OracleConnection con, bool bCaching);
InvalidOperationException - The OracleConnection is not opened.
The connection must be opened explicitly by the application. OracleBlob does not open the connection implicitly.
The temporary BLOB uses the provided connection to store BLOB data. The bCaching input parameter determines whether or not server-side caching is used.
OracleBlob static fields are listed in Table 5-161.
| Field | Description |
|---|---|
|
Holds the maximum number of bytes a |
The MaxSize field holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes.
// C# public static readonly Int64 MaxSize = 4294967295;
This field can be useful in code that checks whether the operation exceeds the maximum length allowed.
OracleBlob static methods are listed in Table 5-162.
| Methods | Description |
|---|---|
|
|
Inherited from |
OracleBlob instance properties are listed in Table 5-163.
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;}
If the LOB stream can be written, returns true; otherwise, returns false.
This instance property indicates the OracleConnection that is used to retrieve and write BLOB data.
// C# public OracleConnection Connection {get;}
An object of OracleConnection.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the BLOB is empty or not.
// C# public bool IsEmpty {get;}
A bool that indicates whether the BLOB is empty.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the BLOB has been opened to defer index updates.
// C# public bool IsInChunkWriteMode{get;}
If the BLOB has been opened, returns true; otherwise, returns false.
This instance property indicates whether or not the current instance is bound to a temporary BLOB.
// C# public bool IsTemporary {get;}
bool
Overrides Stream
This instance property indicates the size of the BLOB data in bytes.
// C# public override Int64 Length {get;}
A number indicating the size of the BLOB data in bytes.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This instance property indicates the minimum number of bytes to retrieve or send from the server during a read or write operation.
// C# public int OptimumChunkSize{get;}
A number representing the minimum bytes to retrieve or send.
ObjectDisposedException - The object is already disposed.
Overrides Stream
This instance property indicates the current read or write position in the LOB stream.
// C# public override Int64 Position{get; set;}
An Int64 that indicates the read or write 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 Position is less than 0.
This instance property returns the data, starting from the first byte in the BLOB, 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.
ArgumentOutOfRangeException - The Value is less than 0.
The value of Position is not used or changed by using this property. 2 GB is the maximum byte array length that can be returned by this property.
OracleBlob instance methods are listed in Table 5-164.
Append appends the supplied data to the end of the current OracleBlob instance.
This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance.
This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance.
This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance.
// C# public void Append(OracleBlob obj);
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened.
No character set conversions are made.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.
This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance.
// C# public void Append(byte[] buffer, int offset, int count);
buffer
An array of bytes.
offset
The zero-based byte offset in the buffer from which data is read.
count
The number of bytes to be appended.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
// C# ... // Append 2 bytes {4,5} to the oraBlob oraBlob.Append(new byte[3] {4,5,6}, 1, 2); ...
This instance method opens the BLOB.
// C# public void BeginChunkWrite();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
BeginChunkWrite does not need to be called before manipulating the BLOB data. This is provided for performance reasons.
After this method is called, write operations do not cause the domain or function-based index on the column to be updated. Index updates occur only once after EndChunkWrite is called.
This instance method creates a copy of an OracleBlob object.
// C# public object Clone();
An OracleBlob 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 OracleBlob oraBlob_cloned = (OracleBlob) oraBlob.Clone(); ...
Overrides Stream
This instance method closes the current stream and releases any resources associated with it.
// C# public override void Close();
This instance method compares data referenced by the current instance and that of the supplied object.
// C# public int Compare(Int64 src_offset, OracleBlob obj, Int64 dst_offset, Int64 amount);
src_offset
The comparison starting point (in bytes) for the current instance.
obj
The provided OracleBlob object.
dst_offset
The comparison starting point (in bytes) for the provided OracleBlob.
amount
The number of bytes to compare.
Returns a value that is:
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened.
ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount parameter is less than 0.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
CopyTo copies data from the current instance to the provided OracleBlob object.
This instance method copies data from the current instance to the provided OracleBlob object.
This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified destination offset.
This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts.
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 OracleBlob 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 OracleBlob 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
The OracleBlob object to which the data is copied.
dst_offset
The offset (in bytes) at 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.
InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened.
ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount parameter is less than 0.
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.
// C# ... // Assume you have 2 valid blobs OracleBlob src_blob = new OracleBlob(con); OracleBlob target_blob = new OracleBlob(con); // Copy 1024 bytes from src_blob (begin at offset 10) to target_blob // (starting at offset 5) src_blob.CopyTo(10, target_blob, 5, 1024); ...
This instance method releases resources allocated by this object.
// C# public void Dispose();
IDisposable
Once Dispose() is called, the object of OracleBlob is in an uninitialized state.
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 closes the BLOB referenced by the current OracleBlob instance.
// C# public void EndChunkWrite();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Index updates occur immediately if there is write operation(s) deferred by the BeginChunkWrite method.
Erase erases a portion or all data.
This instance method erases all data.
This instance method erases a specified portion of data.
This instance method erases all data.
// C# public Int64 Erase();
The number of bytes erased.
Erase() replaces all data with zero-byte fillers.
This instance method erases a specified portion of data.
// C# public Int64 Erase(Int64 offset, Int64 amount);
The number of bytes erased.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The offset or amount parameter is less than 0.
Replaces the specified amount of data with zero-byte fillers.
This instance method compares the LOB data referenced by the two OracleBlobs.
// C# public bool IsEqual(OracleBlob obj);
If the current OracleBlob and the provided OracleBlob refer to the same LOB, returns true. 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 OracleBlob objects return false for == or Equals() because two different OracleBlob instances can refer to the same LOB.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
Overrides Stream
This instance method reads a specified amount of bytes from the ODP.NET LOB 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 starting offset (in bytes) at which the buffer is populated.
count
The amount of bytes to read.
The return value indicates the number of bytes read from the LOB.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset or the count parameter is less than 0.
offset is greater than or equal to the buffer.Length.
offset and the count together are greater than the 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 = oraBlob.Read(buffer, bufferOffset, amountToBeRead); ...
This instance method searches for a binary pattern in the current instance of an OracleBlob.
// C# public Int64 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 OracleBlob is searched.
nth
The specific occurrence (1-based) of the match for which the absolute offset (in bytes) 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 - This exception is thrown if any of the following conditions exist:
offset is less than 0.
nth is less than or equal to 0.
val.Length is greater than 16383.
nth is greater than or equal to OracleBlob.MaxSize.
offset is greater than or equal to OracleBlob.MaxSize.
The limit of the search pattern is 16383 bytes.
// C# ... // Search for the 2nd occurrence of a byte pattern '123' // from the oraBlob starting at offset 1 byte[] pattern = new byte[3] { 1,2,3 }; int positionFound = oraBlob.Search(pattern, 1, 2); ...
Overrides Stream
This instance method sets the position on the current LOB stream.
// C# public override Int64(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 Int64 for 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.
Overrides Stream
This instance method trims or truncates the BLOB value to the specified length (in bytes).
// C# public override void SetLength(Int64 newlen);
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The newlen parameter is less than 0.
Overrides Stream
This instance method writes the supplied buffer into the OracleBlob.
// C# public override void Write(byte[ ] buffer, int offset, int count);
buffer
The byte array buffer that provides the data.
offset
The 0-based offset (in bytes) from which the buffer is read.
count
The amount of data (in bytes) that is to be written into the OracleBlob.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset or the count is less than 0.
offset is greater than or equal to the buffer.Length.
offset and the count together are greater than buffer.Length.
Destination offset in the OracleBlob can be specified by the Position property.
// C# ... // Begin ChunkWrite to improve performance // Index updates occur only once after EndChunkWrite oraBlob.BeginChunkWrite(); // Set the write from the beginning; oraBlob.Position = 0; // Write to the oraBlob in chunks of 10, each 1024 bytes for ( int i=0; i<10; i++ ) { byte[1024] b; b = b[0]; // some new value to be written oraBlob.Write(b, 0, b.Length); } oraBlob.EndChunkWrite(); ...
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|