OracleBFile Class

An OracleBFile is an object that has a reference to BFILE data. It provides methods for performing operations on BFILEs.

Note:

OracleBFile is supported for applications running against Oracle8.x and later.

Class Inheritance

System.Object

  System.MarshalByRefObject

    System.IO.Stream

             Oracle.DataAccess.Types.OracleBFile

Declaration

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

Thread Safety

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

Remarks

OracleBFile is supported for applications running against Oracle8.x and later.

Example

// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
 
CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';
 
*/
 
// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class OracleBFileSample
{
static void Main()
{
    // Create MYDIR directory object as indicated previously and create a file
    // MyFile.txt with the text ABCDABC under C:\TEMP directory.
    // Note that the byte representation of the ABCDABC is 65666768656667
 
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");
 
    // Open the OracleBFile
    bFile.OpenFile();
 
    // Read 7 bytes into readBuffer, starting at buffer offset 0
    byte[] readBuffer = new byte[7];       
    int bytesRead = bFile.Read(readBuffer, 0, 7);
    
    // Prints "bytesRead  = 7"
    Console.WriteLine("bytesRead  = " + bytesRead);    
 
    // Prints "readBuffer = 65666768656667"
    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 {66,67}
    // starting from byte offset 1 in the OracleBFile
    byte[] pattern = new byte[2] {66, 67};
    long posFound = bFile.Search(pattern, 1, 2);
    
    // Prints "posFound   = 6" 
    Console.WriteLine("posFound   = " + posFound);
    
    // Close the OracleBFile
    bFile.CloseFile();
 
    bFile.Close();
    bFile.Dispose();
 
    con.Close();
    con.Dispose();
}
}

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4


OracleBFile Members

OracleBFile members are listed in the following tables.

OracleBFile Constructors

OracleBFile constructors are listed in Table 13-1.

Table 13-1 OracleBFile Constructors

Constructor Description

OracleBFile Constructors

Creates an instance of the OracleBFile class (Overloaded)


OracleBFile Static Fields

OracleBFile static fields are listed in Table 13-2.

Table 13-2 OracleBFile Static Fields

Field Description

MaxSize

The static field holds the maximum number of bytes a BFILE 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 OracleBFile instance


OracleBFile Static Methods

OracleBFile static methods are listed in Table 13-3.

Table 13-3 OracleBFile Static Methods

Methods Description

Equals

Inherited from System.Object (Overloaded)


OracleBFile Instance Properties

OracleBFile instance properties are listed in Table 13-4.

Table 13-4 OracleBFile 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 can be performed

CanWrite

Indicates whether or not the LOB object supports writing

Connection

Indicates the connection used to read from a BFILE

DirectoryName

Indicates the directory alias of the BFILE

FileExists

Indicates whether or not the specified BFILE exists

FileName

Indicates the name of the BFILE

IsEmpty

Indicates whether the BFILE is empty or not

IsNull

Indicates whether or not the current instance has a null value

IsOpen

Indicates whether the BFILE has been opened by this instance or not

Length

Indicates the size of the BFILE data in bytes

Position

Indicates the current read position in the LOB stream

Value

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


OracleBFile Instance Methods

OracleBFile instance methods are listed in Table 13-5.

Table 13-5 OracleBFile Instance Methods

Methods Description

BeginRead

Inherited from System.IO.Stream

BeginWrite

Not Supported

Clone

Creates a copy of an OracleBFile object

Close

Closes the current stream and releases any resources associated with the stream

CloseFile

Closes the BFILE referenced by the current BFILE instance

Compare

Compares data referenced by the two OracleBFiles

CreateObjRef

Inherited from System.MarshalByRefObject

CopyTo

Copies data as specified (Overloaded)

Dispose

Releases resources allocated by this object

EndRead

Inherited from System.IO.Stream

EndWrite

Not Supported

Equals

Inherited from System.Object (Overloaded)

Flush

Not Supported

GetHashCode

Inherited from System.Object

GetLifetimeService

Inherited from System.MarshalByRefObject

GetType

Inherited from System.Object

InitializeLifetimeService

Inherited from System.MarshalByRefObject

IsEqual

Compares the LOB references

OpenFile

Opens the BFILE specified by the FileName and DirectoryName

Read

Reads a specified amount of bytes from the OracleBFile instance and populates the buffer

ReadByte

Inherited from System.IO.Stream

Search

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

Seek

Sets the position on the current LOB stream

SetLength

Not Supported

ToString

Inherited from System.Object

Write

Not Supported

WriteByte

Not Supported



OracleBFile Constructors

OracleBFile constructors create new instances of the OracleBFile class.

Overload List:

OracleBFile(OracleConnection)

This constructor creates an instance of the OracleBFile class with an OracleConnection object.

Declaration

// C#
public OracleBFile(OracleConnection con);

Parameters

  • con

    The OracleConnection object.

Exceptions

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

Remarks

The connection must be opened explicitly by the application. OracleBFile does not open the connection implicitly.

OracleBFile(OracleConnection, string, string)

This constructor creates an instance of the OracleBFile class with an OracleConnection object, the location of the BFILE, and the name of the BFILE.

Declaration

// C#
public OracleBFile(OracleConnection con, string directoryName, string
   fileName);

Parameters

  • con

    The OracleConnection object.

  • directoryName

    The directory alias created by the CREATE DIRECTORY SQL statement.

  • fileName

    The name of the external LOB.

Exceptions

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

Remarks

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

OracleBFile static fields are listed in Table 13-6.

Table 13-6 OracleBFile Static Fields

Field Description

MaxSize

The static field holds the maximum number of bytes a BFILE 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 OracleBFile instance


MaxSize

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

Declaration

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

Remarks

This field is 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 OracleBFile instance.

Declaration

// C#
public static readonly OracleBFile Null;

OracleBFile Static Methods

OracleBFile static methods are listed in Table 13-7.

Table 13-7 OracleBFile Static Methods

Methods Description

Equals

Inherited from System.Object (Overloaded)



OracleBFile Instance Properties

OracleBFile instance properties are listed in Table 13-8.

Table 13-8 OracleBFile 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 can be performed

CanWrite

Indicates whether or not the LOB object supports writing

Connection

Indicates the connection used to read from a BFILE

DirectoryName

Indicates the directory alias of the BFILE

FileExists

Indicates whether or not the specified BFILE exists

FileName

Indicates the name of the BFILE

IsEmpty

Indicates whether the BFILE is empty or not

IsNull

Indicates whether or not the current instance has a null value

IsOpen

Indicates whether the BFILE has been opened by this instance or not

Length

Indicates the size of the BFILE data in bytes

Position

Indicates the current read position in the LOB stream

Value

Returns the data, starting from the first byte in BFILE, 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

BFILE is read only.

Remarks

BFILE is read-only, therefore, the boolean value is always false.

Connection

This instance property indicates the connection used to read from a BFILE.

Declaration

// C#
public OracleConnection Connection {get;}

Property Value

An object of OracleConnection.

Exceptions

ObjectDisposedException - The object is already disposed.

DirectoryName

This instance property indicates the directory alias of the BFILE.

Declaration

// C#
public string DirectoryName {get;set;}

Property Value

A string.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The value of the DirectoryName changed while the BFILE is open.

Remarks

The maximum length of a DirectoryName is 30 bytes.

FileExists

This instance property indicates whether or not the BFILE specified by the DirectoryName and FileName exists.

Declaration

// C#
public bool FileExists {get;}

Property Value

bool

Exceptions

ObjectDisposedException - The object is already disposed.

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

Remarks

Unless a connection, file name, and directory name are provided, this property is set to false by default.

FileName

This instance property indicates the name of the BFILE.

Declaration

// C#
public string FileName {get;set}

Property Value

A string that contains the BFILE name.

Exceptions

ObjectDisposedException - The object is already disposed.

InvalidOperationException - The value of the DirectoryName changed while the BFILE is open.

Remarks

The maximum length of a FileName is 255 bytes.

Changing the FileName property while the BFILE object is opened causes an exception.

IsEmpty

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

Declaration

// C#
public bool IsEmpty {get;}

Property Value

bool

Exceptions

ObjectDisposedException - The object is already disposed.

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.

IsOpen

This instance property indicates whether the BFILE has been opened by this instance or not.

Declaration

// C#
public bool IsOpen {get;}

Property Value

A bool.

Length

Overrides Stream

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

Declaration

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

Property Value

Int64

Exceptions

ObjectDisposedException - The object is already disposed.

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

Position

Overrides Stream

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

Declaration

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

Property Value

An Int64 value that indicates the read 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 value is less than 0.

Value

This instance property returns the data, starting from the first byte in BFILE, 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.

Remarks

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

OracleBFile instance methods are listed in Table 13-9.

Table 13-9 OracleBFile Instance Methods

Methods Description

BeginRead

Inherited from System.IO.Stream

BeginWrite

Not Supported

Clone

Creates a copy of an OracleBFile object

Close

Closes the current stream and releases any resources associated with the stream

CloseFile

Closes the BFILE referenced by the current BFILE instance

Compare

Compares data referenced by the two OracleBFiles

CreateObjRef

Inherited from System.MarshalByRefObject

CopyTo

Copies data as specified (Overloaded)

Dispose

Releases resources allocated by this object

EndRead

Inherited from System.IO.Stream

EndWrite

Not Supported

Equals

Inherited from System.Object (Overloaded)

Flush

Not Supported

GetHashCode

Inherited from System.Object

GetLifetimeService

Inherited from System.MarshalByRefObject

GetType

Inherited from System.Object

InitializeLifetimeService

Inherited from System.MarshalByRefObject

IsEqual

Compares the LOB references

OpenFile

Opens the BFILE specified by the FileName and DirectoryName

Read

Reads a specified amount of bytes from the OracleBFile instance and populates the buffer

ReadByte

Inherited from System.IO.Stream

Search

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

Seek

Sets the position on the current LOB stream

SetLength

Not Supported

ToString

Inherited from System.Object

Write

Not Supported

WriteByte

Not Supported


Clone

This instance method creates a copy of an OracleBFile object.

Declaration

// C#
public object Clone();

Return Value

An OracleBFile 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

// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
 
CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';
 
*/
 
// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class CloneSample
{
  static void Main()
  {
    // Create MYDIR directory object as indicated previously and create a file
    // MyFile.txt with the text ABCDABC under C:\TEMP directory.
    // Note that the byte representation of the ABCDABC is 65666768656667
 
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBFile bFile1 = new OracleBFile(con, "MYDIR", "MyFile.txt");   
    
    // Prints "bFile1.Position = 0"
    Console.WriteLine("bFile1.Position = " + bFile1.Position);
    
    // Set the Position before calling Clone()
    bFile1.Position = 1;
 
    // Clone the OracleBFile
    OracleBFile bFile2 = (OracleBFile) bFile1.Clone();
 
    // Prints "bFile2.Position = 1"
    Console.WriteLine("bFile2.Position = " + bFile2.Position);   
    
    bFile1.Close();
    bFile1.Dispose();
 
    bFile2.Close();
    bFile2.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();

Exceptions

ObjectDisposedException - The object is already disposed.

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

CloseFile

This instance method closes the BFILE referenced by the current BFILE instance.

Declaration

// C#
public void CloseFile();

Remarks

No error is returned if the BFILE exists, but is not opened.

Compare

This instance method compares data referenced by the two OracleBFiles.

Declaration

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

Parameters

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

Return Value

Returns a number that is:

  • Less than zero: if the BFILE data of the current instance is less than that of the provided BFILE data.

  • Zero: if both the BFILEs store the same data.

  • Greater than zero: if the BFILE data of the current instance is greater than that of the provided BFILE data.

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 src_offset, the dst_offset, or the amount is less than 0.

Remarks

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.

Example

// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
 
CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';
 
*/
 
// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class CompareSample
{
  static void Main()
  {
    // Create MYDIR directory object as indicated previously and create a file
    // MyFile.txt with the text ABCDABC under C:\TEMP directory.
    // Note that the byte representation of the ABCDABC is 65666768656667
 
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBFile bFile1 = new OracleBFile(con, "MYDIR", "MyFile.txt");
    OracleBFile bFile2 = new OracleBFile(con, "MYDIR", "MyFile.txt");
 
    // Open the OracleBFiles
    bFile1.OpenFile();
    bFile2.OpenFile();
 
    // Compare 2 bytes from the 1st byte of bFile1 and
    // the 5th byte of bFile2 onwards
    int result = bFile1.Compare(1, bFile2, 5, 2);
 
    // Prints "result = 0" (Indicates the data is identical)
    Console.WriteLine("result = " + result);    
 
    // Close the OracleBFiles
    bFile1.CloseFile();
    bFile2.CloseFile();
 
    bFile1.Close();
    bFile1.Dispose();
 
    bFile2.Close();
    bFile2.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

CopyTo

CopyTo copies data from the current instance to the provided 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 OracleBFile instance to the provided OracleBlob object with the specified destination offset.

  • CopyTo(Int64, OracleBlob, Int64, Int64)

    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.

  • CopyTo(OracleClob)

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

  • CopyTo(OracleClob, Int64)

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

  • CopyTo(Int64, OracleClob, Int64, Int64)

    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.

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 OracleBFile 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 OracleBFile 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

    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.

Return Value

The return value is the amount copied.

Exceptions

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:

  • 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(OracleClob)

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

Declaration

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

Parameters

  • obj

    The OracleClob 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(OracleClob, Int64)

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

Declaration

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

Parameters

  • obj

    The OracleClob object that the data is copied to.

  • dst_offset

    The offset (in characters) at which the OracleClob object is copied to.

Return Value

The amount copied.

Exceptions

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

CopyTo(Int64, OracleClob, Int64, Int64)

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.

Declaration

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

Parameters

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

Return Value

The return value is the amount copied.

Exceptions

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:

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

Dispose

This instance method releases resources allocated by this object.

Declaration

// C#
public void Dispose();

Implements

IDisposable

Remarks

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.

IsEqual

This instance method compares the LOB references.

Declaration

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

Parameters

  • obj

    The provided OracleBFile object.

Return Value

Returns true if the current OracleBFile and the provided OracleBFile object refer to the same external LOB. 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 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.

OpenFile

This instance method opens the BFILE specified by the FileName and DirectoryName.

Declaration

// C#
public void OpenFile();

Exceptions

ObjectDisposedException - The object is already disposed.

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

Remarks

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.

Read

Overrides Stream

This instance method reads a specified amount of bytes from the OracleBFile 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 offset of the byte array buffer to be populated.

  • count

    The amount of bytes to read.

Return Value

The return value indicates the number of bytes read from the BFILE, that is, the external 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 - 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.

Remarks

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

Example

// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
 
CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';
 
*/
 
// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class ReadSample
{
  static void Main()
  {
    // Create MYDIR directory object as indicated previously and create a file
    // MyFile.txt with the text ABCDABC under C:\TEMP directory.
    // Note that the byte representation of the ABCDABC is 65666768656667
 
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");
 
    // Open the OracleBFile
    bFile.OpenFile();
 
    // Read 7 bytes into readBuffer, starting at buffer offset 0
    byte[] readBuffer = new byte[7];       
    int bytesRead = bFile.Read(readBuffer, 0, 7);
    
    // Prints "bytesRead  = 7"
    Console.WriteLine("bytesRead  = " + bytesRead);    
 
    // Prints "readBuffer = 65666768656667"
    Console.Write("readBuffer = ");
    for(int index = 0; index <  readBuffer.Length; index++)
    {
      Console.Write(readBuffer[index]);
    }
    Console.WriteLine();
 
    // Close the OracleBFile
    bFile.CloseFile();
 
    bFile.Close();
    bFile.Dispose();
 
    con.Close();
    con.Dispose();
  }
}

Search

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

Declaration

// C#
public int 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 OracleBFile is searched.

  • nth

    The specific occurrence (1-based) of the match for which the offset 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 - 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.

Remarks

The limit of the search pattern is 16383 bytes.

Example

// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
 
CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';
 
*/
 
// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class SearchSample
{
  static void Main()
  {
    // Create MYDIR directory object as indicated previously and create a file
    // MyFile.txt with the text ABCDABC under C:\TEMP directory.
    // Note that the byte representation of the ABCDABC is 65666768656667
 
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");
 
    // Open the OracleBFile
    bFile.OpenFile();
    
    // Search for the 2nd occurrence of a byte pattern {66,67}
    // starting from byte offset 1 in the OracleBFile
    byte[] pattern = new byte[2] {66, 67};
    long posFound = bFile.Search(pattern, 1, 2);
    
    // Prints "posFound = 6" 
    Console.WriteLine("posFound = " + posFound);
    
    // Close the OracleBFile
    bFile.CloseFile();
 
    bFile.Close();
    bFile.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 an Int64 that indicates 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.

Example

// Database Setup, if you have not done so yet.
/* Log on as DBA (SYS or SYSTEM) that has CREATE ANY DIRECTORY privilege.
 
CREATE OR REPLACE DIRECTORY MYDIR AS 'C:\TEMP';
 
*/
 
// C#
 
using System;
using System.IO;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class SeekSample
{
  static void Main()
  {
    // Create MYDIR directory object as indicated previously and create a file
    // MyFile.txt with the text ABCDABC under C:\TEMP directory.
    // Note that the byte representation of the ABCDABC is 65666768656667
 
    string constr = "User Id=scott;Password=tiger;Data Source=oracle";
    OracleConnection con = new OracleConnection(constr);
    con.Open();
 
    OracleBFile bFile = new OracleBFile(con, "MYDIR", "MyFile.txt");
 
    // Open the OracleBFile
    bFile.OpenFile();
    
    // Set the Position to 2 with respect to SeekOrigin.Begin
    long newPosition = bFile.Seek(2, SeekOrigin.Begin);
 
    // Prints "newPosition     = 2"
    Console.WriteLine("newPosition     = " + newPosition);    
 
    // Prints "bFile.Position  = 2"
    Console.WriteLine("bFile.Position  = " + bFile.Position);    
 
    // Read 2 bytes into readBuffer, starting at buffer offset 1
    byte[] readBuffer = new byte[4];    
    int bytesRead = bFile.Read(readBuffer, 1, 2);
    
    // Prints "bytesRead       = 2"
    Console.WriteLine("bytesRead       = " + bytesRead);    
 
    // Prints "readBuffer      = 067680"
    Console.Write("readBuffer      = ");
    for(int index = 0; index <  readBuffer.Length; index++)
    {
      Console.Write(readBuffer[index]);
    }
    Console.WriteLine();
    
    // Close the OracleBFile
    bFile.CloseFile();
 
    bFile.Close();
    bFile.Dispose();
 
    con.Close();
    con.Dispose();
  }
}