Release 9.2.0.4
Part Number B10961-01
 Contents |
 Index |
| Oracle® Data Provider for .NET Developer's Guide Release 9.2.0.4 Part Number B10961-01 |
|
Oracle.DataAccess.Types Namespace (ODP.NET Types), 16 of 19
An OracleClob is an object that has a reference to CLOB data. It provides methods for performing operations on CLOBs.
Object
MarshalByRefObject
Stream
OracleClob
// C# public sealed class OracleClob : Stream, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
// C# // Example demostrates Read, Append, Search, Write and, Erase APIs // assume: A valid connection 'con'is created OracleClob oraClob = new OracleClob(con); // Read some data (in characters) char buffer = new char[1024]; int bufferOffset = 10; int amountToBeRead = 10; int charRead = oraClob.Read(buffer, bufferOffset, amountToBeRead); // Search for the 2nd occurrence of a char pattern 'oracle' // from the oraClob starting at offset 1 char[6] pattern = new char[6] { "o", "r", "a", "c", "l", "e" }; int positionFound = oraClob.Search(pattern, 1, 2); // Append 2 char to the oraClob oraClob.Append(new char[3] {"f", "o", "o"}, 1, 2); // Write 32 char, starting at buffer offset 512 char[4096] buffer = new char[4096]; ... oraClob.Write(buffer, 512, 32); // Erase 64 char of data starting at offset=1024 oraClob.Erase(1024,64); ...
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
OracleClob members are listed in the following tables:
OracleClob constructors are listed in Table 5-165.
| Constructor | Description |
|---|---|
|
Creates an instance of the |
OracleClob static fields are listed in Table 5-166.
| Field | Description |
|---|---|
|
Holds the maximum number of bytes a |
OracleClob static methods are listed in Table 5-167.
| Methods | Description |
|---|---|
|
|
Inherited from |
OracleClob instance properties are listed in Table 5-168.
The OracleClob instance methods are listed in Table 5-169.
OracleClob constructors create instances of the OracleClob class bound to a temporary CLOB.
This constructor creates an instance of the OracleClob class bound to a temporary CLOB with an OracleConnection object.
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.
// C# public OracleClob(OracleConnection con);
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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.
// C# public OracleClob(OracleConnection con, bool bCaching, bool bNCLOB);
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.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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 5-170.
| Field | Description |
|---|---|
|
Holds the maximum number of bytes a |
The MaxSize field holds the maximum number of bytes a CLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes.
// C# public static readonly Int64 MaxSize = 4294967295;
This field is useful in code that checks whether your operation exceeds the maximum length (in bytes) allowed.
OracleClob static methods are listed in Table 5-171.
| Methods | Description |
|---|---|
|
|
Inherited from |
OracleClob instance properties are listed in Table 5-172.
Overrides Stream
This instance property indicates whether the LOB stream can be read.
// C# public override bool CanRead{get;}
If the LOB stream can be read, returns true; otherwise, returns false.
Overrides Stream
This instance property indicates whether forward and backward seek operations can be performed.
// C# public override bool CanSeek{get;}
If forward and backward seek operations can be performed, returns true; otherwise, returns false.
Overrides Stream
This instance property indicates whether the LOB object supports writing.
// C# public override bool CanWrite{get;}
If the LOB stream can be written, returns true; otherwise, returns false.
This instance property indicates the OracleConnection that is used to retrieve and write CLOB data.
// C# public OracleConnection Connection {get;}
An OracleConnection.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the CLOB is empty or not.
// C# public bool IsEmpty {get;}
A bool.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the CLOB has been opened to defer index updates.
// C# public bool IsInChunkWriteMode{get;}
If the CLOB has been opened, returns true; otherwise, returns false.
This instance property indicates whether the OracleClob object represents an NCLOB.
// C# public bool IsNCLOB {get;}
A bool.
This instance property indicates whether or not the current instance is bound to a temporary CLOB.
// C# public bool IsTemporary {get;}
A bool.
Overrides Stream
This instance property indicates the size of the CLOB data in bytes.
// C# public override Int64 Length {get;}
An Int64 that indicates the size of the CLOB in bytes.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This instance property indicates the minimum number of bytes to retrieve or send from the server during a read or write operation.
// C# public int OptimumChunkSize{get;}
A number representing the minimum bytes to retrieve or send.
ObjectDisposedException - The object is already disposed.
Overrides Stream
This instance property indicates the current read or write position in the LOB stream in bytes.
// C# public override Int64 Position{get; set;}
An Int64 that indicates the read or write position.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The Position is less than 0.
This instance property returns the data, starting from the first character in the CLOB or NCLOB, as a string.
// C# public string Value{get;}
A string.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The Value is less than 0.
The value of Position is 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 5-173.
This instance method appends data to the current OracleClob instance.
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.
// C# public void Append(OracleClob obj);
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened.
No character set conversions are made.
The provided object and the current instance must be using the same connection; that is, the same OracleConnection object.
This instance method appends data at the end of the CLOB, from the supplied byte array buffer, starting from offset (in bytes) of the supplied byte array buffer.
// C# public int Append(byte[] buffer, int offset, int count);
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.
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.
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.
// C# public void Append(char[] buffer, int offset, int count);
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.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
// C# ... // Append 2 char to the oraClob oraClob.Append(new char[3] {"f", "o", "o"}, 1, 2); ...
This instance method opens the CLOB.
// C# public void BeginChunkWrite();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
BeginChunkWrite does not need to be called before manipulating the 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.
// C# public object Clone();
An OracleClob object.
ICloneable
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The cloned object has the same property values as that of the object being cloned.
// C# ... //Need a proper casting for the return value when cloned OracleClob oraClob_cloned = (OracleClob) oraClob.Clone(); ...
Overrides Stream
This instance method closes the current stream and releases resources associated with it.
// C# public override void Close();
This instance method compares data referenced by the current instance to that of the supplied object.
// C# public int Compare(Int64 src_offset, OracleClob obj, Int64 dst_offset, Int64 amount);
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.
The method returns a value that is:
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened.
ArgumentOutOfRangeException - Either the src_offset, dst_offset, or amount parameter is less than 0.
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.
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.
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.
// C# public Int64 CopyTo(OracleClob obj);
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
This instance method copies data from the current OracleClob instance to the provided OracleClob object with the specified destination offset.
// C# public Int64 CopyTo(OracleClob obj, Int64 dst_offset);
obj
The OracleClob object to which the data is copied.
dst_offset
The offset (in characters) at which the OracleClob object is copied.
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
ArgumentOutOfRangeException - The dst_offset is less than 0.
InvalidOperationException - This exception is thrown if any of the following conditions exist:
OracleConnection is not open or has been closed during the lifetime of the object.
If the dst_offset is beyond the end of the 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.
// C# public Int64 CopyTo(Int64 src_offset,OracleClob obj,Int64 dst_offset,Int64 amount);
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.
The return value is the amount copied.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The parameter has a different connection than the object, OracleConnection is not opened, or OracleConnection has been reopened.
ArgumentOutOfRangeException - The src_offset, the dst_offset, or the amount parameter is less than 0.
If the dst_offset is beyond the end of the 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.
// C# ... // Assume you have a valid connection 'con' OracleClob src_clob = new OracleClob(con); OracleClob target_clob = new OracleClob(con); // Copy 1024 chars from src_clob (begin at offset 10) to target_blob // (starting at offset 5) src_clob.CopyTo(10, target_clob, 5, 1024); ...
This instance method releases resources allocated by this object.
public void Dispose();
IDisposable
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.
// C# public void EndChunkWrite();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Index updates occur immediately if write operation(s) are deferred by the BeginChunkWrite method.
Erase erases part or all data.
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.
// C# public Int64 Erase();
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).
// C# public Int64 Erase(Int64 offset, Int64 amount);
The actual number of characters erased.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The offset or amount parameter is less than 0.
Overrides Object
This method returns a hash code for the current instance.
// C# public override int GetHashCode();
An int representing a hash code.
This instance method compares the LOB data referenced by two OracleClobs.
// C# public bool IsEqual(OracleClob obj);
Returns true if the current OracleClob and the provided OracleClob refer to the same LOB. Otherwise, returns false.
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.
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.
// C# public override int Read(byte [ ] buffer, int offset, int count);
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.
The number of bytes read from the CLOB.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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.
// C# public int Read(char[ ] buffer, int offset, int count);
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.
The return value indicates the number of characters read from the CLOB.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset or the count is less than 0.
offset is greater than or equal to the buffer.Length.
offset and the count together are greater than buffer.Length.
Handles all CLOB and NCLOB data as Unicode.
The LOB data is read starting from the position specified by the Position property.
// C# ... // Read some data (in characters) char buffer = new char[1024]; int bufferOffset = 10; int amountToBeRead = 10; int charRead = oraClob.Read(buffer, bufferOffset, amountToBeRead); ...
Search 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.
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.
// C# public int Search(byte[ ] val, Int64 offset, Int64 nth);
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.
Returns the absolute offset of the start of the matched pattern (in bytes) for the nth occurrence of the match. Otherwise, 0 is returned.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset is less than 0.
nth is less than or equal to 0.
nth is greater than or equal to OracleClob.MaxSize.
offset is greater than or equal to OracleClob.MaxSize.
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.
// C# public Int64 Search(char [ ] val, Int64 offset, Int64 nth);
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.
Returns the absolute offset of the start of the matched pattern (in characters) for the nth occurrence of the match. Otherwise, 0 is returned.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset is less than 0.
nth is less than or equal to 0.
val.Length doubled is greater than 16383.
nth is greater than or equal to OracleClob.MaxSize.
offset is greater than or equal to OracleClob.MaxSize.
The limit of the search pattern is 16383 bytes.
// C# .. // Search for the 2nd occurrence of a char pattern 'oracle' // from the oraClob starting at offset 1 char[6] pattern = new char[6] { "o", "r", "a", "c", "l", "e" }; int positionFound = oraClob.Search(pattern, 1, 2); ...
Overrides Stream
This instance method sets the position on the current LOB stream.
// C# public override Int64(Int64 offset, SeekOrigin origin);
offset
A byte offset relative to origin.
origin
A value of type System.IO.SeekOrigin indicating the reference point used to obtain the new position.
Returns an Int64 that indicates the position.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
If offset is negative, the new position precedes the position specified by origin by the number of 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).
// C# public override void SetLength(Int64 newlen);
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The newlen parameter is greater than 0.
This instance method writes data from the provided array buffer into the OracleClob.
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.
// C# public override void Write(byte[ ] buffer, int offset, int count);
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.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset or the count is less than 0.
offset is greater than or equal to the buffer.Length.
offset and the count together are greater than the buffer.Length.
offset, the count, or the Position is not even.
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.
// C# public void Write(char[ ] buffer, int offset, int count);
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.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
offset or the count is less than 0.
offset is greater than or equal to the buffer.Length.
offset and the count together are greater than buffer.Length.
Position is not even.
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.
// C# ... // Begin ChunkWrite to improve performance // Index updates occur only once after EndChunkWrite oraClob.BeginChunkWrite(); // Set the write from the beginning; oraClob.Position = 0; // Write to the oraClob in chunks of 10, each 1024 char for ( int i=0; i<10; i++ ) { char[1024] c; c = c[0]= a; // some new value to be written oraClob.Write(c, 0, c.Length); } oraClob.EndChunkWrite(); ...
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|