OracleLob Class

Definition

Namespace:

System.Data.OracleClient

Assembly:

System.Data.OracleClient.dll

Represents a large object binary (LOB) data type stored on an Oracle server. This class cannot be inherited.

public ref class OracleLob sealed : System::IO::Stream, ICloneable, System::Data::SqlTypes::INullable

public sealed class OracleLob : System.IO.Stream, ICloneable, System.Data.SqlTypes.INullable

type OracleLob = class
    inherit Stream
    interface ICloneable
    interface IDisposable
    interface INullable

Public NotInheritable Class OracleLob
Inherits Stream
Implements ICloneable, INullable

Inheritance

Object

MarshalByRefObject

Stream

OracleLob

Implements

INullable ICloneable IDisposable

Remarks

An OracleLob differs from an OracleBFile in that the data is stored on the server instead of in a physical file in the operating system. It can also be a read-write object, unlike an OracleBFile, which is always read-only.

An OracleLob may be one of these OracleType data types.

OracleType data type	Description
Blob	An Oracle BLOB data type that contains binary data with a maximum size of 4 gigabytes (GB). This maps to an Array of type Byte.
Clob	An Oracle CLOB data type that contains character data, based on the default character set on the server, with a maximum size of 4 GB. This maps to String.
NClob	An Oracle NCLOB data type that contains character data, based on the national character set on the server with a maximum size of 4 GB. This maps to String.

A .NET application developer can retrieve the Oracle LOB values into basic .NET data types, such as Array of type Byte and String, or the specialized OracleLob data type. The OracleLob class supports reading data from and writing to the Oracle LOB in the Oracle database.

The following are the main characteristics of an OracleLob data type that distinguish it from basic .NET data types:

• After you retrieve the Oracle LOB value from the Oracle database into the OracleLob class, you can change the LOB data in an open transaction and your changes are directly reflected to the database. If you retrieve the Oracle LOB value into an Array of type Byte or String and update these arrays, your changes are not reflected to the database.

• When you use the OracleLob class to access a chunk of a LOB value, only that chunk is passed from the Oracle database to the client. When you use the GetChars method to access a chunk of a LOB value, the entire contents of the value are passed from the Oracle database to the client.

To obtain an OracleLob object, call the GetOracleLob method.

You can construct an OracleLob that is NULL using this format:

OracleLob myLob = OracleLob.Null;  

Dim myLob As OracleLob = OracleLob.Null

This technique is used primarily to test whether a LOB returned from the server is NULL, as this example illustrates:

if (myLob == OracleLob.Null)  

If (myLob = OracleLob.Null) Then

A NULL LOB behaves similarly to a zero-byte LOB in that Read succeeds and always returns zero bytes.

Selecting a LOB column that contains a null value returns Null.

You must begin a transaction before obtaining a temporary LOB. Otherwise, the OracleDataReader may fail to obtain data later.

You can also open a temporary LOB in Oracle by calling the DBMS_LOB.CREATETEMPORARY system stored procedure and binding a LOB output parameter. On the client side, a temporary LOB behaves like a table-based LOB. For example, to update the temporary LOB, it must be enclosed in a transaction.

The following example demonstrates how to open a temporary LOB:

var connection = new OracleConnection("server=MyServer; integrated security=yes;");  
connection.Open();  
OracleTransaction transaction = connection.BeginTransaction();  
OracleCommand command = connection.CreateCommand();  
command.Transaction = transaction;  
command.CommandText = "declare xx blob; begin dbms_lob.createtemporary(xx, false, 0); :tempblob := xx; end;";  
command.Parameters.Add(new OracleParameter("tempblob", OracleType.Blob)).Direction = ParameterDirection.Output;  
command.ExecuteNonQuery();  
var tempLob = (OracleLob)command.Parameters[0].Value;  
var tempbuff = new byte[10000];  
tempLob.BeginBatch(OracleLobOpenMode.ReadWrite);  
tempLob.Write(tempbuff,0,tempbuff.Length);  
tempLob.EndBatch();  
command.Parameters.Clear();  
command.CommandText = "MyTable.MyProc";  
command.CommandType = CommandType.StoredProcedure;    
command.Parameters.Add(new OracleParameter("ImportDoc", OracleType.Blob)).Value = tempLob;  
command.ExecuteNonQuery();  
transaction.Commit();  
connection.Close(); 

Note

The inherited WriteByte method fails if used with character data, and an InvalidOperationException is thrown. Use the Write method instead.

Temporary LOBs are only closed when the connection is closed, but with pooling and under load, temporary LOBs do not close. This can be resolved by disposing the temporary LOB, by invoking tempLob.Dispose().

Fields

Null	Represents a null OracleLob object.

Properties

CanRead	Gets a value indicating whether the LOB stream can be read.
CanSeek	Gets a value indicating whether forward and backward seek operations can be performed.
CanTimeout	Gets a value that determines whether the current stream can time out. (Inherited from Stream)
CanWrite	Always returns true, regardless of whether the LOB supports writing or not.
ChunkSize	Gets a value indicating the minimum number of bytes to retrieve from or send to the server during a read/write operation.
Connection	Gets the OracleConnection used by this instance of the OracleLob.
IsBatched	Gets a value indicating whether an application called the BeginBatch() method.
IsNull	Gets a value that indicates whether the OracleLob is a Null stream.
IsTemporary	Gets a value indicating whether the OracleLob is a temporary LOB.
Length	Gets a value that returns the size of the OracleLob.
LobType	Gets a value that returns the LOB data type.
Position	Gets the current read position in the OracleLob stream.
ReadTimeout	Gets or sets a value, in milliseconds, that determines how long the stream will attempt to read before timing out. (Inherited from Stream)
Value	Gets the common language runtime stream value equivalent of the underlying value.
WriteTimeout	Gets or sets a value, in milliseconds, that determines how long the stream will attempt to write before timing out. (Inherited from Stream)

Methods

Append(OracleLob)	Appends data from the specified LOB to the current LOB.
BeginBatch()	Prevents server-side triggers from firing while performing multiple read operations.
BeginBatch(OracleLobOpenMode)	Prevents server-side triggers from firing while performing multiple read and write operations in the specified access mode.
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)	Begins an asynchronous read operation. (Consider using ReadAsync(Byte[], Int32, Int32) instead.) (Inherited from Stream)
BeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)	Begins an asynchronous write operation. (Consider using WriteAsync(Byte[], Int32, Int32) instead.) (Inherited from Stream)
Clone()	Creates a new OracleLob object that references the same Oracle LOB as the original OracleLob object.
Close()	Closes the current stream and releases any resources (such as sockets and file handles) associated with the current stream. Instead of calling this method, ensure that the stream is properly disposed. (Inherited from Stream)
CopyTo(Int64, OracleLob, Int64, Int64)	Copies from this OracleLob to a destination OracleLob with the specified amount of data, and the source offset.
CopyTo(OracleLob, Int64)	Copies from this OracleLob to a destination OracleLob with the specified amount of data.
CopyTo(OracleLob)	Copies from this OracleLob to a destination OracleLob.
CopyTo(Stream, Int32)	Reads the bytes from the current stream and writes them to another stream, using a specified buffer size. Both streams positions are advanced by the number of bytes copied. (Inherited from Stream)
CopyTo(Stream)	Reads the bytes from the current stream and writes them to another stream. Both streams positions are advanced by the number of bytes copied. (Inherited from Stream)
CopyToAsync(Stream, CancellationToken)	Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified cancellation token. Both streams positions are advanced by the number of bytes copied. (Inherited from Stream)
CopyToAsync(Stream, Int32, CancellationToken)	Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size and cancellation token. Both streams positions are advanced by the number of bytes copied. (Inherited from Stream)
CopyToAsync(Stream, Int32)	Asynchronously reads the bytes from the current stream and writes them to another stream, using a specified buffer size. Both streams positions are advanced by the number of bytes copied. (Inherited from Stream)
CopyToAsync(Stream)	Asynchronously reads the bytes from the current stream and writes them to another stream. Both streams positions are advanced by the number of bytes copied. (Inherited from Stream)
CreateObjRef(Type)	Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject)
CreateWaitHandle()	Obsolete. Allocates a WaitHandle object. (Inherited from Stream)
Dispose()	Releases all resources used by the Stream. (Inherited from Stream)
Dispose(Boolean)	Releases the unmanaged resources used by the Stream and optionally releases the managed resources. (Inherited from Stream)
DisposeAsync()	Asynchronously releases the unmanaged resources used by the Stream. (Inherited from Stream)
EndBatch()	Allows server-side triggers to resume firing after performing multiple write operations.
EndRead(IAsyncResult)	Waits for the pending asynchronous read to complete. (Consider using ReadAsync(Byte[], Int32, Int32) instead.) (Inherited from Stream)
EndWrite(IAsyncResult)	Ends an asynchronous write operation. (Consider using WriteAsync(Byte[], Int32, Int32) instead.) (Inherited from Stream)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
Erase()	Erases all data from this OracleLob.
Erase(Int64, Int64)	Erases the specified amount of data from this OracleLob.
Flush()	Not currently supported.
FlushAsync()	Asynchronously clears all buffers for this stream and causes any buffered data to be written to the underlying device. (Inherited from Stream)
FlushAsync(CancellationToken)	Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests. (Inherited from Stream)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetLifetimeService()	Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject)
GetType()	Gets the Type of the current instance. (Inherited from Object)
InitializeLifetimeService()	Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
MemberwiseClone(Boolean)	Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject)
ObjectInvariant()	Obsolete. Provides support for a Contract. (Inherited from Stream)
Read(Byte[], Int32, Int32)	Reads a sequence of bytes from the current OracleLob stream and advances the position within the stream by the number of bytes read.
Read(Span<Byte>)	When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read. (Inherited from Stream)
ReadAsync(Byte[], Int32, Int32, CancellationToken)	Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests. (Inherited from Stream)
ReadAsync(Byte[], Int32, Int32)	Asynchronously reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read. (Inherited from Stream)
ReadAsync(Memory<Byte>, CancellationToken)	Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests. (Inherited from Stream)
ReadAtLeast(Span<Byte>, Int32, Boolean)	Reads at least a minimum number of bytes from the current stream and advances the position within the stream by the number of bytes read. (Inherited from Stream)
ReadAtLeastAsync(Memory<Byte>, Int32, Boolean, CancellationToken)	Asynchronously reads at least a minimum number of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests. (Inherited from Stream)
ReadByte()	Reads a byte from the stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream. (Inherited from Stream)
ReadExactly(Byte[], Int32, Int32)	Reads count number of bytes from the current stream and advances the position within the stream. (Inherited from Stream)
ReadExactly(Span<Byte>)	Reads bytes from the current stream and advances the position within the stream until the buffer is filled. (Inherited from Stream)
ReadExactlyAsync(Byte[], Int32, Int32, CancellationToken)	Asynchronously reads count number of bytes from the current stream, advances the position within the stream, and monitors cancellation requests. (Inherited from Stream)
ReadExactlyAsync(Memory<Byte>, CancellationToken)	Asynchronously reads bytes from the current stream, advances the position within the stream until the buffer is filled, and monitors cancellation requests. (Inherited from Stream)
Seek(Int64, SeekOrigin)	Sets the position on the current OracleLob stream.
SetLength(Int64)	Sets the length of the OracleLob stream to a value less than the current length.
ToString()	Returns a string that represents the current object. (Inherited from Object)
Write(Byte[], Int32, Int32)	Writes a sequence of bytes to the current OracleLob stream, and advances the current position within this stream by the number of bytes written.
Write(ReadOnlySpan<Byte>)	When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written. (Inherited from Stream)
WriteAsync(Byte[], Int32, Int32, CancellationToken)	Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. (Inherited from Stream)
WriteAsync(Byte[], Int32, Int32)	Asynchronously writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written. (Inherited from Stream)
WriteAsync(ReadOnlyMemory<Byte>, CancellationToken)	Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests. (Inherited from Stream)
WriteByte(Byte)	Writes a byte to the current position in the OracleLob stream, and advances the position within the stream by one byte.

Extension Methods

CopyToAsync(Stream, PipeWriter, CancellationToken)

Asynchronously reads the bytes from the Stream and writes them to the specified PipeWriter, using a cancellation token.