| Oracle® Data Provider for .NET Developer's Guide 10g Release 1 (10.1) Part Number B10117-01 |
|
|
View PDF |
| Oracle® Data Provider for .NET Developer's Guide 10g Release 1 (10.1) Part Number B10117-01 |
|
|
View PDF |
This section covers the following object classes:
ODP.NET Types (ODP.NET LOB objects) consisting of these object classes:
All offsets are 0-based for all ODP.NET LOB and OracleXmlStream object parameters.
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 higher. |
Object
MarshalByRefObject
Stream
OracleBFile
// C# public sealed class OracleBFile : Stream, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
OracleBFile is supported for applications running against Oracle8.x and higher.
[C#]
...
// assume:
// 1. A valid connection is made
// 2. contains a file c:\MyDir\MyFile.txt
OracleBFile oraBFile = new OracleBFile(con, "c:\\MyDir", "MyFile.txt");
// Open the oraBFile
oraBFile.Open();
// Read some data
...
int byteRead = oraBFile.Read(buffer, bufferOffset, amountToBeRead);
// Search for the 2nd occurrence of a byte pattern '123'
// from oraBFile starting at offset 1
byte[] pattern = new byte[3] { 1,2,3 };
int positionFound = oraBFile.Search(pattern, 1, 2);
// Close the BFile
oraBFile.CloseFile();
...
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
OracleBFile members are listed in the following tables:
OracleBFile constructors are listed in Table 5-147.
Table 5-147 OracleBFile Constructors
| Constructor | Description |
|---|---|
| OracleBFile Constructors |
Creates an instance of the OracleBFile class (Overloaded) |
OracleBFile static fields are listed in Table 5-148.
Table 5-148 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 |
OracleBFile static methods are listed in Table 5-149.
Table 5-149 OracleBFile Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
OracleBFile instance properties are listed in Table 5-150.
Table 5-150 OracleBFile Instance Properties
| Properties | Description |
|---|---|
| CanRead | Indicates whether the LOB stream can be read |
| CanSeek | Indicates whether forward and backward seek operations can be performed |
| CanWrite |
Indicates whether 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 |
| 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 are listed in Table 5-151.
Table 5-151 OracleBFile Instance Methods
| Methods | Description |
|---|---|
BeginRead |
Inherited from 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 MarshalByRefObject |
| CopyTo |
Copies data as specified (Overloaded) |
| Dispose |
Releases resources allocated by this object |
EndRead |
Inherited from Stream |
EndWrite |
Not Supported |
Equals |
Inherited from Object (Overloaded) |
Flush |
Not Supported |
GetHashCode |
Inherited from Object |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializeLifetimeService |
Inherited from 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 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 Object |
Write |
Not Supported |
WriteByte |
Not Supported |
OracleBFile constructors create new instances of the OracleBFile class.
This constructor creates an instance of the OracleBFile class with an OracleConnection object.
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.
This constructor creates an instance of the OracleBFile class with an OracleConnection object.
// C# public OracleBFile(OracleConnection con);
con
The OracleConnection object.
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. OracleBFile does not open the connection implicitly.
This constructor creates an instance of the OracleBFile class with an OracleConnection object, the location of the BFILE, and the name of the BFILE.
// C# public OracleBFile(OracleConnection con, string directoryName, string fileName);
con
The OracleConnection object.
directoryName
The directory alias created by the CREATE DIRECTORY SQL statement.
fileName
The name of the external LOB.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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 are listed in Table 5-152.
Table 5-152 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 |
This static field holds the maximum number of bytes a BFILE 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 the operation exceeds the maximum length allowed.
OracleBFile static methods are listed in Table 5-153.
Table 5-153 OracleBFile Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
OracleBFile instance properties are listed in Table 5-154.
Table 5-154 OracleBFile Instance Properties
| Properties | Description |
|---|---|
| CanRead | Indicates whether the LOB stream can be read |
| CanSeek | Indicates whether forward and backward seek operations can be performed |
| CanWrite |
Indicates whether 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 |
| 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 |
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;}
BFILE is read only.
BFILE is read-only, therefore, the boolean value is always false.
This instance property indicates the connection used to read from a BFILE.
// C#
public OracleConnection Connection {get;}
An object of OracleConnection.
ObjectDisposedException - The object is already disposed.
This instance property indicates the directory alias of the BFILE.
// C#
public string DirectoryName {get;set;}
A string.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The value of the DirectoryName changed while the BFILE is open.
The maximum length of a DirectoryName is 30 bytes.
This instance property indicates whether or not the BFILE specified by the DirectoryName and FileName exists.
// C#
public bool FileExists {get;}
bool
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Unless a connection, file name, and directory name are provided, this property is set to false by default.
This instance property indicates the name of the BFILE.
// C#
public string FileName {get;set}
A string that contains the BFILE name.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The value of the DirectoryName changed while the BFILE is open.
The maximum length of a FileName is 255 bytes.
Changing the FileName property while the BFILE object is opened causes an exception.
This instance property indicates whether the BFILE is empty or not.
// C#
public bool IsEmpty {get;}
bool
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the BFILE has been opened by this instance or not.
// C#
public bool IsOpen {get;}
A bool.
Overrides Stream
This instance property indicates the size of the BFILE data in bytes.
// C#
public override Int64 Length {get;}
Int64
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Overrides Stream
This instance property indicates the current read position in the LOB stream.
// C#
public override Int64 Position{get; set;}
An Int64 value that indicates the read 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 value is less than 0.
This instance property returns the data, starting from the first byte in BFILE, as a byte array.
// C#
public byte[] Value{get;}
A byte array.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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 are listed in Table 5-155.
Table 5-155 OracleBFile Instance Methods
| Methods | Description |
|---|---|
BeginRead |
Inherited from 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 MarshalByRefObject |
| CopyTo |
Copies data as specified (Overloaded) |
| Dispose |
Releases resources allocated by this object |
EndRead |
Inherited from Stream |
EndWrite |
Not Supported |
Equals |
Inherited from Object (Overloaded) |
Flush |
Not Supported |
GetHashCode |
Inherited from Object |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializeLifetimeService |
Inherited from 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 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 Object |
Write |
Not Supported |
WriteByte |
Not Supported |
This instance method creates a copy of an OracleBFile object.
// C# public object Clone();
An OracleBFile 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 OracleBFile oraBfile_cloned = (OracleBFile) oraBfile.Clone(); ...
Overrides Stream
This instance method closes the current stream and releases any resources associated with it.
// C# public override void Close();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This instance method closes the BFILE referenced by the current BFILE instance.
// C# public void CloseFile();
No error is returned if the BFILE exists, but is not opened.
This instance method compares data referenced by the two OracleBFiles.
// C# public int Compare(Int64 src_offset, OracleBFile obj, Int64 dst_offset, Int64 amount);
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.
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.
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.
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.
// C#
...
// Assume you have 2 valid files in C:\MyDir
OracleBFile myBFile1 = new OracleBFile(con, "c:\\MyDir", "MyFile1.txt");
OracleBFile myBFile2 = new OracleBFile(con, "c:\\MyDir", "MyFile2.txt");
int src_offset = 10;
int dst_offset = 20;
int amount = 5;
int result = myBFile1.Compare(src_offset, myBFile2, dst_offset, amount);
if ( result == 0 )
Console.WriteLine("Identical");
else
Console.WriteLine("Not Identical");
...
CopyTo
CopyTo copies data from the current instance to the provided object.
This instance method copies data from the current instance to the provided OracleBlob object.
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.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object.
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.
This instance method copies data from the current instance to the provided OracleBlob object.
// C# public Int64 CopyTo(OracleBlob obj);
obj
The OracleBlob object to which the data is copied.
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:
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.
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 OracleBFile instance to the provided OracleBlob object with the specified destination offset.
// C# public Int64 CopyTo(OracleBlob obj, Int64 dst_offset);
obj
The OracleBlob object to which the data is copied.
dst_offset
The offset (in bytes) at which the OracleBlob 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:
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.
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.
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.
// C# public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset, Int64 amount);
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.
The return value is the amount copied.
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.
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.
This instance method copies data from the current OracleBFile instance to the provided OracleClob object.
// C# public Int64 CopyTo(OracleClob obj);
obj
The OracleClob object to which the data is copied.
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:
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.
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 OracleBFile instance to the provided OracleClob object with the specified destination offset.
// C# public Int64 CopyTo(OracleClob obj, Int64 dst_offset);
obj
The OracleClob object that the data is copied to.
dst_offset
The offset (in characters) at which the OracleClob object is copied to.
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:
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.
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 OracleBFile instance to the provided OracleClob object with the specified source offset, destination offset, and amount of characters.
// 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
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.
The return value is the amount copied.
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.
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.
This instance method releases resources allocated by this object.
// C# public void Dispose();
IDisposable
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.
This instance method compares the LOB references.
// C# public bool IsEqual(OracleBFile obj);
obj
The provided OracleBFile object.
Returns true if the current OracleBFile and the provided OracleBFile object refer to the same external LOB. Returns false otherwise.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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.
This instance method opens the BFILE specified by the FileName and DirectoryName.
// C# public void OpenFile();
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
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.
Overrides Stream
This instance method reads a specified amount of bytes from the OracleBFile instance and populates the buffer.
// C# public override int Read(byte[ ] buffer, int offset, int count);
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.
The return value indicates the number of bytes read from the BFILE, that is, the external LOB.
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.
The LOB data is read starting from the position specified by the Position property.
// C# ... byte buffer = new byte[1024]; int bufferOffset = 10; int amountToBeRead = 10; // Read some data int byteRead = oraBFile.Read(buffer, bufferOffset, amountToBeRead); ...
This instance method searches for a binary pattern in the current instance of an OracleBFile.
// C# public int Search(byte[ ] val, Int64 offset, Int64 nth);
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.
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 - 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.
The limit of the search pattern is 16383 bytes.
// C#
...
// Search for the 2nd occurrence of a byte pattern '123'
// from oraBFile starting at offset 1
byte[] pattern = new byte[3] { 1,2,3 };
int positionFound = oraBFile.Search(pattern, 1, 2);
...
Overrides Stream
This instance method sets the position on the current LOB stream.
// C# public override int64 Seek(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 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.
// C# ... // Set the Position to 5 bytes (with respect to SeekOrigin.Begin), read 10 bytes // out, and put the data in a buffer with offset = 10 bytes byte buffer = new byte[1024]; int bufferOffset = 10; int amountToBeRead = 10; // Seek int newPosition = oraBFile.Seek(5, SeekOrigin.Begin); // Read some data int byteRead = oraBFile.Read(buffer, bufferOffset, amountToBeRead); ...
An OracleBlob object is an object that has a reference to BLOB data. It provides methods for performing operations on BLOBs.
Object
MarshalByRefObject
Stream
OracleBlob
// C# public sealed class OracleBlob : Stream, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
[C#]
...
// assume: A valid connection is made
OracleBlob oraBlob = new OracleBlob(con);
// Read some data
...
int byteRead = oraBlob.Read(buffer, bufferOffset, amountToBeRead);
// Search for the 2nd occurrence of a byte pattern '123'
// from the oraBlob starting at offset 1
byte[] pattern = new byte[3] { 1,2,3 };
int positionFound = oraBlob.Search(pattern, 1, 2);
// Append 2 bytes {4,5} to the oraBlob
oraBlob.Append(new byte[3] {4,5,6}, 1, 2);
// Write 64 bytes, starting at buffer offset 512
byte[4096] buffer = new byte[4096];
...
oraBlob.Write(buffer, 512, 64);
// Erase 64 bytes of data starting at offset=1024
oraBlob.Erase(1024,64);
...
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
OracleBlob members are listed in the following tables:
OracleBlob constructors are listed in Table 5-156.
Table 5-156 OracleBlob Constructors
| Constructor | Description |
|---|---|
| OracleBlob Constructors |
Creates an instance of the OracleBlob class (Overloaded) |
OracleBlob static fields are listed in Table 5-157.
Table 5-157 OracleBlob Static Fields
| Field | Description |
|---|---|
| MaxSize |
Holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes |
OracleBlob static methods are listed in Table 5-158.
OracleBlob instance properties are listed in Table 5-159.
Table 5-159 OracleBlob Instance Properties
| Properties | Description |
|---|---|
| CanRead |
Indicates whether the LOB stream can be read |
| CanSeek |
Indicates whether forward and backward seek operations be performed |
| CanWrite |
Indicates whether the LOB object supports writing |
| Connection |
Indicates the OracleConnection that is used to retrieve and write BLOB data |
| IsEmpty |
Indicates whether the BLOB is empty or not |
| IsInChunkWriteMode |
Indicates whether the BLOB has been opened to defer index updates |
| IsTemporary |
Indicates whether or not the current instance is bound to a temporary BLOB |
| Length |
Indicates the size of the BLOB data |
| OptimumChunkSize |
Indicates the minimum number of bytes to retrieve or send from the server during a read or write operation |
| Position |
Indicates the current read or write position in the LOB stream |
| Value |
Returns the data, starting from the first byte in BLOB, as a byte array |
OracleBlob instance methods are listed in Table 5-160.
Table 5-160 OracleBlob Instance Methods
| Methods | Description |
|---|---|
| Append |
Appends the supplied data to the current OracleBlob instance (Overloaded) |
| BeginChunkWrite |
Opens the BLOB |
BeginRead |
Inherited from Stream |
BeginWrite |
Inherited from Stream |
| Clone |
Creates a copy of an OracleBlob object |
| Close |
Closes the current stream and releases any resources associated with it |
| Compare |
Compares data referenced by the current instance and that of the supplied object |
| CopyTo |
Copies from the current OracleBlob instance to an OracleBlob object (Overloaded) |
CreateObjRef |
Inherited from MarshalByRefObject |
| Dispose |
Releases resources allocated by this object |
| EndChunkWrite |
Closes the BLOB referenced by the current OracleBlob instance |
EndRead |
Inherited from Stream |
EndWrite |
Inherited from Stream |
Equals |
Inherited from Object (Overloaded) |
| Erase |
Erases data (Overloaded) |
Flush |
Not supported |
GetHashCode |
Inherited from Object |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializedLifetimeService |
Inherited from MarshalByRefObject |
| IsEqual |
Compares the LOB data referenced by the two OracleBlobs |
| Read |
Reads a specified amount of bytes from the ODP.NET LOB Type instance and populates the buffer |
ReadByte |
Inherited from Stream |
| Search |
Searches for a binary pattern in the current instance of an OracleBlob |
| Seek |
Sets the position in the current LOB stream |
| SetLength |
Trims or truncates the BLOB value to the specified length |
ToString |
Inherited from Object |
| Write |
Writes the supplied buffer into the OracleBlob |
WriteByte |
Inherited from Stream |
OracleBlob constructors are listed in Table 5-156.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object.
OracleBlob(OracleConnection, bool)
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object.
// C# public OracleBlob(OracleConnection con);
con
The OracleConnection object.
InvalidOperationException - The OracleConnection is not opened.
The connection must be opened explicitly by the application. OracleBlob does not open the connection implicitly.
The temporary BLOB utilizes the provided connection to store BLOB data. Caching is not turned on by this constructor.
This constructor creates an instance of the OracleBlob class bound to a temporary BLOB with an OracleConnection object and a boolean value for caching.
// C# public OracleBlob(OracleConnection con, bool bCaching);
con
The OracleConnection object.
bCaching
A flag for enabling or disabling server-side caching.
InvalidOperationException - The OracleConnection is not opened.
The connection must be opened explicitly by the application. OracleBlob does not open the connection implicitly.
The temporary BLOB uses the provided connection to store BLOB data. The bCaching input parameter determines whether or not server-side caching is used.
OracleBlob static fields are listed in Table 5-161.
Table 5-161 OracleBlob Static Fields
| Field | Description |
|---|---|
| MaxSize |
Holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes |
The MaxSize field holds the maximum number of bytes a BLOB can hold, which is 4,294,967,295 (2^32 - 1) bytes.
// C# public static readonly Int64 MaxSize = 4294967295;
This field can be useful in code that checks whether the operation exceeds the maximum length allowed.
OracleBlob static methods are listed in Table 5-162.
OracleBlob instance properties are listed in Table 5-163.
Table 5-163 OracleBlob Instance Properties
| Properties | Description |
|---|---|
| CanRead |
Indicates whether the LOB stream can be read |
| CanSeek |
Indicates whether forward and backward seek operations be performed |
| CanWrite |
Indicates whether the LOB object supports writing |
| Connection |
Indicates the OracleConnection that is used to retrieve and write BLOB data |
| IsEmpty |
Indicates whether the BLOB is empty or not |
| IsInChunkWriteMode |
Indicates whether the BLOB has been opened to defer index updates |
| IsTemporary |
Indicates whether or not the current instance is bound to a temporary BLOB |
| Length |
Indicates the size of the BLOB data |
| OptimumChunkSize |
Indicates the minimum number of bytes to retrieve or send from the server during a read or write operation |
| Position |
Indicates the current read or write position in the LOB stream |
| Value |
Returns the data, starting from the first byte in BLOB, as a byte array |
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 BLOB data.
// C#
public OracleConnection Connection {get;}
An object of OracleConnection.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the BLOB is empty or not.
// C#
public bool IsEmpty {get;}
A bool that indicates whether the BLOB is empty.
ObjectDisposedException - The object is already disposed.
This instance property indicates whether the BLOB has been opened to defer index updates.
// C#
public bool IsInChunkWriteMode{get;}
If the BLOB has been opened, returns true; otherwise, returns false.
This instance property indicates whether or not the current instance is bound to a temporary BLOB.
// C#
public bool IsTemporary {get;}
bool
Overrides Stream
This instance property indicates the size of the BLOB data in bytes.
// C#
public override Int64 Length {get;}
A number indicating the size of the BLOB data 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.
// 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 byte in the BLOB, as a byte array.
// C#
public Byte[] Value{get;}
A byte array.
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 not used or changed by using this property. 2 GB is the maximum byte array length that can be returned by this property.
OracleBlob instance methods are listed in Table 5-164.
Table 5-164 OracleBlob Instance Methods
| Methods | Description |
|---|---|
| Append |
Appends the supplied data to the current OracleBlob instance (Overloaded) |
| BeginChunkWrite |
Opens the BLOB |
BeginRead |
Inherited from Stream |
BeginWrite |
Inherited from Stream |
| Clone |
Creates a copy of an OracleBlob object |
| Close |
Closes the current stream and releases any resources associated with it |
| Compare |
Compares data referenced by the current instance and that of the supplied object |
| CopyTo |
Copies from the current OracleBlob instance to an OracleBlob object (Overloaded) |
CreateObjRef |
Inherited from MarshalByRefObject |
| Dispose |
Releases resources allocated by this object |
| EndChunkWrite |
Closes the BLOB referenced by the current OracleBlob instance |
EndRead |
Inherited from Stream |
EndWrite |
Inherited from Stream |
Equals |
Inherited from Object (Overloaded) |
| Erase |
Erases data (Overloaded) |
Flush |
Not supported |
GetHashCode |
Inherited from Object |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializedLifetimeService |
Inherited from MarshalByRefObject |
| IsEqual |
Compares the LOB data referenced by the two OracleBlobs |
| Read |
Reads a specified amount of bytes from the ODP.NET LOB Type instance and populates the buffer |
ReadByte |
Inherited from Stream |
| Search |
Searches for a binary pattern in the current instance of an OracleBlob |
| Seek |
Sets the position in the current LOB stream |
| SetLength |
Trims or truncates the BLOB value to the specified length |
ToString |
Inherited from Object |
| Write |
Writes the supplied buffer into the OracleBlob |
WriteByte |
Inherited from Stream |
Append
Append appends the supplied data to the end of the current OracleBlob instance.
This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance.
This instance method appends data from the supplied byte array buffer to the end of the current OracleBlob instance.
This instance method appends the BLOB data referenced by the provided OracleBlob object to the current OracleBlob instance.
// C# public void Append(OracleBlob obj);
obj
An object of OracleBlob.
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 from the supplied byte array buffer to the end of the current OracleBlob instance.
// C# public void Append(byte[] buffer, int offset, int count);
buffer
An array of bytes.
offset
The zero-based byte offset in the buffer from which data is read.
count
The number of bytes to be appended.
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 bytes {4,5} to the oraBlob
oraBlob.Append(new byte[3] {4,5,6}, 1, 2);
...
This instance method opens the BLOB.
// 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 BLOB data. This is provided for performance reasons.
After this method is called, write operations do not cause the domain or function-based index on the column to be updated. Index updates occur only once after EndChunkWrite is called.
This instance method creates a copy of an OracleBlob object.
// C# public object Clone();
An OracleBlob 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 OracleBlob oraBlob_cloned = (OracleBlob) oraBlob.Clone(); ...
Overrides Stream
This instance method closes the current stream and releases any resources associated with it.
// C# public override void Close();
This instance method compares data referenced by the current instance and that of the supplied object.
// C# public int Compare(Int64 src_offset, OracleBlob obj, Int64 dst_offset, Int64 amount);
src_offset
The comparison starting point (in bytes) for the current instance.
obj
The provided OracleBlob object.
dst_offset
The comparison starting point (in bytes) for the provided OracleBlob.
amount
The number of bytes to compare.
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
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.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
CopyTo
CopyTo copies data from the current instance to the provided OracleBlob object.
This instance method copies data from the current instance to the provided OracleBlob object.
This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified destination offset.
CopyTo(Int64, OracleBlob, Int64, Int64)
This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts.
This instance method copies data from the current instance to the provided OracleBlob object.
// C# public Int64 CopyTo(OracleBlob obj);
obj
The OracleBlob object to which the data is copied.
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:
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.
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 OracleBlob instance to the provided OracleBlob object with the specified destination offset.
// C# public Int64 CopyTo(OracleBlob obj, Int64 dst_offset);
obj
The OracleBlob object to which the data is copied.
dst_offset
The offset (in bytes) at which the OracleBlob 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:
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.
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.
This instance method copies data from the current OracleBlob instance to the provided OracleBlob object with the specified source offset, destination offset, and character amounts.
// C# public Int64 CopyTo(Int64 src_offset,OracleBlob obj,Int64 dst_offset,Int64 amount);
src_offset
The offset (in bytes) in the current instance, from which the data is read.
obj
The OracleBlob object to which the data is copied.
dst_offset
The offset (in bytes) at which the OracleBlob object is copied.
amount
The amount of data to be copied.
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 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.
// C# ... // Assume you have 2 valid blobs OracleBlob src_blob = new OracleBlob(con); OracleBlob target_blob = new OracleBlob(con); // Copy 1024 bytes from src_blob (begin at offset 10) to target_blob // (starting at offset 5) src_blob.CopyTo(10, target_blob, 5, 1024); ...
This instance method releases resources allocated by this object.
// C# public void Dispose();
IDisposable
Once Dispose() is called, the object of OracleBlob is in an uninitialized state.
Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls may lead to exceptions. The object cannot be reused after being disposed.
This instance method closes the BLOB referenced by the current OracleBlob 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 there is write operation(s) deferred by the BeginChunkWrite method.
Erase
Erase erases a portion or all data.
This instance method erases all data.
This instance method erases a specified portion of data.
This instance method erases all data.
// C# public Int64 Erase();
The number of bytes erased.
Erase() replaces all data with zero-byte fillers.
This instance method erases a specified portion of data.
// C# public Int64 Erase(Int64 offset, Int64 amount);
offset
The offset from which to erase.
amount
The quantity (in bytes) to erase.
The number of bytes 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.
Replaces the specified amount of data with zero-byte fillers.
This instance method compares the LOB data referenced by the two OracleBlobs.
// C# public bool IsEqual(OracleBlob obj);
obj
An OracleBlob object.
If the current OracleBlob and the provided OracleBlob refer to the same LOB, returns true. Returns false otherwise.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Note that this method can return true even if the two OracleBlob objects return false for == or Equals() because two different OracleBlob instances can refer to the same LOB.
The provided object and the current instance must be using the same connection, that is, the same OracleConnection object.
Overrides Stream
This instance method reads a specified amount of bytes from the ODP.NET LOB instance and populates the buffer.
// C# public override int Read(byte[ ] buffer, int offset, int count);
buffer
The byte array buffer to be populated.
offset
The starting offset (in bytes) at which the buffer is populated.
count
The amount of bytes to read.
The return value indicates the number of bytes read from the LOB.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - This exception is thrown if any of the following conditions exist:
The offset or the count parameter is less than 0.
The offset is greater than or equal to the buffer.Length.
The offset and the count together are greater than the buffer.Length.
The LOB data is read starting from the position specified by the Position property.
// C# ... byte buffer = new byte[1024]; int bufferOffset = 10; int amountToBeRead = 10; // Read some data ... int byteRead = oraBlob.Read(buffer, bufferOffset, amountToBeRead); ...
This instance method searches for a binary pattern in the current instance of an OracleBlob.
// C# public Int64 Search(byte[] val, int64 offset, int64 nth);
val
The binary pattern being searched for.
offset
The 0-based offset (in bytes) starting from which the OracleBlob is searched.
nth
The specific occurrence (1-based) of the match for which the absolute offset (in bytes) is returned.
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:
The offset is less than 0.
The nth is less than or equal to 0.
The val.Length is greater than 16383.
The nth is greater than or equal to OracleBlob.MaxSize.
The offset is greater than or equal to OracleBlob.MaxSize.
The limit of the search pattern is 16383 bytes.
// C#
...
// Search for the 2nd occurrence of a byte pattern '123'
// from the oraBlob starting at offset 1
byte[] pattern = new byte[3] { 1,2,3 };
int positionFound = oraBlob.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 Int64 for 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 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.
Overrides Stream
This instance method trims or truncates the BLOB value to the specified length (in bytes).
// C# public override void SetLength(Int64 newlen);
newlen
The desired length of the current stream in bytes.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentOutOfRangeException - The newlen parameter is less than 0.
Overrides Stream
This instance method writes the supplied buffer into the OracleBlob.
// C# public override void Write(byte[ ] buffer, int offset, int count);
buffer
The byte array buffer that provides the data.
offset
The 0-based offset (in bytes) from which the buffer is read.
count
The amount of data (in bytes) that is to be written into the OracleBlob.
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.
Destination offset in the OracleBlob can be specified by the Position property.
// C#
...
// Begin ChunkWrite to improve performance
// Index updates occur only once after EndChunkWrite
oraBlob.BeginChunkWrite();
// Set the write from the beginning;
oraBlob.Position = 0;
// Write to the oraBlob in chunks of 10, each 1024 bytes
for ( int i=0; i<10; i++ )
{
byte[1024] b;
b = b[0]; // some new value to be written
oraBlob.Write(b, 0, b.Length);
}
oraBlob.EndChunkWrite();
...
An OracleClob is an object that has a reference to CLOB data. It provides methods for performing operations on CLOBs.
|
Note: TheOracleClob object uses the client side character set when retrieving or writing CLOB data using a .NET Framework byte array. |
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.
Table 5-165 OracleClob Constructors
| Constructor | Description |
|---|---|
| OracleClob Constructors |
Creates an instance of the OracleClob class bound to a temporary CLOB (Overloaded) |
OracleClob static fields are listed in Table 5-166.
Table 5-166 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 are listed in Table 5-167.
OracleClob instance properties are listed in Table 5-168.
Table 5-168 OracleClob Instance Properties
| Properties | Description |
|---|---|
| CanRead |
Indicates whether the LOB stream can be read |
| CanSeek |
Indicates whether forward and backward seek operations can be performed |
| CanWrite |
Indicates whether 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 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 server 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 |
The OracleClob instance methods are listed in Table 5-169.
Table 5-169 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 OracleClobs |
| 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.
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.
// C# public OracleClob(OracleConnection con);
con
The OracleConnection object.
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.
Table 5-170 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.
// 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.
OracleClob instance properties are listed in Table 5-172.
Table 5-172 OracleClob Instance Properties
| Properties | Description |
|---|---|
| CanRead |
Indicates whether the LOB stream can be read |
| CanSeek |
Indicates whether forward and backward seek operations can be performed |
| CanWrite |
Indicates whether 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 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 server 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 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.
Table 5-173 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 OracleClobs |
| 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 |
Append
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);
obj
An OracleClob object.
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:
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.
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
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.
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.
// C# public Int64 CopyTo(OracleClob obj);
obj
The OracleClob object to which the data is copied.
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:
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.
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:
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.
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
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);
offset
The offset.
amount
The amount of data.
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);
obj
An OracleClob object.
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
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:
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.
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
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:
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.
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:
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.
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);
newlen
The desired length of the current stream in characters.
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.
Write
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:
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.
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:
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.
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();
...
An OracleRefCursor object represents an Oracle REF CURSOR.
Object
MarshalRefByObject
OracleRefCursor
// C# public sealed class OracleRefCursor : MarshalRefByObject, IDisposable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
// C#
// Example demonstrates how to use a REF CURSOR as an output parameter
...
// 1. Assume you have a stored procedure called MyPack.MyProc created with
// the following function, which returns 1 REF CURSOR and contains one REF
// CURSOR as an output parameter
// FUNCTION MyProc (...)
// BEGIN
// open p_cursor for select * from multimedia_tab;
// open p_cursor1 for select * from emp;
// return (p_cursor);
// END MyProc;
// ...
//
// 2. Assume you have a valid connection
// Set the command
OracleCommand cmd = new OracleCommand("MyPack.MyProc", con);
cmd.CommandType = CommandType.StoredProcedure;
// Bind
// select * from multimedia_tab;
OracleParameter p1 = cmd.Parameters.Add("refcursor1", OracleDbType.RefCursor);
p1.Direction = ParameterDirection.ReturnValue;
// select * from emp
OracleParameter p2 = cmd.Parameters.Add("refcursor2", OracleDbType.RefCursor);
p2.Direction = ParameterDirection.Output;
// Execute command
cmd.ExecuteNonQuery();
...
DataReader reader = p1.Value.GetDataReader();
Console.WriteLine("Field count: " + reader.FieldCount);
...
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
OracleRefCursor members are listed in the following tables:
OracleRefCursor static methods are listed in Table 5-174.
Table 5-174 OracleRefCursor Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
OracleRefCursor properties are listed in Table 5-175.
Table 5-175 OracleRefCursor Properties
| Properties | Description |
|---|---|
| Connection |
A reference to the OracleConnection used to fetch the REF CURSOR data |
OracleRefCursor instance methods are listed in Table 5-176.
Table 5-176 OracleRefCursor Instance Methods
| Methods | Description |
|---|---|
| Dispose |
Disposes the resources allocated by the OracleRefCursor object |
Equals |
Inherited from Object (Overloaded) |
| GetDataReader |
Returns an OracleDataReader object for the REF CURSOR |
GetHashCode |
Inherited from Object |
GetType |
Inherited from Object |
ToString |
Inherited from Object |
OracleRefCursor static methods are listed in Table 5-177.
Table 5-177 OracleRefCursor Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
OracleRefCursor properties are listed in Table 5-178.
Table 5-178 OracleRefCursor Properties
| Properties | Description |
|---|---|
| Connection |
A reference to the OracleConnection used to fetch the REF CURSOR data |
This property refers to the OracleConnection used to fetch the REF CURSOR data.
// C#
public OracleConnection Connection {get;}
An OracleConnection.
ObjectDisposedException - The object is already disposed.
This property is bound to a REF CURSOR once it is set. After the OracleRefCursor object is created by the constructor, this property is initially null. An OracleRefCursor object can be bound to a REF CURSOR after a command execution.
If the connection is closed or returned to the connection pool, the OracleRefCursor is placed in an uninitialized state and no operation can be carried out from it. However, the uninitialized OracleRefCursor can be reassigned to another REF CURSOR.
OracleRefCursor instance methods are listed in Table 5-179.
Table 5-179 OracleRefCursor Instance Methods
| Methods | Description |
|---|---|
| Dispose |
Disposes the resources allocated by the OracleRefCursor object |
Equals |
Inherited from Object (Overloaded) |
| GetDataReader |
Returns an OracleDataReader object for the REF CURSOR |
GetHashCode |
Inherited from Object |
GetType |
Inherited from Object |
ToString |
Inherited from Object |
This instance method disposes of the resources allocated by the OracleRefCursor object.
// C# public void Dispose();
IDisposable
The object cannot be reused after being disposed.
Once Dispose() is called, the object of OracleRefCursor is in an uninitialized state. Although some properties can still be accessed, their values may not be accountable. Since resources are freed, method calls can lead to exceptions.
This instance method returns an OracleDataReader object for the REF CURSOR.
// C# public OracleDataReader GetDataReader();
OracleDataReader
Using the OracleDataReader, rows can be fetched from the REF CURSOR.
An OracleXmlStream object represents a read-only stream of XML data stored in an OracleXmlType object.
Object
MarshalByRefObject
Stream
OracleXmlStream
// C# public sealed class OracleXmlStream : IDisposable, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
This class can only be used with Oracle9i Release 2 (9.2) and later.
OracleXmlStream members are listed in the following tables:
The OracleXmlStream constructors are listed in Table 5-180.
Table 5-180 OracleXmlStream Constructors
| Constructor | Description |
|---|---|
| OracleXmlStream Constructor | Creates an instance of an OracleXmlStream object which provides a Stream representation of the XML data stored in an OracleXmlType |
The OracleXmlStream static methods are listed in Table 5-181.
Table 5-181 OracleXmlStream Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
The OracleXmlStream instance properties are listed in Table 5-182.
Table 5-182 OracleXmlStream Instance Properties
| Properties | Description |
|---|---|
| CanRead | Indicates whether the XML stream can be read |
| CanSeek | Indicates whether forward and backward seek operation can be performed |
| CanWrite | Not Supported |
| Connection | Indicates the OracleConnection that is used to retrieve the XML data |
| Length | Indicates the number of bytes in the XML stream |
| Position | Gets or sets the byte position within the stream |
| Value | Returns the XML data, starting from the first character in the stream as a string |
The OracleXmlStream instance methods are listed in Table 5-183.
Table 5-183 OracleXmlStream instance Methods
| Methods | Description |
|---|---|
BeginRead |
Inherited from Stream |
BeginWrite |
Inherited from Stream |
| Clone | Creates a copy of an OracleXmlStream object |
| Close | Closes the current stream and releases any resources associated with it |
| Dispose | Releases resources allocated by this object |
EndRead |
Inherited from Stream |
EndWrite |
Inherited from Stream |
Equals |
Inherited from Object |
Flush |
Not Supported |
GetHashCode |
Inherited from Object |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializeLifetimeService |
Inherited from MarshalByRefObject |
| Read | Reads a specified amount from the current stream instance and populates the array buffer (Overloaded) |
ReadByte |
Inherited from Stream |
| Seek | Sets the position within the current stream and returns the new position within the current stream |
SetLength |
Not Supported |
ToString |
Inherited from Object |
Write |
Not Supported |
WriteByte |
Not Supported |
This constructor creates an instance of an OracleXmlStream object which provides a Stream representation of the XML data stored in an OracleXmlType object.
// C# public OracleXmlStream(OracleXmlType xmlType);
xmlType
The OracleXmlType object.
The OracleXmlStream implicitly uses the OracleConnection object from the OracleXmlType object from which it was constructed.
The OracleXmlStream static methods are listed in Table 5-184.
Table 5-184 OracleXmlStream Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
The OracleXmlStream instance properties are listed in Table 5-185.
Table 5-185 OracleXmlStream Instance Properties
| Properties | Description |
|---|---|
| CanRead | Indicates whether the XML stream can be read |
| CanSeek | Indicates whether forward and backward seek operation can be performed |
CanWrite |
Not Supported |
| Connection | Indicates the OracleConnection that is used to retrieve the XML data |
| Length | Indicates the number of bytes in the XML stream |
| Position | Gets or sets the byte position within the stream |
| Value | Returns the XML data, starting from the first character in the stream as a string |
Overrides Stream
This property indicates whether the XML stream can be read.
// C#
public override bool CanRead{get;}
If the XML stream is can be read, returns true; otherwise, returns false.
Overrides Stream
This property indicates whether forward and backward seek operation can be performed.
// C#
public override bool CanSeek{get;}
If forward and backward seek operations can be performed, this property returns true. Otherwise, returns false.
This instance property indicates the OracleConnection that is used to retrieve the XML data.
// C#
public OracleConnection Connection {get;}
An OracleConnection.
ObjectDisposedException - The object is already disposed.
Overrides Stream
This property indicates the number of bytes in the XML stream.
// C#
public override Int64 Length{get;}
An Int64 value representing the number of bytes in the XML stream. An empty stream has a length of 0 bytes.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Overrides Stream
This property gets or sets the byte position within the stream.
// C#
public override Int64 Position{get; set;}
An Int64 that indicates the current position in the stream.
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.
The beginning of the stream is represented by position 0. Seeking to any location beyond the length of the stream is supported.
This property returns the XML data, starting from the first character of the stream as a string.
// C#
public string Value{get; set;}
A string.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The value of Position is neither used nor changed by using this property.
The maximum length of the string that can be returned by this property is 2 GB.
The OracleXmlStream instance methods are listed in Table 5-186.
Table 5-186 OracleXmlStream Instance Methods
| Methods | Description |
|---|---|
BeginRead |
Inherited from Stream |
BeginWrite |
Inherited from Stream |
| Clone | Creates a copy of an OracleXmlStream object |
| Close | Closes the current stream and releases any resources associated with it |
| Dispose | Releases resources allocated by this object |
EndRead |
Inherited from Stream |
EndWrite |
Inherited from Stream |
Equals |
Inherited from Object |
Flush |
Not Supported |
GetHashCode |
Inherited from Object |
GetLifetimeService |
Inherited from MarshalByRefObject |
GetType |
Inherited from Object |
InitializeLifetimeService |
Inherited from MarshalByRefObject |
| Read | Reads a specified amount from the current XML stream instance and populates the array buffer (Overloaded) |
ReadByte |
Inherited from Stream |
| Seek | Sets the position within the current stream and returns the new position within the current stream |
SetLength |
Not Supported |
ToString |
Inherited from Object |
Write |
Not Supported |
WriteByte |
Not Supported |
This method creates a copy of an OracleXmlStream object.
// C# public object Clone();
An OracleXmlStream 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 OracleXmlStream oraXmlStream_cloned = (OracleXmlStream) oraXmlStream.Clone(); ...
Overrides Stream
This method closes the current stream and releases any resources associated with it.
// C# public override void Close();
This public method releases resources allocated by this object.
// C# 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.
Read
This method reads a specified amount from the current XML stream instance and populates the array buffer.
This method reads a specified amount of unicode bytes from the current instance, advances the position within the stream, and populates the byte array buffer.
This method reads a specified amount of characters from the current instance, advances the position within the stream, and populates the character array buffer.
Overrides Stream
This method reads a specified amount of unicode bytes from the current instance, advances the position within the stream, 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 zero-based offset (in bytes) at which the buffer is populated.
count
The maximum amount of bytes to be read.
The number of unicode bytes read into the given byte[] buffer or 0 if the end of the stream has been reached.
This method reads a maximum of count bytes from the current stream and stores them in buffer beginning at offset. The current position within the stream is advanced by the number of bytes read. However, if an exception occurs, the current position within the stream remains unchanged.
The XML data is read starting from the position specified by the Position property.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Overrides Stream
This method reads a specified amount of characters from the current instance, advances the position within the stream, and populates the character array buffer.
// C# public override int Read(char[ ] buffer, int offset, int count);
buffer
The character array buffer to be populated.
offset
The zero-based offset (in characters) in the buffer at which the buffer is populated.
count
The maximum amount of characters to be read from the stream.
The return value indicates the number of characters read from the stream or 0 if the end of the stream has been reached.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This method requires that the Position on the stream instance be zero or an even number.
The XML data is read starting from the position specified by the Position property.
Overrides Stream.
This method sets the position within the current stream and returns the new position within the current stream.
// C# public long Seek(long offset, SeekOrigin origin);
offset
A byte offset relative to origin.
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.
origin
A value of type SeekOrigin indicating the reference point used to obtain the new position.
The new Position within the current stream.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object
Use the CanSeek property to determine whether the current instance supports seeking. Seeking to any location beyond the length of the stream is supported.
An OracleXmlType object represents an Oracle XMLType instance.
Class Inheritance
Object
OracleXmlType
// C# public sealed class OracleXmlType : IDisposable, ICloneable
All public static methods are thread-safe, although instance methods do not guarantee thread safety.
OracleXmlType objects can be used for well-formed XML documents with or without XML schemas or XML fragments.
Namespace: Oracle.DataAccess.Types
Assembly: Oracle.DataAccess.dll
This class can only be used with Oracle9i Release 2 (9.2) or higher.
OracleXmlType members are listed in the following tables:
The OracleXmlType constructors are listed in Table 5-187.
Table 5-187 OracleXmlType Constructors
| Constructor | Description |
|---|---|
| OracleXmlType Constructors | Creates an instance of the OracleXmlType class (Overloaded) |
The OracleXmlType static methods are listed in Table 5-188.
Table 5-188 OracleXmlType Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
The OracleXmlType instance properties are listed in Table 5-189.
Table 5-189 OracleXmlType Instance Properties
| Properties | Description |
|---|---|
| Connection | Indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType |
| IsEmpty | Indicates whether or not the OracleXmlType is empty |
| IsFragment | Indicates whether the XML data is a collection of XML elements or a well-formed XML document |
| IsSchemaBased | Indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema |
| RootElement |
Represents the name of the top-level element of the schema-based XML data contained in the OracleXmlType |
| Schema |
Represents the XML schema of the XML data contained in the OracleXmlType |
| SchemaUrl |
Represents URL in the database for the XML schema of the XML data contained in the OracleXmlType. |
The OracleXmlType instance methods are listed in Table 5-190.
Table 5-190 OracleXmlType Instance Methods
| Methods | Description |
|---|---|
| Clone | Creates a copy of the OracleXmlType instance |
| Dispose | Releases the resources allocated by this OracleXmlType object |
Equals |
Inherited from Object |
| Extract | Extracts a subset from the XML data using the given XPath expression (Overloaded) |
GetHashCode |
Inherited from Object |
| GetStream | Returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance |
GetType |
Inherited from Object |
| GetXmlDocument | Returns a XmlDocument object containing the XML data stored in this OracleXmlType instance |
| GetXmlReader | Returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods |
| IsExists | Checks for the existence of a particular set of nodes identified by the given XPath expression in the XMLdata (Overloaded) |
ToString |
Inherited from Object |
| Transform | Transforms the OracleXmlType into another OracleXmlType instance using the given XSL document (Overloaded) |
| Update | Updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance (Overloaded) |
| Validate |
Validates whether the XML data in the OracleXmlType object conforms to the given XML schema. |
OracleXmlType constructors create instances of the OracleXmlType class.
This constructor creates an instance of the OracleXmlType class using the XML data contained in an OracleClob object.
OracleXmlType(OracleConnection, string)
This constructor creates an instance of the OracleXmlType class using the XML data contained in the .NET String.
OracleXmlType(OracleConnection, XmlReader)
This constructor creates an instance of the OracleXmlType class using the contents of the .NET XmlReader object.
OracleXmlType(OracleConnection, XmlDocument)
This constructor creates an instance of the OracleXmlType object using the contents of the XML DOM document in the .NET XmlDocument object.
This constructor creates an instance of the OracleXmlType class using the XML data contained in an OracleClob object.
// C# public OracleXmlType(OracleClob oraClob);
oraClob
An OracleClob object.
ArgumentNullException - The OracleClob object is null.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The CLOB data depends on a valid connection object and the new OracleXMLType uses the OracleConnection in the OracleClob object to store data for the current instance.
This constructor creates an instance of the OracleXmlType class using the XML data contained in the .NET String.
// C# public OracleXmlType(OracleConnection con, string xmlData);
con
An OracleConnection object.
xmlData
A string containing the XML data.
ArgumentNullException - The OracleConnection object is null.
ArgumentException - The xmlData argument is an empty string.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The new OracleXmlType uses the given OracleConnection object to store data for the current instance.
This constructor creates an instance of the OracleXmlType class using the contents of the .NET XmlReader object.
// C# public OracleXmlType(OracleConnection con, XmlReader reader);
con
An OracleConnection object.
reader
An XmlReader object.
ArgumentNullException - The OracleConnection object is null.
ArgumentException - The reader argument contains no data.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The new OracleXMLType uses the given OracleConnection object to store data for the current instance.
This constructor creates an instance of the OracleXmlType object using the contents of the XML DOM document in the .NET XmlDocument object.
// C# public OracleXmlType(OracleConnection con, XmlDocument domDoc);
con
An OracleConnection object.
domDoc
An XML document.
ArgumentNullException - The OracleConnection object is null.
ArgumentException - The domDoc argument contains no data.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The new OracleXMLType uses the given OracleConnection object to store data for the current instance.
The OracleXmlType static methods are listed in Table 5-191.
Table 5-191 OracleXmlType Static Methods
| Methods | Description |
|---|---|
Equals |
Inherited from Object (Overloaded) |
The OracleXmlType instance properties are listed in Table 5-192.
Table 5-192 OracleXmlType Instance Properties
| Properties | Description |
|---|---|
| Connection | Indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType |
| IsEmpty | Indicates whether or not the OracleXmlType is empty |
| IsFragment | Indicates whether the XML data is a collection of XML elements or a well-formed XML document |
| IsSchemaBased | Indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema |
| RootElement |
Represents the name of the top-level element of the schema-based XML data contained in the OracleXmlType |
| Schema |
Represents the XML schema of the XML data contained in the OracleXmlType |
| SchemaUrl |
Represents URL in the database for the XML schema of the XML data contained in the OracleXmlType. |
This property indicates the OracleConnection that is used to retrieve and store XML data in the OracleXmlType.
// C#
public OracleConnection Connection {get;}
An OracleConnection object.
ObjectDisposedException - The object is already disposed.
The connection must explicitly be opened by the user before creating or using OracleXmlType.
This property indicates whether or not the OracleXmlType is empty.
// C#
public bool IsEmpty {get;}
Returns true if the OracleXmlType represents an empty XML document. Returns false otherwise.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This property indicates whether the XML data is a collection of XML elements or a well-formed XML document.
// C#
public bool IsFragment {get;}
Returns true if the XML data contained in the OracleXmlType object is a collection of XML elements with no root element. Returns false otherwise.
ObjectDisposedException - The object is already disposed.
This property indicates whether or not the XML data represented by the OracleXmlType is based on an XML schema.
// C#
public bool IsSchemaBased {get;}
Returns true if the XML data represented by the OracleXmlType is based on an XML schema. Returns false otherwise.
ObjectDisposedException - The object is already disposed.
This property represents the name of the top-level or root element of the schema-based XML data contained in the OracleXmlType.
// C#
public string RootElement{get;}
A string that represents the name of the top-level or root element of the XML data contained in the OracleXmlType.
ObjectDisposedException - The object is already disposed.
If the OracleXmlType instance contains non-schema based XML data, this property returns an empty string.
This property represents the XML schema for the XML data contained in the OracleXmlType.
// C#public OracleXmlType Schema {get;}
An OracleXmlType instance that represents the XML schema for the XML data contained in the OracleXmlType.
ObjectDisposedException - The object is already disposed.
If the OracleXmlType instance contains non-schema based XML data, this property returns an OracleXmlType instance representing an empty XML document.
This property represents the URL in the database for the XML schema of the XML data contained in the OracleXmlType.
// C#
public string SchemaUrl {get;}
A string that represents the URL in the database for the XML schema of the XML data.
ObjectDisposedException - The object is already disposed.
If the OracleXmlType instance contains non-schema based XML data, this property returns an empty string.
This property returns the XML data starting from the first character in the current instance as a string.
// C#
public string RootElement{get;}
The entire XML data as a string.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The OracleXmlType instance methods are listed in Table 5-193.
Table 5-193 OracleXmlType Instance Methods
| Methods | Description |
|---|---|
| Clone | Creates a copy of the OracleXmlType instance |
| Dispose | Releases the resources allocated by this OracleXmlType object |
Equals |
Inherited from Object |
| Extract | Extracts a subset from the XML data using the given XPath expression (Overloaded) |
GetHashCode |
Inherited from Object |
| GetStream | Returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance |
GetType |
Inherited from Object |
| GetXmlDocument | Returns a XmlDocument object containing the XML data stored in this OracleXmlType instance |
| GetXmlReader | Returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods |
| IsExists | Checks for the existence of a particular set of nodes identified by the given XPath expression in the XMLdata (Overloaded) |
ToString |
Inherited from Object |
| Transform | Transforms the OracleXmlType into another OracleXmlType instance using the given XSL document (Overloaded) |
| Update | Updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance (Overloaded) |
| Validate |
Validates whether the XML data in the OracleXmlType object conforms to the given XML schema. |
This method creates a copy of this OracleXmlType instance.
// C# public object Clone();
ICloneable
An OracleXmlType object.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This method releases the resources allocated by this object.
// C# public void Dispose();
IDisposable
Extract
This method extracts a subset from the XML data using the given XPath expression.
This method extracts a subset from the XML data represented by the OracleXmlType object using the given XPath expression and a string parameter for namespace resolution.
Extract(string, XmlNameSpaceManager)
This method extracts a subset from the XML data represented by the OracleXmlType object, using the given XPath expression and a .NET XmlNameSpaceManager object for namespace resolution.
This method extracts a subset from the XML data represented by the OracleXmlType object using the given XPath expression and a string parameter for namespace resolution.
// C# public OracleXmlType Extract(string xpathExpr, string nsMap);
xpathExpr
The XPath expression.
nsMap
The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. For example:
xmlns:nsi"=http://www.company1.com" xmlns:nsz="http://www.company2.com"
An OracleXmlType object.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This public method extracts a subset from the XML data represented by the OracleXmlType object, using the given XPath expression and a .NET XmlNameSpaceManager object for namespace resolution.
// C# public OracleXmlType Extract(string xpathExpr, XmlNameSpaceManager nsMgr);
xpathExpr
The XPath expression.
nsMgr
The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.
An OracleXmlType.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
This public method returns an instance of OracleXmlStream which provides a read-only stream of the XML data stored in this OracleXmlType instance.
// C# public Stream GetStream();
A Stream object.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This public method returns a XmlDocument object containing the XML data stored in this OracleXmlType instance.
// C# public XmlDocument GetXmlDocument();
An XmlDocument object.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The XML data in the XmlDocument object is a copy of the XML data in the OracleXmlType instance and modifying it does not automatically modify the XML data in the OracleXmlType instance. The XmlDocument instance returned has the PreserveWhitespace property set to true.
This public method returns a XmlTextReader object that can be used to manipulate XML data directly using the .NET Framework classes and methods.
// C# public XmlTextReader GetXmlReader();
An XmlTextReader object.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The XmlTextReader is a read-only, forward-only representation of the XML data stored in the OracleXmlType instance.
IsExists
IsExists checks for the existence of a particular set of nodes identified by the XPath expression in the XML data.
This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML data represented by the current OracleXmlType instance using a string parameter for namespace resolution.
IsExists(string, XmlNameSpaceManager)
This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML document represented by the current OracleXmlType instance using a .NET XmlNameSpaceManager object for namespace resolution.
This method checks for the existence of a particular set of nodes identified by the XPath expression in the XML data represented by the current OracleXmlType instance using a string parameter for namespace resolution.
// C# public bool IsExists(string xpathExpr, string nsMap);
xpathExpr
The XPath expression.
nsMap
The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null.
Returns true if the required set of nodes exists; otherwise, returns false.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
This method checks the existence of a particular set of nodes identified by the XPath expression in the XML document represented by the current OracleXmlType instance using a .NET XmlNameSpaceManager object for namespace resolution.
// C# public bool IsExists(string xpathExpr, XmlNameSpaceManager nsMgr);
xpathExpr
The XPath expression.
nsMgr
The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.
Returns true if the required set of nodes exists; otherwise, returns false.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
Transform
This method transforms the OracleXmlType into another OracleXmlType instance using the given XSL document.
Transform(OracleXmlType, string)
This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document (as an OracleXmlType object) and a string of XSLT parameters.
This public method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters.
This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters.
// C# public OracleXmlType Transform(OracleXmlType xsldoc, string paramMap);
xsldoc
The XSL document as an OracleXmlType object.
paramMap
A string which provides the parameters for the XSL document.
For this release, paramMap is ignored.
An OracleXmlType object containing the transformed XML document.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xsldoc parameter is null.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
This method transforms the current OracleXmlType instance into another OracleXmlType instance using the given XSL document and a string of XSLT parameters.
// C# public OracleXmlType Transform(string xsldoc, string paramMap);
xsldoc
The XSL document to be used for XSLT.
paramMap
A string which provides the parameters for the XSL document.
For this release, paramMap is ignored.
An OracleXmlType object containing the transformed XML document.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xsldoc parameter is null.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
Update
This method updates the XML node or fragment identified by the given XPath expression in the current OracleXmlType instance.
Update(string, string, string)
This method updates the XML nodes identified by the given XPath expression with the given string value and a string parameter for namespace resolution.
Update(string, XmlNameSpaceManager, string)
This method updates the XML nodes identified by the given XPath expression with the given string value and a .NET XmlNameSpaceManager object for namespace resolution.
Update(string, string, OracleXmlType)
This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a string parameter for namespace resolution.
Update(string, XmlNameSpaceManager, OracleXmlType)
This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a .NET XmlNameSpaceManager object for namespace resolution.
This method updates the XML nodes identified by the given XPath expression with the given string value and a string parameter for namespace resolution.
// C# public void Update(string xpathExpr, string nsMap, string value);
xpathExpr
The XPath expression that identifies the nodes to update.
nsMap
The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null. For example:
xmlns:nsi"=http://www.company1.com" xmlns:nsz="http://www.company2.com"
value
The new value as a string.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
This method updates the XML nodes identified by the given XPath expression with the given string value and a .NET XmlNameSpaceManager object for namespace resolution.
// C# public void Update(string xpathExpr, XmlNameSpaceManager nsMgr, string value);
xpathExpr
The XPath expression that identifies the nodes to update.
nsMgr
The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.
value
The new value as a string.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a string parameter for namespace resolution.
// C# public void Update(string xpathExpr, string nsMap, OracleXmlType value);
xpathExpr
The XPath expression that identifies the nodes to update.
nsMap
The string parameter used for namespace resolution of the XPath expression. nsMap has zero or more namespaces separated by spaces. nsMap can be null.
value
The new value as an OracleXmlType object.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
This method updates the XML nodes identified by the given XPath expression with the XML data stored in the given OracleXmlType value and a .NET XmlNameSpaceManager object for namespace resolution.
// C# public void Update(string xpathExpr, XmlNameSpaceManager nsMgr, OracleXmlType value);
xpathExpr
The XPath expression that identifies the nodes to update.
nsMgr
The .NET XmlNameSpaceManager object used for namespace resolution of the XPath expression. nsMgr can be null.
value
The new value as an OracleXmlType object.
ObjectDisposedException - The object is already disposed.
ArgumentNullException - The xpathExpr is null or zero-length.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
The default namespace is ignored if its value is an empty string.
This methods validates whether the XML data in the OracleXmlType object conforms to the given XML schema.
// C# public bool Validate(String schemaUrl);
schemaUrl
A string representing the URL in the database of the XML schema.
Returns true if the XML data conforms to the XML schema; otherwise, returns false.
ObjectDisposedException - The object is already disposed.
InvalidOperationException - The OracleConnection is not open or has been closed during the lifetime of the object.
ArgumentNullException - The schemaUrl argument is null or an empty string.
|
 Copyright © 2002, 2003 Oracle Corporation All Rights Reserved. |
|