OracleLob.Write(Byte[], Int32, Int32) Method

Definition

Namespace:

System.Data.OracleClient

Assembly:

System.Data.OracleClient.dll

Writes a sequence of bytes to the current OracleLob stream, and advances the current position within this stream by the number of bytes written.

public:
 override void Write(cli::array <System::Byte> ^ buffer, int offset, int count);

public override void Write (byte[] buffer, int offset, int count);

override this.Write : byte[] * int * int -> unit

Public Overrides Sub Write (buffer As Byte(), offset As Integer, count As Integer)

Parameters

buffer

Byte[]

An array of bytes. This method copies the number of bytes specified in count from buffer to the current stream.

offset

Int32

The zero-based byte offset in buffer at which to begin copying bytes to the current stream. For CLOB and NCLOB data types, this must be an even number.

count

Int32

The number of bytes to be written to the current stream. For CLOB and NCLOB data types, this must be an even number.

Exceptions

ArgumentNullException

The buffer parameter is a null reference (Nothing in Visual Basic).

ArgumentOutOfRangeException

A value in the offset or count parameter is not positive.

-or-

The sum of the offset and count parameters is larger than the buffer length.

-or-

A value specified in the count or offset parameter is less than zero or greater than 4 gigabytes.

-or-

You must specify CLOB and NCLOB data types as an even number of bytes.

InvalidOperationException

The operation is not within a transaction, the OracleLob object is null, or the connection is closed.

ObjectDisposedException

The object was closed or disposed.

OracleException

An Oracle error has occurred.

Remarks

If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged.

Writing beyond the end of LOB is allowed and enlarges the LOB by the number of bytes written.

The .NET Framework Data Provider for Oracle handles all CLOB and NCLOB data as Unicode. Therefore, when accessing CLOB and NCLOB data types, you are always dealing with the number of bytes, where each character is 2 bytes. For example, if a string of text containing three characters is saved as an NCLOB on an Oracle server where the character set is 4 bytes per character, and you perform a Write operation, you specify the length of the string as 6 bytes, although it is stored as 12 bytes on the server.

To write to the LOB, you must have retrieved the LOB using the FOR UPDATE clause in the SQL SELECT statement, and you must have a local transaction started.

The following example demonstrates how to write to OracleLob objects:

public static void WriteLobExample(OracleCommand command)  
{  
    // Note: Updating LOB data requires a transaction.  
    command.Transaction = command.Connection.BeginTransaction();  
    // Select some data.  
    //    Table Schema:  
    //        "CREATE TABLE tablewithlobs (a int, b BLOB, c BLOB)";  
    //        "INSERT INTO tablewithlobs values (1, 'AA', 'AAA')";  
    command.CommandText = "SELECT * FROM TableWithLobs FOR UPDATE";  
    OracleDataReader reader = command.ExecuteReader();  
    using(reader)  
    {  
        // Obtain the first row of data.  
        reader.Read();  
        // Obtain both LOBs.  
        OracleLob BLOB1 = reader.GetOracleLob(1);  
        OracleLob BLOB2 = reader.GetOracleLob(2);  
        // Perform any desired operations on the LOB, (read, position, and so on).  
        // ...  
        // Example - Writing binary data (directly to the backend).  
        // To write, you can use any of the stream classes, or write raw binary data using   
        // the OracleLob write method. Writing character vs. binary is the same;  
        // however note that character is always in terms of Unicode byte counts  
        // (for example: even number of bytes - 2 bytes for every Unicode character).  
        var buffer = new byte[100];  
        buffer[0] = 0xCC;  
        buffer[1] = 0xDD;  
        BLOB1.Write(buffer, 0, 2);  
        BLOB1.Position = 0;  
        Console.WriteLine(BLOB1.LobType + ".Write(" + buffer + ", 0, 2) => " + BLOB1.Value);  

        // Example - Copying data into another LOB.  
        long actual = BLOB1.CopyTo(BLOB2);  
        Console.WriteLine(BLOB1.LobType + ".CopyTo(" + BLOB2.Value + ") => " + actual);  

        // Commit the transaction now that everything succeeded.  
        // Note: On error, Transaction.Dispose is called (from the using statement)  
        // and will automatically roll-back the pending transaction.  
        command.Transaction.Commit();  
    }  
}  

Note

A write operation to a read-only LOB might succeed, but does not update the LOB on the server. In this case, however, the local copy of the LOB is updated. Therefore, later read operations on the OracleLob object might return the results of the write operation.