OracleBlob Class

An OracleBlob object is an object that has a reference to BLOB data. It provides methods for performing operations on BLOBs.

Class Inheritance

System.Object

  System.MarshalByRefObject

    System.IO.Stream

      Oracle.DataAccess.Types.OracleBlob

Declaration

// C#
public sealed class OracleBlob : Stream, ICloneable, INullable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class OracleBlobSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob = new OracleBlob(con);
      
    // Write 4 bytes from writeBuffer, starting at buffer offset 0
    byte[] writeBuffer = new byte[4] {1, 2, 3, 4};
    blob.Write(writeBuffer, 0, 4);    
 
    // Append first 2 bytes from writeBuffer {1, 2} to the oracleBlob
    blob.Append(writeBuffer, 0, 2);
 
    // Prints "blob.Length  = 6"
    Console.WriteLine("blob.Length  = " + blob.Length);
 
    // Reset the Position for the Read
    blob.Position = 0;
 
    // Read 6 bytes into readBuffer, starting at buffer offset 0
    byte[] readBuffer = new byte[6];       
    int bytesRead = blob.Read(readBuffer, 0, 6);
    
    // Prints "bytesRead    = 6"
    Console.WriteLine("bytesRead    = " + bytesRead);    
 
    // Prints "readBuffer   = 123412"
    Console.Write("readBuffer   = ");
    for(int index = 0; index <  readBuffer.Length; index++)
    {
      Console.Write(readBuffer[index]);
    }
    Console.WriteLine();
        
    // Search for the 2nd occurrence of a byte pattern '12'
    // starting from byte offset 0 in the OracleBlob
    byte[] pattern = new byte[2] {1, 2};
    long posFound = blob.Search(pattern, 0, 2);
 
    // Prints "posFound     = 5" 
    Console.WriteLine("posFound     = " + posFound);
 
    // Erase 4 bytes of data starting at byte offset 1
    // Sets bytes to zero
    blob.Erase(1, 4);
 
    byte[] erasedBuffer = blob.Value;    
 
    //Prints "erasedBuffer = 100002"
    Console.Write("erasedBuffer = ");
    for(int index = 0; index < erasedBuffer.Length; index++)
    {
      Console.Write(erasedBuffer[index]);
    }
    Console.WriteLine();
 
    blob.Close();
    blob.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

Microsoft .NET Framework Version: 1.0 or later


OracleBlob Members

OracleBlob members are listed in the following tables.

OracleBlob Constructors

OracleBlob constructors are listed in Table 11-10.

Table 11-10 OracleBlob Constructors

Constructor Description

OracleBlob Constructors

Creates an instance of the OracleBlob class (Overloaded)


OracleBlob Static Fields

OracleBlob static fields are listed in Table 11-11.

Table 11-11 OracleBlob Static Fields

Field Description

MaxSize

Holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes

Null

Represents a null value that can be assigned to the value of an OracleBlob instance


OracleBlob Static Methods

OracleBlob static methods are listed in Table 11-12.

Table 11-12 OracleBlob Static Methods

Methods Description

Equals

Inherited from System.Object (Overloaded)


OracleBlob Instance Properties

OracleBlob instance properties are listed in Table 11-13.

Table 11-13 OracleBlob Instance Properties

Properties Description

CanRead

Indicates whether or not the LOB stream can be read

CanSeek

Indicates whether or not forward and backward seek operations be performed

CanWrite

Indicates whether or not the LOB object supports writing

Connection

Indicates the OracleConnection that is used to retrieve and write BLOB data

IsEmpty

Indicates whether the BLOB is empty or not

IsInChunkWriteMode

Indicates whether or not the BLOB has been opened to defer index updates

IsNull

Indicates whether or not the current instance has a null value

IsTemporary

Indicates whether or not the current instance is bound to a temporary BLOB

Length

Indicates the size of the BLOB data

OptimumChunkSize

Indicates the optimal data buffer length (or multiples thereof) that read and write operations should use to improve performance

Position

Indicates the current read or write position in the LOB stream

Value

Returns the data, starting from the first byte in BLOB, as a byte array


OracleBlob Instance Methods

OracleBlob instance methods are listed in Table 11-14.

Table 11-14 OracleBlob Instance Methods

Methods Description

Append

Appends the supplied data to the current OracleBlob instance (Overloaded)

BeginChunkWrite

Opens the BLOB

BeginRead

Inherited from System.IO.Stream

BeginWrite

Inherited from System.IO.Stream

Clone

Creates a copy of an OracleBlob object

Close

Closes the current stream and releases any resources associated with it

Compare

Compares data referenced by the current instance and that of the supplied object

CopyTo

Copies from the current OracleBlob instance to an OracleBlob object (Overloaded)

CreateObjRef

Inherited from System.MarshalByRefObject

Dispose

Releases resources allocated by this object

EndChunkWrite

Closes the BLOB referenced by the current OracleBlob instance

EndRead

Inherited from System.IO.Stream

EndWrite

Inherited from System.IO.Stream

Equals

Inherited from System.Object (Overloaded)

Erase

Erases data (Overloaded)

Flush

Not supported

GetHashCode

Inherited from System.Object

GetLifetimeService

Inherited from System.MarshalByRefObject

GetType

Inherited from System.Object

InitializedLifetimeService

Inherited from System.MarshalByRefObject

IsEqual

Compares the LOB data referenced by the two OracleBlobs

Read

Reads a specified amount of bytes from the ODP.NET LOB Type instance and populates the buffer

ReadByte

Inherited from System.IO.Stream

Search

Searches for a binary pattern in the current instance of an OracleBlob

Seek

Sets the position in the current LOB stream

SetLength

Trims or truncates the BLOB value to the specified length

ToString

Inherited from System.Object

Write

Writes the supplied buffer into the OracleBlob

WriteByte

Inherited from System.IO.Stream



OracleBlob Constructors

OracleBlob constructors are listed in Table 11-10.

Overload List:

  • OracleBlob(OracleConnection)

    This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object.

  • OracleBlob(OracleConnection, bool)

    This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching.

OracleBlob(OracleConnection)

This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object.

Declaration

// C#
public OracleBlob(OracleConnection con);

Parameters

  • con

    The OracleConnection object.

Exceptions

InvalidOperationException - The OracleConnection is not opened.

Remarks

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.

OracleBlob(OracleConnection, bool)

This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching.

Declaration

// C#
public OracleBlob(OracleConnection con, bool bCaching);

Parameters

  • con

    The OracleConnection object.

  • bCaching

    A flag for enabling or disabling server-side caching.

Exceptions

InvalidOperationException - The OracleConnection is not opened.

Remarks

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

OracleBlob static fields are listed in Table 11-15.

Table 11-15 OracleBlob Static Fields

Field Description

MaxSize

Holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes

Null

Represents a null value that can be assigned to the value of an OracleBlob instance


MaxSize

The MaxSize field holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes.

Declaration

// C#
public static readonly Int64 MaxSize = 4294967295;

Remarks

This field can be useful in code that checks whether or not the operation exceeds the maximum length allowed.

Null

This static field represents a null value that can be assigned to the value of an OracleBlob instance.

Declaration

// C#
public static readonly OracleBlob Null;

OracleBlob Static Methods

OracleBlob static methods are listed in Table 11-16.

Table 11-16 OracleBlob Static Methods

Methods Description

Equals

Inherited from System.Object (Overloaded)



OracleBlob Instance Properties

OracleBlob instance properties are listed in Table 11-17.

Table 11-17 OracleBlob Instance Properties

Properties Description

CanRead

Indicates whether or not the LOB stream can be read

CanSeek

Indicates whether or not forward and backward seek operations be performed

CanWrite

Indicates whether or not the LOB object supports writing

Connection

Indicates the OracleConnection that is used to retrieve and write BLOB data

IsEmpty

Indicates whether the BLOB is empty or not

IsInChunkWriteMode

Indicates whether or not the BLOB has been opened to defer index updates

IsNull

Indicates whether or not the current instance has a null value

IsTemporary

Indicates whether or not the current instance is bound to a temporary BLOB

Length

Indicates the size of the BLOB data

OptimumChunkSize

Indicates the optimal data buffer length (or multiples thereof) that read and write operations should use to improve performance

Position

Indicates the current read or write position in the LOB stream

Value

Returns the data, starting from the first byte in BLOB, as a byte array


CanRead

Overrides Stream

This instance property indicates whether or not the LOB stream can be read.

Declaration

// C#
public override bool CanRead{get;}

Property Value

If the LOB stream can be read, returns true; otherwise, returns false.

CanSeek

Overrides Stream

This instance property indicates whether or not forward and backward seek operations can be performed.

Declaration

// C#
public override bool CanSeek{get;}

Property Value

If forward and backward seek operations can be performed, returns true; otherwise, returns false.

CanWrite

Overrides Stream

This instance property indicates whether or not the LOB object supports writing.

Declaration

// C#
public override bool CanWrite{get;}

Property Value

If the LOB stream can be written, returns true; otherwise, returns false.

Connection

This instance property indicates the OracleConnection that is used to retrieve and write BLOB data.

Declaration

// C#
public OracleConnection Connection {get;}

Property Value

An object of OracleConnection.

Exceptions

ObjectDisposedException - The object is already disposed.

IsEmpty

This instance property indicates whether the BLOB is empty or not.

Declaration

// C#
public bool IsEmpty {get;}

Property Value

A bool that indicates whether or not the BLOB is empty.

Exceptions

ObjectDisposedException - The object is already disposed.

IsInChunkWriteMode

This instance property indicates whether or not the BLOB has been opened to defer index updates.

Declaration

// C#
public bool IsInChunkWriteMode{get;}

Property Value

If the BLOB has been opened, returns true; otherwise, returns false.

IsNull

This property indicates whether or not the current instance has a null value.

Declaration

// C#
public bool IsNull{get;}

Property Value

Returns true if the current instance has a null value; otherwise, returns false.

IsTemporary

This instance property indicates whether or not the current instance is bound to a temporary BLOB.

Declaration

// C#
public bool IsTemporary {get;}

Property Value

bool

Length

Overrides Stream

This instance property indicates the size of the BLOB data in bytes.

Declaration

// C#
public override Int64 Length {get;}

Property Value

A number indicating the size of the BLOB data in bytes.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

OptimumChunkSize

This instance property indicates the optimal data buffer length (or multiples thereof) that read and write operations should use to improve performance.

Declaration

// C#
public int OptimumChunkSize{get;}

Property Value

A number representing the minimum bytes to retrieve or send.

Exceptions

ObjectDisposedException - The object is already disposed.

Position

Overrides Stream

This instance property indicates the current read or write position in the LOB stream.

Declaration

// C#
public override Int64 Position{get; set;}

Property Value

An Int64 that indicates the read or write position.

Exceptions

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.

Value

This instance property returns the data, starting from the first byte in the BLOB, as a byte array.

Declaration

// C#
public Byte[] Value{get;}

Property Value

A byte array.

Exceptions

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.

Remarks

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

OracleBlob instance methods are listed in Table 11-18.

Table 11-18 OracleBlob Instance Methods

Methods Description

Append

Appends the supplied data to the current OracleBlob instance (Overloaded)

BeginChunkWrite

Opens the BLOB

BeginRead

Inherited from System.IO.Stream

BeginWrite

Inherited from System.IO.Stream

Clone

Creates a copy of an OracleBlob object

Close

Closes the current stream and releases any resources associated with it

Compare

Compares data referenced by the current instance and that of the supplied object

CopyTo

Copies from the current OracleBlob instance to an OracleBlob object (Overloaded)

CreateObjRef

Inherited from System.MarshalByRefObject

Dispose

Releases resources allocated by this object

EndChunkWrite

Closes the BLOB referenced by the current OracleBlob instance

EndRead

Inherited from System.IO.Stream

EndWrite

Inherited from System.IO.Stream

Equals

Inherited from System.Object (Overloaded)

Erase

Erases data (Overloaded)

Flush

Not supported

GetHashCode

Inherited from System.Object

GetLifetimeService

Inherited from System.MarshalByRefObject

GetType

Inherited from System.Object

InitializedLifetimeService

Inherited from System.MarshalByRefObject

IsEqual

Compares the LOB data referenced by the two OracleBlobs

Read

Reads a specified amount of bytes from the ODP.NET LOB Type instance and populates the buffer

ReadByte

Inherited from System.IO.Stream

Search

Searches for a binary pattern in the current instance of an OracleBlob

Seek

Sets the position in the current LOB stream

SetLength

Trims or truncates the BLOB value to the specified length

ToString

Inherited from System.Object

Write

Writes the supplied buffer into the OracleBlob

WriteByte

Inherited from System.IO.Stream


Append

Append appends the supplied data to the end of the current OracleBlob instance.

Overload List:

  • Append(OracleBlob)

    This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance.

  • Append(byte[ ], int, int)

    This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance.

Append(OracleBlob)

This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance.

Declaration

// C#
public void Append(OracleBlob obj);

Parameters

  • obj

    An object of OracleBlob.

Exceptions

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.

Remarks

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.

Append(byte[ ], int, int)

This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance.

Declaration

// C#
public void Append(byte[] buffer, int offset, int count);

Parameters

  • 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.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class AppendSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob = new OracleBlob(con);
      
    // Append 2 bytes {4, 5} to the OracleBlob
    byte[] buffer = new byte[3] {4, 5, 6};
    blob.Append(buffer, 0, 2);
 
    byte[] appendBuffer = blob.Value;
 
    // Prints "appendBuffer = 45"
    Console.Write("appendBuffer = ");
    for(int index = 0; index < appendBuffer.Length; index++)
    {
      Console.Write(appendBuffer[index]);
    }
    Console.WriteLine();
 
    blob.Close();
    blob.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

BeginChunkWrite

This instance method opens the BLOB.

Declaration

// C#
public void BeginChunkWrite();

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

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.

Clone

This instance method creates a copy of an OracleBlob object.

Declaration

// C#
public object Clone();

Return Value

An OracleBlob object.

Implements

ICloneable

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

The cloned object has the same property values as that of the object being cloned.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class CloneSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob1 = new OracleBlob(con);
 
    // Prints "blob1.Position = 0"
    Console.WriteLine("blob1.Position = " + blob1.Position);
    
    // Set the Position before calling Clone()
    blob1.Position = 1;
 
    // Clone the OracleBlob
    OracleBlob blob2 = (OracleBlob)blob1.Clone();
    
    // Prints "blob2.Position = 1"
    Console.WriteLine("blob2.Position = " + blob2.Position);
 
    blob1.Close();
    blob1.Dispose();
 
    blob2.Close();
    blob2.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

Close

Overrides Stream

This instance method closes the current stream and releases any resources associated with it.

Declaration

// C#
public override void Close();

Compare

This instance method compares data referenced by the current instance and that of the supplied object.

Declaration

// C#
public int Compare(Int64 src_offset, OracleBlob obj, Int64 dst_offset,
   Int64 amount);

Parameters

  • 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.

Return Value

Returns a value that is:

  • Less than zero: if the data referenced by the current instance is less than that of the supplied instance

  • Zero: if both objects reference the same data

  • Greater than zero: if the data referenced by the current instance is greater than that of the supplied instance

Exceptions

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.

Remarks

The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.

CopyTo

CopyTo copies data from the current instance to the provided OracleBlob object.

Overload List:

  • CopyTo(OracleBlob)

    This instance method copies data from the current instance to the provided OracleBlob object.

  • CopyTo(OracleBlob, Int64)

    This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified destination offset.

  • CopyTo(Int64, OracleBlob, Int64, Int64)

    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.

CopyTo(OracleBlob)

This instance method copies data from the current instance to the provided OracleBlob object.

Declaration

// C#
public Int64 CopyTo(OracleBlob obj);

Parameters

  • obj

    The OracleBlob object to which the data is copied.

Return Value

The return value is the amount copied.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - This exception is thrown if any of the following conditions exist:

  • The OracleConnection is not open or has been closed during the lifetime of the object.

  • The LOB object parameter has a different connection than the object.

Remarks

The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.

CopyTo(OracleBlob, Int64)

This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified destination offset.

Declaration

// C#
public Int64 CopyTo(OracleBlob obj, Int64 dst_offset);

Parameters

  • obj

    The OracleBlob object to which the data is copied.

  • dst_offset

    The offset (in bytes) at which the OracleBlob object is copied.

Return Value

The return value is the amount copied.

Exceptions

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:

  • The OracleConnection is not open or has been closed during the lifetime of the object.

  • The LOB object parameter has a different connection than the object.

Remarks

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.

CopyTo(Int64, OracleBlob, Int64, Int64)

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.

Declaration

// C#
public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset,
   Int64 amount);

Parameters

  • 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.

Return Value

The return value is the amount copied.

Exceptions

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.

Remarks

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.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class CopyToSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob1 = new OracleBlob(con);
    OracleBlob blob2 = new OracleBlob(con);
 
    // Write 4 bytes, starting at buffer offset 0
    byte[] buffer = new byte[4] {1, 2, 3, 4};    
    blob1.Write(buffer, 0, 4);
 
    // Copy 2 bytes from byte 0 of blob1 to byte 1 of blob2
    blob1.CopyTo(0, blob2, 1, 2);
 
    byte[] copyBuffer = blob2.Value;    
 
    //Prints "Value = 012"
    Console.Write("Value = ");
    for(int index = 0; index < copyBuffer.Length; index++)
    {
      Console.Write(copyBuffer[index]);
    }
    Console.WriteLine();
    
    blob1.Close();
    blob1.Dispose();
 
    blob2.Close();
    blob2.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

Dispose

This instance method releases resources allocated by this object.

Declaration

// C#
public void Dispose();

Implements

IDisposable

Remarks

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.

EndChunkWrite

This instance method closes the BLOB referenced by the current OracleBlob instance.

Declaration

// C#
public void EndChunkWrite();

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

Index updates occur immediately if there is write operation(s) deferred by the BeginChunkWrite method.

Erase

Erase erases a portion or all data.

Overload List:

Erase()

This instance method erases all data.

Declaration

// C#
public Int64 Erase();

Return Value

The number of bytes erased.

Remarks

Erase() replaces all data with zero-byte fillers.

Erase(Int64, Int64)

This instance method erases a specified portion of data.

Declaration

// C#
public Int64 Erase(Int64 offset, Int64 amount);

Parameters

  • offset

    The offset from which to erase.

  • amount

    The quantity (in bytes) to erase.

Return Value

The number of bytes erased.

Exceptions

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.

Remarks

Replaces the specified amount of data with zero-byte fillers.

IsEqual

This instance method compares the LOB data referenced by the two OracleBlobs.

Declaration

// C#
public bool IsEqual(OracleBlob obj);

Parameters

  • obj

    An OracleBlob object.

Return Value

If the current OracleBlob and the provided OracleBlob refer to the same LOB, returns true. Returns false otherwise.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

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.

Read

Overrides Stream

This instance method reads a specified amount of bytes from the ODP.NET LOB instance and populates the buffer.

Declaration

// C#
public override int Read(byte[ ] buffer, int offset, int count);

Parameters

  • 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.

Return Value

The return value indicates the number of bytes read from the LOB.

Exceptions

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:

  • The offset or the count parameter is less than 0.

  • The offset is greater than or equal to the buffer.Length.

  • The offset and the count together are greater than the buffer.Length.

Remarks

The LOB data is read starting from the position specified by the Position property.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class ReadSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob = new OracleBlob(con);
      
    // Write 3 bytes, starting at buffer offset 1
    byte[] writeBuffer = new byte[4] {1, 2, 3, 4};
    blob.Write(writeBuffer, 1, 3);
 
    // Reset the Position for Read
    blob.Position = 1;
 
    // Read 2 bytes into buffer starting at buffer offset 1
    byte[] readBuffer = new byte[4];    
    int bytesRead = blob.Read(readBuffer, 1, 2);
 
    // Prints "bytesRead  = 2"
    Console.WriteLine("bytesRead  = " + bytesRead);    
 
    // Prints "readBuffer = 0340"
    Console.Write("readBuffer = ");
    for(int index = 0; index <  readBuffer.Length; index++)
    {
      Console.Write(readBuffer[index]);
    }
    Console.WriteLine();
 
    blob.Close();
    blob.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

Search

This instance method searches for a binary pattern in the current instance of an OracleBlob.

Declaration

// C#
public Int64 Search(byte[] val, int64 offset, int64 nth);

Parameters

  • 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.

Return Value

Returns the absolute offset of the start of the matched pattern (in bytes) for the nth occurrence of the match. Otherwise, 0 is returned.

Exceptions

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:

  • The offset is less than 0.

  • The nth is less than or equal to 0.

  • The val.Length is greater than 16383.

  • The nth is greater than or equal to OracleBlob.MaxSize.

  • The offset is greater than or equal to OracleBlob.MaxSize.

Remarks

The limit of the search pattern is 16383 bytes.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class SearchSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob = new OracleBlob(con);
      
    // Write 7 bytes, starting at buffer offset 0
    byte[] buffer = new byte[7] {1, 2, 3, 4, 1, 2, 3};
    blob.Write(buffer, 0, 7);
      
    // Search for the 2nd occurrence of a byte pattern '23'
    // starting at offset 1 in the OracleBlob
    byte[] pattern = new byte[2] {2 ,3};
    long posFound = blob.Search(pattern, 1, 2);
 
    // Prints "posFound = 6" 
    Console.WriteLine("posFound = " + posFound);
 
    blob.Close();
    blob.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

Seek

Overrides Stream

This instance method sets the position on the current LOB stream.

Declaration

// C#
public override Int64 Seek(Int64 offset, SeekOrigin origin);

Parameters

  • 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.

Return Value

Returns Int64 for the position.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.

Remarks

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.

SetLength

Overrides Stream

This instance method trims or truncates the BLOB value to the specified length (in bytes).

Declaration

// C#
public override void SetLength(Int64 newlen);

Parameters

  • newlen

    The desired length of the current stream in bytes.

Exceptions

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.

Write

Overrides Stream

This instance method writes the supplied buffer into the OracleBlob.

Declaration

// C#
public override void Write(byte[ ] buffer, int offset, int count);

Parameters

  • 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.

Exceptions

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:

  • The offset or the count is less than 0.

  • The offset is greater than or equal to the buffer.Length.

  • The offset and the count together are greater than buffer.Length.

Remarks

Destination offset in the OracleBlob can be specified by the Position property.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class WriteSample
{
  static void Main()
  {
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBlob blob = new OracleBlob(con);
    
    // Set the Position for the Write
    blob.Position = 0;  
 
    // Begin ChunkWrite to improve performance
    // Index updates occur only once after EndChunkWrite
    blob.BeginChunkWrite();
          
    // Write to the OracleBlob in 5 chunks of 2 bytes each
    byte[] b = new byte[2] {1, 2};
    for(int index = 0; index < 5; index++)
    {
      blob.Write(b, 0, b.Length);
    }
    blob.EndChunkWrite();
 
    byte[] chunkBuffer = blob.Value;
 
    // Prints "chunkBuffer = 1212121212"
    Console.Write("chunkBuffer = ");
    for(int index = 0; index < chunkBuffer.Length; index++)
    {
      Console.Write(chunkBuffer[index]);
    }
    Console.WriteLine();
 
    blob.Close();
    blob.Dispose();
 
    con.Close();
    con.Dispose();
  }
}