This documentation is archived and is not being maintained.

OracleLob.Write Method

Note: This namespace, class, or member is supported only in version 1.1 of the .NET Framework.

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

[Visual Basic]
Overrides Public Sub Write( _
   ByVal buffer() As Byte, _
   ByVal offset As Integer, _
   ByVal count As Integer _
)
[C#]
public override void Write(
 byte[] buffer,
 int offset,
 int count
);
[C++]
public: void Write(
 unsigned char buffer __gc[],
 int offset,
 int count
);
[JScript]
public override function Write(
   buffer : Byte[],
 offset : int,
 count : int
);

Parameters

buffer
An array of bytes. This method copies the number of bytes specfied in count from buffer to the current stream.
offset
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
The number of bytes to be written to the current stream. For CLOB and NCLOB data types, this must be an even number.

Exceptions

Exception Type Condition
ArgumentNullException The buffer parameter is a null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException A value in the offset or count parameterv 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 Writing to a LOB requires that the operation be within a transaction.

-or-

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 will enlarge 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.

The following C# example demonstrates how to write to OracleLob objects.

public static void WriteLobExample(OracleCommand cmd)
{
    //Note: Updating LOB data requires a transaction.
    cmd.Transaction = cmd.Connection.BeginTransaction();
        
    //Select some data.
    //    Table Schema:
    //        "CREATE TABLE tablewithlobs (a int, b BLOB, c CLOB, d NCLOB)";
    //        "INSERT INTO tablewithlobs values (1, 'AA', 'AAA', N'AAAA')";
    cmd.CommandText = "SELECT * FROM tablewithlobs FOR UPDATE";
    OracleDataReader reader = cmd.ExecuteReader();
    using(reader)
    {
        //Obtain the first row of data.
        reader.Read();
        //Obtain a LOB.
        OracleLob BLOB    = reader.GetOracleLob(1/*0:based ordinal*/);
        //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).
        byte[] buffer = new byte[100];
        buffer[0] = 0xCC;
        buffer[1] = 0xDD;
        BLOB.Write(buffer, 0/*buffer offset*/, 2/*count*/);
        BLOB.Position = 0;
        Console.WriteLine(BLOB.LobType + ".Write(" + buffer + ", 0, 2) => " + BLOB.Value);
            
        //Example - Obtaining a temp LOB and copying data into it from another LOB.
        OracleLob templob = CreateTempLob(cmd, BLOB.LobType);
        long actual = BLOB.CopyTo(templob);
        Console.WriteLine(BLOB.LobType + ".CopyTo(" + templob.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.
        cmd.Transaction.Commit();
    }
}
Note   In this release, a write operation to a read-only LOB might succeed, but will not update the LOB on the server. In this case, however, the local copy of the LOB will be updated. Therefore, subsequent read operations on the OracleLob object might return the results of the write operation.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

.NET Framework Security: 

See Also

OracleLob Class | OracleLob Members | System.Data.OracleClient Namespace

Show: