OCI8::CLOB

This is an I/O class to read/write character data to/from CLOB objects. You can insert a CLOB object to a column and get the column data by a select statement.

 con = OCI8.new('scott', 'tiger')
 # create a table.
 con.exec("CREATE TABLE novels (title VARCHAR2(30), contents CLOB)")
 # insert a CLOB object.
 con.exec("INSERT INTO novels(title, contents) values (:1, :2)",
          'a long tale', OCI8::CLOB.new(con, 'long long text ...'))
 # select a CLOB object.
 con.exec("select contents from novels where title = :1",
          'a long tale') do |row|
   # row[0] is a CLOB object.
   contents = row[0].read
 end

OCI8::CLOB.new(con, val)

(requires Oracle 8.1 or upper) (new in 1.0.0-rc2)

create a temporary lob. "temporary" means "which is not stored to a database." You can store your data to a temporary lob and insert it to a table.

available?

check whether the CLOB object is available or not.

 con.exec("CREATE TABLE novels (title VARCHAR2(30), contents CLOB)")
 con.exec("INSERT INTO novels VALUES ('null-data', NULL)")
 con.exec("INSERT INTO novels VALUES ('empty-data', EMPTY_CLOB())")
 con.exec("SELECT title, contents FROM novels") do |title, contents|
   case title
   when 'null-data'
     puts "#{title} => #{contents.available?.to_s}"
     # => false
   when 'empty-data'
     puts "#{title} => #{contents.available?.to_s}"
     # => true
   end
 end

read(size = nil)

get characters from the CLOB object. The number of characters is at most the specified size. If the size is nil, it read until the end of the CLOB.

note: the size is not counted by byte but by character. The returned value's number of bytes can be longer then the size if it contains multi-byte characters.

 # read CLOB data.
 con.exec("SELECT title, contents FROM novels") do |title, contents|
   File.open(title, 'w') do |f|
     f.write(contents.read)
   end
 end

write(string)

write the given string to CLOB. The return value is the number of written characters. If old data is longer than new data, resize by OCI8::CLOB#size.

 # write to CLOB.
 con.exec("SELECT title, contents FROM novels") do |title, clob|
   File.open(title, 'r') do |f|
     contents = f.read
     num_chars = clob.write(contents)
     clob.size = num_chars
   end
 end

note: OCI8::CLOB#size is counted by characters. If the contents contain multibyte characters, the following code set incorrect clob size.

 # bad example
 con.exec("SELECT title, contents FROM novels") do |title, clob|
   File.open(title, 'r') do |f|
     contents = f.read
     clob.write(contents)
     clob.size = contents.length # boo!
   end
 end

size

return the number of characters in the CLOB.

size=(len)

set the number of characters in the CLOB.

pos

return the current offset of the CLOB in characters.

pos = number

set the current offset of the CLOB in characters.

eof?

true if the current offset is at the end of the CLOB.

chunk_size

return the chunk size of CLOB.

truncate(len)

synonym for size=.

tell

synonym for pos.

seek(pos)

synonym for pos=.

rewind

set the current offset to zero.