Oracle® Data Provider for .NET Developer's Guide 10g Release 2 (10.2) Part Number B14307-01 |
|
|
View PDF |
An OracleClob
is an object that has a reference to CLOB
data. It provides methods for performing operations on CLOB
s.
Note:
TheOracleClob
object uses the client side character set when retrieving or writing CLOB
data using a .NET Framework byte array.Class Inheritance
Object
MarshalByRefObject
Stream
OracleClob
Declaration
// C# public sealed class OracleClob : Stream, ICloneable
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 OracleClobSample { static void Main() { string constr = "User Id=scott;Password=tiger;Data Source=oracle"; OracleConnection con = new OracleConnection(constr); con.Open(); OracleClob clob = new OracleClob(con); // Write 4 chars from writeBuffer, starting at buffer offset 0 char[] writeBuffer = new char[4] {'a', 'b', 'c', 'd'}; clob.Write(writeBuffer, 0, 4); // Append first 2 chars from writeBuffer {'a', 'b'} to the oracleClob clob.Append(writeBuffer, 0, 2); // Prints "clob.Length = 12" Console.WriteLine("clob.Length = " + clob.Length); // Reset the Position for the Read clob.Position = 0; // Read 6 chars into readBuffer, starting at buffer offset 0 char[] readBuffer = new char[6]; int charsRead = clob.Read(readBuffer, 0, 6); // Prints "charsRead = 6" Console.WriteLine("charsRead = " + charsRead); // Prints "readBuffer = abcdab" Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); // Search for the 2nd occurrence of a char pattern 'ab' // starting from char offset 0 in the OracleClob char[] pattern = new char[2] {'a', 'b'}; long posFound = clob.Search(pattern, 0, 2); // Prints "posFound = 5" Console.WriteLine("posFound = " + posFound); // Erase 4 chars of data starting at char offset 1 // Sets chars to '' clob.Erase(1, 4); //Prints "clob.Value = a b" Console.WriteLine("clob.Value = " + clob.Value); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } }
Requirements
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
See Also:
OracleClob
members are listed in the following tables:
OracleClob Constructors
OracleClob
constructors are listed in Table 10-19.
Table 10-19 OracleClob Constructors
Constructor | Description |
---|---|
OracleClob Constructors |
Creates an instance of the OracleClob class bound to a temporary CLOB (Overloaded) |
OracleClob Static Fields
OracleClob
static fields are listed in Table 10-20.
Table 10-20 OracleClob Static Fields
Field | Description |
---|---|
MaxSize |
Holds the maximum number of bytes a CLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes |
OracleClob Static Methods
OracleClob
static methods are listed in Table 10-21.
OracleClob Instance Properties
OracleClob
instance properties are listed in Table 10-22.
Table 10-22 OracleClob 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 stream can be written |
Connection |
Indicates the OracleConnection that is used to retrieve and write CLOB data |
IsEmpty |
Indicates whether the CLOB is empty or not |
IsInChunkWriteMode |
Indicates whether or not the CLOB has been opened |
IsNCLOB |
Indicates whether or not the OracleClob object represents an NCLOB . |
IsTemporary |
Indicates whether or not the current instance is bound to a temporary CLOB |
Length |
Indicates the size of the CLOB data in bytes |
OptimumChunkSize |
Indicates the minimum number of bytes to retrieve or send from the database during a read or write operation |
Position |
Indicates the current read or write position in the LOB stream in bytes |
Value |
Returns the data, starting from the first character in the CLOB or NCLOB , as a string |
OracleClob Instance Methods
The OracleClob
instance methods are listed in Table 10-23.
Table 10-23 OracleClob Instance Methods
Methods | Description |
---|---|
Append |
Appends data to the current OracleClob instance (Overloaded) |
BeginChunkWrite |
Opens the CLOB |
BeginRead |
Inherited from Stream |
BeginWrite |
Inherited from Stream |
Clone |
Creates a copy of an OracleClob object |
Close |
Closes the current stream and releases resources associated with it |
Compare |
Compares data referenced by the current instance to that of the supplied object |
CopyTo |
Copies the data to an OracleClob (Overloaded) |
CreateObjRef |
Inherited from MarshalByRefObject |
Dispose |
Releases resources allocated by this object |
EndChunkWrite |
Closes the CLOB referenced by the current OracleClob instance |
EndRead |
Inherited from Stream |
EndWrite |
Inherited from Stream |
Equals |
Inherited from Object (Overloaded) |
Erase |
Erases the specified amount of data (Overloaded) |
Flush |
Not supported |
GetHashCode |
Returns a hash code for the current instance |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializeLifetimeService |
Inherited from MarshalByRefObject |
IsEqual |
Compares the LOB data referenced by two OracleClob s |
Read |
Reads from the current instance (Overloaded) |
ReadByte |
Inherited from Stream |
Search |
Searches for a character pattern in the current instance of OracleClob (Overloaded) |
Seek |
Sets the position in the current LOB stream |
SetLength |
Trims or truncates the CLOB value |
ToString |
Inherited from Object |
Write |
Writes the provided buffer into the OracleClob (Overloaded) |
WriteByte |
Inherited from Stream |
OracleClob
constructors create instances of the OracleClob
class bound to a temporary CLOB
.
Overload List:
This constructor creates an instance of the OracleClob
class bound to a temporary CLOB
with an OracleConnection
object.
OracleClob(OracleConnection, bool, bool)
This constructor creates an instance of the OracleClob
class that is bound to a temporary CLOB
, with an OracleConnection
object, a boolean value for caching, and a boolean value for NCLOB
.
This constructor creates an instance of the OracleClob
class bound to a temporary CLOB
with an OracleConnection
object.
Declaration
// C#
public OracleClob(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. OracleClob
does not open the connection implicitly. The temporary CLOB
utilizes the provided connection to store CLOB
data. Caching is not enabled by default.
This constructor creates an instance of the OracleClob
class that is bound to a temporary CLOB
, with an OracleConnection
object, a boolean value for caching, and a boolean value for NCLOB
.
Declaration
// C# public OracleClob(OracleConnection con, bool bCaching, bool bNCLOB);
Parameters
con
The OracleConnection
object connection.
bCaching
A flag that indicates whether or not server-side caching is enabled.
bNCLOB
A flag that is set to true
if the instance is a NCLOB
or false
if it is a CLOB
.
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. OracleClob
does not open the connection implicitly. The temporary CLOB
or NCLOB
uses the provided connection to store CLOB
data.
OracleClob
static fields are listed in Table 10-24.
Table 10-24 OracleClob Static Fields
Field | Description |
---|---|
MaxSize |
Holds the maximum number of bytes a CLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes |
The MaxSize
field holds the maximum number of bytes a CLOB
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 your operation exceeds the maximum length (in bytes) allowed.
OracleClob
static methods are listed in Table 10-25.
OracleClob
instance properties are listed in Table 10-26.
Table 10-26 OracleClob 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 stream can be written |
Connection |
Indicates the OracleConnection that is used to retrieve and write CLOB data |
IsEmpty |
Indicates whether the CLOB is empty or not |
IsInChunkWriteMode |
Indicates whether or not the CLOB has been opened |
IsNCLOB |
Indicates whether or not the OracleClob object represents an NCLOB . |
IsTemporary |
Indicates whether or not the current instance is bound to a temporary CLOB |
Length |
Indicates the size of the CLOB data in bytes |
OptimumChunkSize |
Indicates the minimum number of bytes to retrieve or send from the database during a read or write operation |
Position |
Indicates the current read or write position in the LOB stream in bytes |
Value |
Returns the data, starting from the first character in the CLOB or NCLOB , as a string |
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
.
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
.
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
.
This instance property indicates the OracleConnection
that is used to retrieve and write CLOB
data.
Declaration
// C# public OracleConnection Connection {get;}
Property Value
An OracleConnection
.
Exceptions
ObjectDisposedException
- The object is already disposed.
This instance property indicates whether the CLOB
is empty or not.
Declaration
// C# public bool IsEmpty {get;}
Property Value
A bool
.
Exceptions
ObjectDisposedException
- The object is already disposed.
This instance property indicates whether or not the CLOB
has been opened to defer index updates.
Declaration
// C# public bool IsInChunkWriteMode{get;}
Property Value
If the CLOB
has been opened, returns true
; otherwise, returns false
.
This instance property indicates whether or not the OracleClob
object represents an NCLOB
.
Declaration
// C# public bool IsNCLOB {get;}
Property Value
A bool
.
This instance property indicates whether or not the current instance is bound to a temporary CLOB
.
Declaration
// C# public bool IsTemporary {get;}
Property Value
A bool
.
Overrides Stream
This instance property indicates the size of the CLOB
data in bytes.
Declaration
// C# public override Int64 Length {get;}
Property Value
An Int64
that indicates the size of the CLOB
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.
This instance property indicates the minimum number of bytes to retrieve or send from the database during a read or write operation.
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.
Overrides Stream
This instance property indicates the current read or write position in the LOB stream in bytes.
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
.
This instance property returns the data, starting from the first character in the CLOB
or NCLOB
, as a string.
Declaration
// C# public string Value{get;}
Property Value
A string.
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 neither used nor changed by using this property.
The maximum string length that can be returned by this property is 2 GB.
The OracleClob
instance methods are listed in Table 10-27.
Table 10-27 OracleClob Instance Methods
Methods | Description |
---|---|
Append |
Appends data to the current OracleClob instance (Overloaded) |
BeginChunkWrite |
Opens the CLOB |
BeginRead |
Inherited from Stream |
BeginWrite |
Inherited from Stream |
Clone |
Creates a copy of an OracleClob object |
Close |
Closes the current stream and releases resources associated with it |
Compare |
Compares data referenced by the current instance to that of the supplied object |
CopyTo |
Copies the data to an OracleClob (Overloaded) |
CreateObjRef |
Inherited from MarshalByRefObject |
Dispose |
Releases resources allocated by this object |
EndChunkWrite |
Closes the CLOB referenced by the current OracleClob instance |
EndRead |
Inherited from Stream |
EndWrite |
Inherited from Stream |
Equals |
Inherited from Object (Overloaded) |
Erase |
Erases the specified amount of data (Overloaded) |
Flush |
Not supported |
GetHashCode |
Returns a hash code for the current instance |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializeLifetimeService |
Inherited from MarshalByRefObject |
IsEqual |
Compares the LOB data referenced by two OracleClob s |
Read |
Reads from the current instance (Overloaded) |
ReadByte |
Inherited from Stream |
Search |
Searches for a character pattern in the current instance of OracleClob (Overloaded) |
Seek |
Sets the position in the current LOB stream |
SetLength |
Trims or truncates the CLOB value |
ToString |
Inherited from Object |
Write |
Writes the provided buffer into the OracleClob (Overloaded) |
WriteByte |
Inherited from Stream |
This instance method appends data to the current OracleClob
instance.
Overload List:
This instance method appends the CLOB
data referenced by the provided OracleClob
object to the current OracleClob
instance.
This instance method appends data at the end of the CLOB
, from the supplied byte array buffer, starting from offset (in bytes) of the supplied byte array buffer.
This instance method appends data from the supplied character array buffer to the end of the current OracleClob
instance, starting at the offset (in characters) of the supplied character buffer.
This instance method appends the CLOB
data referenced by the provided OracleClob
object to the current OracleClob
instance.
Declaration
// C#
public void Append(OracleClob obj);
Parameters
obj
An OracleClob
object.
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.
This instance method appends data at the end of the CLOB
, from the supplied byte array buffer, starting from offset (in bytes) of the supplied byte array buffer.
Declaration
// C# public int Append(byte[] buffer, int offset, int count);
Parameters
buffer
An array of bytes, representing a Unicode string.
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.
ArgumentOutOfRangeException
- Either the offset
or the count
parameter is not even.
Remarks
Both offset
and count
must be even numbers for CLOB
and NCLOB
because every two bytes represent a Unicode character.
This instance method appends data from the supplied character array buffer to the end of the current OracleClob
instance, starting at the offset (in characters) of the supplied character buffer.
Declaration
// C# public void Append(char[] buffer, int offset, int count);
Parameters
buffer
An array of characters.
offset
The zero-based offset (in characters) in the buffer from which data is read.
count
The number of characters 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(); OracleClob clob = new OracleClob(con); // Append 2 chars {'d', 'e'} to the OracleClob char[] buffer = new char[3] {'d', 'e', 'f'}; clob.Append(buffer, 0, 2); // Prints "clob.Value = de" Console.WriteLine("clob.Value = " + clob.Value); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } }
This instance method opens the CLOB
.
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 CLOB
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 OracleClob
object.
Declaration
// C# public object Clone();
Return Value
An OracleClob
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(); OracleClob clob1 = new OracleClob(con); // Prints "clob1.Position = 0" Console.WriteLine("clob1.Position = " + clob1.Position); // Set the Position before calling Clone() clob1.Position = 1; // Clone the OracleClob OracleClob clob2 = (OracleClob)clob1.Clone(); // Prints "clob2.Position = 1" Console.WriteLine("clob2.Position = " + clob2.Position); clob1.Close(); clob1.Dispose(); clob2.Close(); clob2.Dispose(); con.Close(); con.Dispose(); } }
Overrides Stream
This instance method closes the current stream and releases resources associated with it.
Declaration
// C# public override void Close();
This instance method compares data referenced by the current instance to that of the supplied object.
Declaration
// C# public int Compare(Int64 src_offset, OracleClob obj, Int64 dst_offset, Int64 amount);
Parameters
src_offset
The comparison starting point (in characters) for the current instance.
obj
The provided OracleClob
object.
dst_offset
The comparison starting point (in characters) for the provided OracleClob
.
amount
The number of characters to compare.
Return Value
The method 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
- Either the src_offset
, dst_offset
, or amount
parameter is less than 0
.
Remarks
The character set of the two OracleClob
objects being compared should be the same for a meaningful comparison.
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 OracleClob
object.
Overload List:
This instance method copies data from the current instance to the provided OracleClob
object.
This instance method copies data from the current OracleClob
instance to the provided OracleClob
object with the specified destination offset.
CopyTo(Int64, OracleClob, Int64, Int64)
This instance method copies data from the current OracleClob
instance to the provided OracleClob
object with the specified source offset, destination offset, and character amounts.
This instance method copies data from the current 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.
This instance method copies data from the current OracleClob
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 to which the data is copied.
dst_offset
The offset (in characters) at which the OracleClob
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 OracleClob
data, spaces are written into the OracleClob
until the dst_offset
is met.
The offsets are 0
-based. No character conversion is performed by this operation.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection
object.
This instance method copies data from the current OracleClob
instance to the provided OracleClob
object with the specified source offset, destination offset, and character amounts.
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
The OracleClob
object to which the data is copied.
dst_offset
The offset (in characters) at which the OracleClob
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 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.
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(); OracleClob clob1 = new OracleClob(con); OracleClob clob2 = new OracleClob(con); // Write 4 chars, starting at buffer offset 0 char[] buffer = new char[4] {'a', 'b', 'c', 'd'}; clob1.Write(buffer, 0, 4); // Copy 2 chars from char 0 of clob1 to char 1 of clob2 clob1.CopyTo(0, clob2, 1, 2); //Prints "clob2.Value = ab" Console.WriteLine("clob2.Value = " + clob2.Value); clob1.Close(); clob1.Dispose(); clob2.Close(); clob2.Dispose(); con.Close(); con.Dispose(); } }
This instance method releases resources allocated by this object.
Declaration
public void Dispose();
Implements
IDisposable
Remarks
The object cannot be reused after being disposed. Although some properties can still be accessed, their values cannot be accountable. Since resources are freed, method calls can lead to exceptions.
This instance method closes the CLOB
referenced by the current OracleClob
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 write operation(s) are deferred by the BeginChunkWrite
method.
Erase
erases part or all data.
Overload List:
This instance method erases all data.
This instance method replaces the specified amount
of data (in characters) starting from the specified offset
with zero-byte fillers (in characters).
This instance method erases all data.
Declaration
// C# public Int64 Erase();
Return Value
The number of characters erased.
This instance method replaces the specified amount
of data (in characters) starting from the specified offset
with zero-byte fillers (in characters).
Declaration
// C# public Int64 Erase(Int64 offset, Int64 amount);
Parameters
offset
The offset.
amount
The amount of data.
Return Value
The actual number of characters 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
.
Overrides Object
This method returns a hash code for the current instance.
Declaration
// C# public override int GetHashCode();
Return Value
An int
representing a hash code.
This instance method compares the LOB data referenced by two OracleClob
s.
Declaration
// C#
public bool IsEqual(OracleClob obj);
Parameters
obj
An OracleClob
object.
Return Value
Returns true
if the current OracleClob
and the provided OracleClob
refer to the same LOB. Otherwise, returns false
.
Remarks
Note that this method can return true
even if the two OracleClob
objects returns false
for == or Equals()
because two different OracleClob
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
reads a specified amount from the current instance and populates the array buffer.
Overload List:
This instance method reads a specified amount of bytes from the current instance and populates the byte array buffer
.
This instance method reads a specified amount of characters from the current instance and populates the character array buffer.
Overrides Stream
This instance method reads a specified amount of bytes from the current instance and populates the byte array buffer
.
Declaration
// C# public override int Read(byte [ ] buffer, int offset, int count);
Parameters
buffer
The byte array buffer that is populated.
offset
The offset (in bytes) at which the buffer is populated.
count
The amount of bytes to be read.
Return Value
The number of bytes read from the CLOB
.
Exceptions
ObjectDisposedException
- The object is already disposed.
InvalidOperationException
- The OracleConnection
is not open or has been closed during the lifetime of the object.
Remarks
Both offset
and count
must be even numbers for CLOB
and NCLOB
because every two bytes represent a Unicode character.
The LOB data is read starting from the position specified by the Position
property, which must also be an even number.
OracleClob
is free to return fewer bytes than requested, even if the end of the stream has not been reached.
This instance method reads a specified amount of characters from the current instance and populates the character array buffer.
Declaration
// C# public int Read(char[ ] buffer, int offset, int count);
Parameters
buffer
The character array buffer that is populated.
offset
The offset (in characters) at which the buffer is populated.
count
The amount of characters to be read.
Return Value
The return value indicates the number of characters read from the CLOB
.
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
Handles all CLOB
and NCLOB
data as Unicode.
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(); OracleClob clob = new OracleClob(con); // Write 3 chars, starting at buffer offset 1 char[] writeBuffer = new char[4] {'a', 'b', 'c', 'd'}; clob.Write(writeBuffer, 1, 3); // Reset the Position (in bytes) for Read clob.Position = 2; // Read 2 chars into buffer starting at buffer offset 1 char[] readBuffer = new char[4]; int charsRead = clob.Read(readBuffer, 1, 2); // Prints "charsRead = 2" Console.WriteLine("charsRead = " + charsRead); // Prints "readBuffer = cd " Console.Write("readBuffer = "); for(int index = 0; index < readBuffer.Length; index++) { Console.Write(readBuffer[index]); } Console.WriteLine(); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } }
Search
searches for a character pattern in the current instance of OracleClob
.
Overload List:
This instance method searches for a character pattern, represented by the byte array, in the current instance of OracleClob
.
This instance method searches for a character pattern in the current instance of OracleClob
.
This instance method searches for a character pattern, represented by the byte array, in the current instance of OracleClob
.
Declaration
// C# public int Search(byte[ ] val, Int64 offset, Int64 nth);
Parameters
val
A Unicode byte array.
offset
The 0
-based offset (in characters) starting from which the OracleClob
is searched.
nth
The specific occurrence (1
-based) of the match for which the absolute offset (in characters) 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 nth
is greater than or equal to OracleClob.MaxSize
.
The offset
is greater than or equal to OracleClob.MaxSize
.
Remarks
The byte[
]
is converted to Unicode before the search is made.
The limit of the search pattern is 16383 bytes.
This instance method searches for a character pattern in the current instance of OracleClob
.
Declaration
// C# public Int64 Search(char [ ] val, Int64 offset, Int64 nth);
Parameters
val
The Unicode string being searched for.
offset
The 0
-based offset (in characters) starting from which the OracleClob
is searched.
nth
The specific occurrence (1
-based) of the match for which the absolute offset (in characters) is returned.
Return Value
Returns the absolute offset
of the start of the matched pattern (in characters) 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
doubled is greater than 16383
.
The nth
is greater than or equal to OracleClob.MaxSize
.
The offset
is greater than or equal to OracleClob.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(); OracleClob clob = new OracleClob(con); // Write 7 chars, starting at buffer offset 0 char[] buffer = new char[7] {'a', 'b', 'c', 'd', 'a', 'b', 'c'}; clob.Write(buffer, 0, 7); // Search for the 2nd occurrence of a char pattern 'bc' // starting at offset 1 in the OracleBlob char[] pattern = new char[2] {'b', 'c'}; long posFound = clob.Search(pattern, 1, 2); // Prints "posFound = 6" Console.WriteLine("posFound = " + posFound); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } }
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 characters 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 characters 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 CLOB
value to the specified length (in characters).
Declaration
// C#
public override void SetLength(Int64 newlen);
Parameters
newlen
The desired length of the current stream in characters.
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 greater than 0
.
This instance method writes data from the provided array buffer into the OracleClob
.
Overload List:
This instance method writes data from the provided byte array buffer into the OracleClob
.
This instance method writes data from the provided character array buffer into the OracleClob
.
Overrides Stream
This instance method writes data from the provided byte array buffer into the OracleClob
.
Declaration
// C# public override void Write(byte[ ] buffer, int offset, int count);
Parameters
buffer
The byte array buffer that represents a Unicode string.
offset
The offset (in bytes) from which the buffer
is read.
count
The amount of data (in bytes) from the buffer to be written into the OracleClob
.
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 the buffer
.Length
.
The offset
, the count
, or the Position
is not even.
Remarks
Both offset
and count
must be even numbers for CLOB
and NCLOB
because every two bytes represent a Unicode character.
The LOB data is read starting from the position specified by the Position
property. The Position
property must be an even number.
If necessary, proper data conversion is carried out from the client character set to the database character set.
This instance method writes data from the provided character array buffer into the OracleClob
.
Declaration
// C# public void Write(char[ ] buffer, int offset, int count);
Parameters
buffer
The character array buffer that is written to the OracleClob
.
offset
The offset (in characters) from which the buffer
is read.
count
The amount (in characters) from the buffer that is to be written into the OracleClob
.
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
.
The Position
is not even.
Remarks
Handles all CLOB
and NCLOB
data as Unicode.
The LOB data is read starting from the position specified by the Position
property.
If necessary, proper data conversion is carried out from the client character set to the database character set.
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(); OracleClob clob = new OracleClob(con); // Set the Position for the Write; clob.Position = 0; // Begin ChunkWrite to improve performance // Index updates occur only once after EndChunkWrite clob.BeginChunkWrite(); // Write to the OracleClob in 5 chunks of 2 chars each char[] c = new char[2] {'a', 'b'}; for (int index = 0; index < 5; index++) { clob.Write(c, 0, c.Length); } clob.EndChunkWrite(); // Prints "clob.Value = ababababab" Console.WriteLine("clob.Value = " + clob.Value); clob.Close(); clob.Dispose(); con.Close(); con.Dispose(); } }