RubyGems - ruby-oci8 - Versions diffs - 2.0.4-x86-mingw32 - Mend

ruby-oci8 2.0.4-x86-mingw32

Files changed (52) hide show

@@ -0,0 +1,527 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html
+  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Ruby/OCI8 High-level API</title>
+<link href="manual.css" type="text/css" rel="stylesheet" />
+</head>
+<body>
+<h1><a name="label-0" id="label-0">Ruby/OCI8 High-level API</a></h1><!-- RDLabel: "Ruby/OCI8 High-level API" -->
+<p>[ <a href="index.en.html">Home</a> ] [ English | <a href="api.ja.html">Japanese</a> ]</p>
+<p>Ruby/OCI8 is divided to two layer APIs. One is "Low-level
+API". The other is "High-level API". This document describes how to
+use the latter, but some of the former will be described as long as it
+is necessary to use the latter.</p>
+<p>"High-level API" is the library written by ruby, which based on
+"Low-level API". This API hides complicated structure of OCI and make
+it easy to issue SQL statements as possible. Please use this for general purpose.</p>
+<p>"Low-level API" is the library written by C language. OCI <a name="footmark-1" id="footmark-1" href="#foottext-1"><sup><small>*1</small></sup></a> handles and OCI functions become ruby's classes
+and methods respectively. The handles and functions are converted by
+straight mapping rule as long as ruby's syntax allows. </p>
+<p>In the version 0.2 I will rewrite High-level API by C language directly.
+Low-level API will be obsolete.</p>
+<h2><a name="label-1" id="label-1">Contents</a></h2><!-- RDLabel: "Contents" -->
+<ul>
+<li><a href="#label-2">Classes List</a>
+<ul>
+<li><a href="#label-3">OCI8</a></li>
+<li><a href="#label-4">OCI8::Cursor</a></li>
+<li><a href="#label-5">OCI8::BLOB</a></li>
+<li><a href="#label-6">OCI Exception Classes</a></li>
+</ul></li>
+<li><a href="#label-7">Methods List</a>
+<ul>
+<li>OCI8
+<ul>
+<li><a href="#label-9">new</a>(userid, password, dbname = nil, privilege = nil)</li>
+<li><a href="#label-10">logoff</a>()</li>
+<li><a href="#label-11">exec</a>(sql, *bindvars)</li>
+<li><a href="#label-12">parse</a>(sql)</li>
+<li><a href="#label-13">commit</a>()</li>
+<li><a href="#label-14">rollback</a>()</li>
+<li><a href="#label-15">autocommit?</a></li>
+<li><a href="#label-16">autocommit</a></li>
+<li><a href="#label-17">autocommit=</a></li>
+<li><a href="#label-18">non_blocking?</a></li>
+<li><a href="#label-19">non_blocking=</a></li>
+<li><a href="#label-20">break</a>()</li>
+</ul></li>
+<li>OCI8::Cursor
+<ul>
+<li><a href="#label-22">define</a>(pos, type, length = nil)</li>
+<li><a href="#label-23">bind_param</a>(key, val, type = nil, length = nil)</li>
+<li><a href="#label-24">[]</a>(key)</li>
+<li><a href="#label-25">[]=</a>(key, val)</li>
+<li><a href="#label-26">keys</a>()</li>
+<li><a href="#label-27">exec</a>(*bindvars)</li>
+<li><a href="#label-28">type</a></li>
+<li><a href="#label-29">row_count</a></li>
+<li><a href="#label-30">get_col_names</a></li>
+<li><a href="#label-31">getColNames</a></li>
+<li><a href="#label-32">fetch</a>()</li>
+<li><a href="#label-33">close</a>()</li>
+<li><a href="#label-34">rowid</a></li>
+</ul></li>
+<li>OCI8::BLOB
+<ul>
+<li><a href="#label-36">available?</a></li>
+<li><a href="#label-37">read</a>(size = nil)</li>
+<li><a href="#label-38">write</a>(data)</li>
+<li><a href="#label-39">size</a></li>
+<li><a href="#label-40">size=</a>(len)</li>
+<li><a href="#label-41">chunk_size</a></li>
+<li><a href="#label-42">truncate</a>(len)</li>
+<li><a href="#label-43">pos</a></li>
+<li><a href="#label-44">pos=</a>(pos)</li>
+<li><a href="#label-46">tell</a></li>
+<li><a href="#label-47">seek</a>(pos)</li>
+<li><a href="#label-48">rewind</a></li>
+<li><a href="#label-45">eof?</a></li>
+</ul></li>
+</ul></li>
+<li><a href="#label-49">Appendix</a>
+<ul>
+<li><a href="#label-50">Blocking/Non-Blocking Mode</a></li>
+</ul></li>
+</ul>
+<h2><a name="label-2" id="label-2">Classes List</a></h2><!-- RDLabel: "Classes List" -->
+<p>Indispensable Classes to use high-level API are <a href="#label-3">OCI8</a>,
+<a href="#label-4">OCI8::Cursor</a>, <a href="#label-5">OCI8::BLOB</a> and <a href="#label-6">OCI Exception Classes</a>.</p>
+<h3><a name="label-3" id="label-3">OCI8</a></h3><!-- RDLabel: "OCI8" -->
+<p>The instance of this class corresponds to the connection with
+database, which corresponds to java.sql.Connection of JDBC and
+database handle $dbh of Perl/DBI.</p>
+<p>To execute simple SQL, it can perform by this class only.</p>
+<h3><a name="label-4" id="label-4">OCI8::Cursor</a></h3><!-- RDLabel: "OCI8::Cursor" -->
+<p>The instance of this class corresponds to cursor in the term of
+Oracle, which corresponds to java.sql.Statement of JDBC and statement
+handle $sth of Perl/DBI.</p>
+<p>Don't create the instance by calling 'new' method. Please create it by
+calling <a href="#label-11">OCI8#exec</a> or <a href="#label-12">OCI8#parse</a>.</p>
+<h3><a name="label-5" id="label-5">OCI8::BLOB</a></h3><!-- RDLabel: "OCI8::BLOB" -->
+<p>This is a lob locator to read/write binary data to/from BLOB column.
+This instance is automatically generated by select statement.</p>
+<h3><a name="label-6" id="label-6">OCI Exception Classes</a></h3><!-- RDLabel: "OCI Exception Classes" -->
+<p>The class hierarchy of OCI exception class used in high-level API is
+as follows.</p>
+<ul>
+<li><var>OCIException</var>
+<ul>
+<li><var>OCIError</var></li>
+<li><var>OCIInvalidHandle</var></li>
+<li><var>OCIBreak</var></li>
+</ul></li>
+</ul>
+<p><var>OCIException</var> is the abstract class for all OCI exceptions. To
+rescue all OCI exceptions, please use this class.</p>
+<p><var>OCIError</var> is the exception class with Oracle's error code. You
+get the error message by OCIError#message. The error code by
+OCIError#code.</p>
+<p><var>OCIInvalidHandle</var> is raised when OCI call is performed to
+the invalid handle.</p>
+<p><var>OCIBreak</var> is raised when the OCI call is canceled by other thread.
+See also <a href="#label-50">Blocking/Non-Blocking Mode</a>.</p>
+<h2><a name="label-7" id="label-7">Methods List</a></h2><!-- RDLabel: "Methods List" -->
+<h3><a name="label-8" id="label-8">OCI8</a></h3><!-- RDLabel: "OCI8" -->
+<dl>
+<dt><a name="label-9" id="label-9"><code>OCI8.new(<var>userid</var>, <var>password</var>, <var>dbname</var> = <var>nil</var>, <var>privilege</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "OCI8.new" -->
+<dd>
+<p>Connects to Oracle by userid and password. dbname is the connect
+string of Net8. If you need DBA privilege, please set privilege
+as :SYSDBA or :SYSOPER.</p>
+<p>example:</p>
+<pre># sqlplus scott/tiger@orcl.world
+conn = OCI8.new("scott", "tiger", "orcl.world")</pre>
+<p>example:</p>
+<pre># sqlplus 'sys/change_on_install as sysdba'
+conn = OCI8.new("sys", "change_on_install", nil, :SYSDBA)</pre></dd>
+<dt><a name="label-10" id="label-10"><code>OCI8#logoff()</code></a></dt><!-- RDLabel: "OCI8#logoff" -->
+<dd>
+<p>Disconnects from Oracle. Uncommitted transaction will be
+rollbacked.</p>
+<p>example:</p>
+<pre>conn = OCI8.new("scott", "tiger")
+... do something ...
+conn.logoff</pre></dd>
+<dt><a name="label-11" id="label-11"><code>OCI8#exec(<var>sql</var>, *<var>bindvars</var>)</code></a></dt><!-- RDLabel: "OCI8#exec" -->
+<dd>
+<p>Executes the sql statement. The type of return value depends on
+the type of sql statement: select; insert, update and delete;
+create, alter and drop; and PL/SQL.</p>
+<p>When bindvars are specified, they are bound as bind variables
+before execution.</p>
+<p>In case of select statement with no block, it returns the
+instance of OCI8::Cursor.</p>
+<p>example:</p>
+<pre>conn = OCI8.new('scott', 'tiger')
+cursor = conn.exec('SELECT * FROM emp')
+while r = cursor.fetch()
+  puts r.join(',')
+end
+cursor.close
+conn.logoff</pre>
+<p>In case of select statement with a block, it acts as iterator and
+returns the processed row counts. Fetched data is passed to the
+block as array. NULL value becomes nil in ruby.</p>
+<p>example:</p>
+<pre>conn = OCI8.new('scott', 'tiger')
+num_rows = conn.exec('SELECT * FROM emp') do |r|
+  puts r.join(',')
+end
+puts num_rows.to_s + ' rows were processed.'
+conn.logoff</pre>
+<p>In case of insert, update or delete statement, it returns the
+number of processed rows.</p>
+<p>example:</p>
+<pre>conn = OCI8.new('scott', 'tiger')
+num_rows = conn.exec('UPDATE emp SET sal = sal * 1.1')
+puts num_rows.to_s + ' rows were updated.'
+conn.logoff</pre>
+<p>In case of create, alter or drop statement, it returns true.</p>
+<p>example:</p>
+<pre>conn = OCI8.new('scott', 'tiger')
+conn.exec('CREATE TABLE test (col1 CHAR(6))')
+conn.logoff</pre>
+<p>In case of PL/SQL statement, it returns the array of bind
+variables.</p>
+<p>example:</p>
+<pre>conn = OCI8.new('scott', 'tiger')
+conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123)
+# =&gt; ["0123", 123]
+conn.logoff</pre>
+<p>Above example uses two bind variables which names are <var>:str</var>
+and <var>:num</var>. These initial values are "the string whose width
+is 4 and whose value is 'ABCD'" and "the number whose value is
+123". This method returns the array of these bind variables,
+which may modified by PL/SQL statement. The order of array is
+same with that of bind variables.</p></dd>
+<dt><a name="label-12" id="label-12"><code>OCI8#parse(<var>sql</var>)</code></a></dt><!-- RDLabel: "OCI8#parse" -->
+<dd>
+Creates cursor, prepare to execute SQL statement and return the
+instance of OCI8::Cursor.</dd>
+<dt><a name="label-13" id="label-13"><code>OCI8#commit()</code></a></dt><!-- RDLabel: "OCI8#commit" -->
+<dd>
+<p>Commits the transaction.</p>
+<p>example:</p>
+<pre>conn = OCI8.new("scott", "tiger")
+conn.exec("UPDATE emp SET sal = sal * 1.1") # yahoo
+conn.commit
+conn.logoff</pre></dd>
+<dt><a name="label-14" id="label-14"><code>OCI8#rollback()</code></a></dt><!-- RDLabel: "OCI8#rollback" -->
+<dd>
+<p>Rollbacks the transaction.</p>
+<p>example:</p>
+<pre>conn = OCI8.new("scott", "tiger")
+conn.exec("UPDATE emp SET sal = sal * 0.9") # boos
+conn.rollback
+conn.logoff</pre></dd>
+<dt><a name="label-15" id="label-15"><code>OCI8#autocommit?</code></a></dt><!-- RDLabel: "OCI8#autocommit?" -->
+<dd>
+Returns the state of the autocommit mode. The default value is
+false. If true, the transaction is committed automatically
+whenever executing insert/update/delete statements.</dd>
+<dt><a name="label-16" id="label-16"><code>OCI8#autocommit</code></a></dt><!-- RDLabel: "OCI8#autocommit" -->
+<dd>
+Alias of <a href="#label-15">OCI8#autocommit?</a>.</dd>
+<dt><a name="label-17" id="label-17"><code>OCI8#autocommit=</code></a></dt><!-- RDLabel: "OCI8#autocommit=" -->
+<dd>
+<p>Changes the status of the autocommit mode. Acceptable values are
+true and false.</p>
+<p>example:</p>
+<pre>conn = OCI8.new("scott", "tiger")
+conn.autocommit = true
+... do something ...
+conn.logoff</pre></dd>
+<dt><a name="label-18" id="label-18"><code>OCI8#non_blocking?</code></a></dt><!-- RDLabel: "OCI8#non_blocking?" -->
+<dd>
+Returns the status of blocking/non-blocking mode. The default
+value is false, that is blocking mode. See
+<a href="#label-50">Blocking/Non-Blocking Mode</a>.</dd>
+<dt><a name="label-19" id="label-19"><code>OCI8#non_blocking=</code></a></dt><!-- RDLabel: "OCI8#non_blocking=" -->
+<dd>
+Changes the status of blocking/non-blocking mode. Acceptable
+values are true and false. See
+<a href="#label-50">Blocking/Non-Blocking Mode</a>.</dd>
+<dt><a name="label-20" id="label-20"><code>OCI8#break()</code></a></dt><!-- RDLabel: "OCI8#break" -->
+<dd>
+Cancels the OCI call performing in other thread. To use this, the
+connection status must be non-blocking mode. See
+<a href="#label-50">Blocking/Non-Blocking Mode</a>.</dd>
+</dl>
+<h2><a name="label-21" id="label-21">OCI8::Cursor</a></h2><!-- RDLabel: "OCI8::Cursor" -->
+<dl>
+<dt><a name="label-22" id="label-22"><code>OCI8::Cursor#define(<var>pos</var>, <var>type</var>, <var>length</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "OCI8::Cursor#define" -->
+<dd>
+<p>explicitly indicate the date type of fetched value. run this
+method within parse and exec. pos starts from 1. lentgh is used
+when type is String.</p>
+<p>example:</p>
+<pre>cursor = conn.parse("SELECT ename, hiredate FROM emp")
+cursor.define(1, String, 20) # fetch the first column as String.
+cursor.define(2, Time)       # fetch the second column as Time.
+cursor.exec()</pre></dd>
+<dt><a name="label-23" id="label-23"><code>OCI8::Cursor#bind_param(<var>key</var>, <var>val</var>, <var>type</var> = <var>nil</var>, <var>length</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "OCI8::Cursor#bind_param" -->
+<dd>
+<p>Binds variables explicitly.</p>
+<p>When key is number, it binds by position, which starts from 1.
+When key is string, it binds by the name of placeholder.</p>
+<p>example:</p>
+<pre>cursor = conn.parse("SELECT * FROM emp WHERE ename = :ename")
+cursor.bind_param(1, 'SMITH') # bind by position
+  ...or...
+cursor.bind_param(':ename', 'SMITH') # bind by name</pre>
+<p>To bind as number, Fixnum and Float are available, but Bignum is
+not supported. If its initial value is NULL, please set nil to
+<var>type</var> and Fixnum or Float to <var>val</var>.</p>
+<p>example:</p>
+<pre>cursor.bind_param(1, 1234) # bind as Fixnum, Initial value is 1234.
+cursor.bind_param(1, 1234.0) # bind as Float, Initial value is 1234.0.
+cursor.bind_param(1, nil, Fixnum) # bind as Fixnum, Initial value is NULL.
+cursor.bind_param(1, nil, Float) # bind as Float, Initial value is NULL.</pre>
+<p>In case of binding a string, set the string itself to
+<var>val</var>. When the bind variable is used as output, set the
+string whose length is enough to store or set the length.</p>
+<p>example:</p>
+<pre>cursor = conn.parse("BEGIN :out := :in || '_OUT'; END;")
+cursor.bind_param(':in', 'DATA') # bind as String with width 4.
+cursor.bind_param(':out', nil, String, 7) # bind as String with width 7.
+cursor.exec()
+p cursor[':out'] # =&gt; 'DATA_OU'
+# Though the length of :out is 8 bytes in PL/SQL block, it is
+# bound as 7 bytes. So result is cut off at 7 byte.</pre>
+<p>In case of binding a string as RAW, set OCI::RAW to <var>type</var>.</p>
+<p>example:</p>
+<pre>cursor = conn.parse("INSERT INTO raw_table(raw_column) VALUE (:1)")
+cursor.bind_param(1, 'RAW_STRING', OCI8::RAW)
+cursor.exec()
+cursor.close()</pre></dd>
+<dt><a name="label-24" id="label-24"><code>OCI8::Cursor#[<var>key</var>]</code></a></dt><!-- RDLabel: "OCI8::Cursor#[]" -->
+<dd>
+<p>Gets the value of the bind variable.</p>
+<p>In case of binding explicitly, use same key with that of
+<a href="#label-23">OCI8::Cursor#bind_param</a>. A placeholder can be bound by
+name or position. If you bind by name, use that name. If you bind
+by position, use the position.</p>
+<p>example:</p>
+<pre>cursor = conn.parse("BEGIN :out := 'BAR'; END;")
+cursor.bind_param(':out', 'FOO') # bind by name
+p cursor[':out'] # =&gt; 'FOO'
+p cursor[1] # =&gt; nil
+cursor.exec()
+p cursor[':out'] # =&gt; 'BAR'
+p cursor[1] # =&gt; nil</pre>
+<p>example:</p>
+<pre>cursor = conn.parse("BEGIN :out := 'BAR'; END;")
+cursor.bind_param(1, 'FOO') # bind by position
+p cursor[':out'] # =&gt; nil
+p cursor[1] # =&gt; 'FOO'
+cursor.exec()
+p cursor[':out'] # =&gt; nil
+p cursor[1] # =&gt; 'BAR'</pre>
+<p>In case of binding by <a href="#label-11">OCI8#exec</a> or <a href="#label-27">OCI8::Cursor#exec</a>,
+get the value by position, which starts from 1.</p>
+<p>example:</p>
+<pre>cursor = conn.exec("BEGIN :out := 'BAR'; END;", 'FOO')
+# 1st bind variable is bound as String with width 3. Its initial value is 'FOO'
+# After execute, the value become 'BAR'.
+p cursor[1] # =&gt; 'BAR'</pre></dd>
+<dt><a name="label-25" id="label-25"><code>OCI8::Cursor#[<var>key</var>] = <var>val</var></code></a></dt><!-- RDLabel: "OCI8::Cursor#[]=" -->
+<dd>
+<p>Sets the value to the bind variable. The way to specify the
+<var>key</var> is same with <a href="#label-24">OCI8::Cursor#[]</a>. This is available
+to replace the value and execute many times.</p>
+<p>example1:</p>
+<pre>cursor = conn.parse("INSERT INTO test(col1) VALUES(:1)")
+cursor.bind_params(1, nil, String, 3)
+['FOO', 'BAR', 'BAZ'].each do |key|
+  cursor[1] = key
+  cursor.exec
+end
+cursor.close()</pre>
+<p>example2:</p>
+<pre>['FOO', 'BAR', 'BAZ'].each do |key|
+  conn.exec("INSERT INTO test(col1) VALUES(:1)", key)
+end</pre>
+<p>Both example's results are same. But the former will use less resources.</p></dd>
+<dt><a name="label-26" id="label-26"><code>OCI8::Cursor#keys()</code></a></dt><!-- RDLabel: "OCI8::Cursor#keys" -->
+<dd>
+Returns the keys of bind variables as array.</dd>
+<dt><a name="label-27" id="label-27"><code>OCI8::Cursor#exec(*<var>bindvars</var>)</code></a></dt><!-- RDLabel: "OCI8::Cursor#exec" -->
+<dd>
+<p>Executes the SQL statement assigned the cursor. The type of
+return value depends on the type of sql statement: select;
+insert, update and delete; create, alter, drop and PL/SQL.</p>
+<p>In case of select statement, it returns the number of the
+select-list.</p>
+<p>In case of insert, update or delete statement, it returns the
+number of processed rows.</p>
+<p>In case of create, alter, drop and PL/SQL statement, it returns
+true. In contrast with <a href="#label-11">OCI8#exec</a>, it returns true even
+though PL/SQL. Use <a href="#label-24">OCI8::Cursor#[]</a> explicitly to get bind
+variables.</p></dd>
+<dt><a name="label-28" id="label-28"><code>OCI8::Cursor#type</code></a></dt><!-- RDLabel: "OCI8::Cursor#type" -->
+<dd>
+<p>gets the type of SQL statement. Its value is one of the follows.</p>
+<ul>
+<li>OCI8::STMT_SELECT</li>
+<li>OCI8::STMT_UPDATE</li>
+<li>OCI8::STMT_DELETE</li>
+<li>OCI8::STMT_INSERT</li>
+<li>OCI8::STMT_CREATE</li>
+<li>OCI8::STMT_DROP</li>
+<li>OCI8::STMT_ALTER</li>
+<li>OCI8::STMT_BEGIN</li>
+<li>OCI8::STMT_DECLARE</li>
+</ul>
+<p>For PL/SQL statement, it returns OCI8::STMT_BEGIN or
+OCI8::STMT_DECLARE.</p></dd>
+<dt><a name="label-29" id="label-29"><code>OCI8::Cursor#row_count</code></a></dt><!-- RDLabel: "OCI8::Cursor#row_count" -->
+<dd>
+Returns the number of processed rows.</dd>
+<dt><a name="label-30" id="label-30"><code>OCI8::Cursor#get_col_names</code></a></dt><!-- RDLabel: "OCI8::Cursor#get_col_names" -->
+<dd>
+Gets the names of select-list as array. Please use this
+method after exec.</dd>
+<dt><a name="label-31" id="label-31"><code>OCI8::Cursor#getColNames</code></a></dt><!-- RDLabel: "OCI8::Cursor#getColNames" -->
+<dd>
+Alias of <a href="#label-30">OCI8::Cursor#get_col_names</a>.</dd>
+<dt><a name="label-32" id="label-32"><code>OCI8::Cursor#fetch()</code></a></dt><!-- RDLabel: "OCI8::Cursor#fetch" -->
+<dd>
+<p>Gets fetched data as array. This is available for select
+statement only.</p>
+<p>example:</p>
+<pre>conn = OCI8.new('scott', 'tiger')
+cursor = conn.exec('SELECT * FROM emp')
+while r = cursor.fetch()
+  puts r.join(',')
+end
+cursor.close
+conn.logoff</pre></dd>
+<dt><a name="label-33" id="label-33"><code>OCI8::Cursor#close()</code></a></dt><!-- RDLabel: "OCI8::Cursor#close" -->
+<dd>
+close the cursor.</dd>
+<dt><a name="label-34" id="label-34"><code>OCI8::Cursor#rowid()</code></a></dt><!-- RDLabel: "OCI8::Cursor#rowid" -->
+<dd>
+get the rowid of the last processed row.
+This value is available as bind data.
+On the other hand it isn't available for other purpose.</dd>
+</dl>
+<h2><a name="label-35" id="label-35">OCI8::BLOB</a></h2><!-- RDLabel: "OCI8::BLOB" -->
+<dl>
+<dt><a name="label-36" id="label-36"><code>OCI8::BLOB#available?</code></a></dt><!-- RDLabel: "OCI8::BLOB#available?" -->
+<dd>
+<p>check whether BLOB is available or not.
+To use BLOB you need to insert EMPTY_BLOB() at first.</p>
+<p>example:</p>
+<pre>conn.exec("CREATE TABLE photo (name VARCHAR2(50), image BLOB)")
+conn.exec("INSERT INTO photo VALUES ('null-data', NULL)")
+conn.exec("INSERT INTO photo VALUES ('empty-data', EMPTY_BLOB())")
+conn.exec("SELECT name, image FROM photo") do |name, image|
+  case name
+  when 'null-data'
+    puts "#{name} =&gt; #{image.available?.to_s}"
+    # =&gt; false
+  when 'empty-data'
+    puts "#{name} =&gt; #{image.available?.to_s}"
+    # =&gt; true
+  end
+end</pre></dd>
+<dt><a name="label-37" id="label-37"><code>OCI8::BLOB#read(<var>size</var> = <var>nil</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#read" -->
+<dd>
+<p>read at most size bytes from BLOB, or to the end of file if size is omitted.</p>
+<p>example: read chunks of chunk size.</p>
+<pre>conn.exec("SELECT name, image FROM photo") do |name, image|
+  chunk_size = image.chunk_size
+  File.open(name, 'w') do |f|
+    until image.eof?
+      f.write(image.read(chunk_size))
+    end
+  end
+end</pre>
+<p>example: read at once.</p>
+<pre>conn.exec("SELECT name, image FROM photo") do |name, image|
+  File.open(name, 'w') do |f|
+    f.write(image.read)
+  end
+end</pre></dd>
+<dt><a name="label-38" id="label-38"><code>OCI8::BLOB#write(<var>string</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#write" -->
+<dd>
+<p>write the given string to BLOB.
+If old data is longer than new data, resize by <a href="#label-40">OCI8::BLOB#size=</a>.</p>
+<p>example: write chunks of chunk size.</p>
+<pre>cursor = conn.parse("INSERT INTO photo VALUES(:name, EMPTY_BLOB())")
+Dir["*.png"].each do |fname|
+  cursor.exec(fname)
+end
+conn.exec("SELECT name, image FROM photo") do |name, image|
+  chunk_size = image.chunk_size
+  File.open(name, 'r') do |f|
+    until f.eof?
+      image.write(f.read(chunk_size))
+    end
+    image.size = f.pos
+  end
+end
+conn.commit</pre>
+<p>example: write at once.</p>
+<pre>conn.exec("SELECT name, image FROM photo") do |name, image|
+  File.open(name, 'r') do |f|
+    image.write(f.read)
+    image.size = f.pos
+  end
+end</pre></dd>
+<dt><a name="label-39" id="label-39"><code>OCI8::BLOB#size</code></a></dt><!-- RDLabel: "OCI8::BLOB#size" -->
+<dd>
+return the size of BLOB.</dd>
+<dt><a name="label-40" id="label-40"><code>OCI8::BLOB#size=(<var>len</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#size=" -->
+<dd>
+set the size of BLOB.</dd>
+<dt><a name="label-41" id="label-41"><code>OCI8::BLOB#chunk_size</code></a></dt><!-- RDLabel: "OCI8::BLOB#chunk_size" -->
+<dd>
+return the chunk size of BLOB.</dd>
+<dt><a name="label-42" id="label-42"><code>OCI8::BLOB#truncate(<var>len</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#truncate" -->
+<dd>
+set the size of BLOB.</dd>
+<dt><a name="label-43" id="label-43"><code>OCI8::BLOB#pos</code></a></dt><!-- RDLabel: "OCI8::BLOB#pos" -->
+<dd>
+return the current offset of BLOB.</dd>
+<dt><a name="label-44" id="label-44"><code>OCI8::BLOB#pos=(<var>pos</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#pos=" -->
+<dd>
+set the current offset of BLOB.</dd>
+<dt><a name="label-45" id="label-45"><code>OCI8::BLOB#eof?</code></a></dt><!-- RDLabel: "OCI8::BLOB#eof?" -->
+<dd>
+return true if BLOB is at end of file</dd>
+<dt><a name="label-46" id="label-46"><code>OCI8::BLOB#tell</code></a></dt><!-- RDLabel: "OCI8::BLOB#tell" -->
+<dd>
+Synonym for <a href="#label-43">OCI8::BLOB#pos</a>.</dd>
+<dt><a name="label-47" id="label-47"><code>OCI8::BLOB#seek(<var>pos</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#seek" -->
+<dd>
+Synonym for <a href="#label-44">OCI8::BLOB#pos=</a>.</dd>
+<dt><a name="label-48" id="label-48"><code>OCI8::BLOB#rewind</code></a></dt><!-- RDLabel: "OCI8::BLOB#rewind" -->
+<dd>
+set the current offset to zero.</dd>
+</dl>
+<h2><a name="label-49" id="label-49">Appendix</a></h2><!-- RDLabel: "Appendix" -->
+<h3><a name="label-50" id="label-50">Blocking/Non-Blocking Mode</a></h3><!-- RDLabel: "Blocking/Non-Blocking Mode" -->
+<p>The default mode is blocking mode. You can change the mode by
+<a href="#label-19">OCI8#non_blocking=</a>.</p>
+<p>When the mode is blocking, heavy OCI calls will block the process
+itself even though multithread application because ruby's thread is
+not native one.</p>
+<p>when the mode is non-blocking, heavy OCI calls will not block the
+process, but block the thread only. Instead of the merit, each OCI
+call become a bit slower because it polls many times whether the OCI
+call is finished or not.</p>
+<p>You can cancel a OCI call by using <a href="#label-20">OCI8#break</a> from other thread.
+The canceled OCI call raises <var>OCIBreak</var> exception.</p>
+<p>Restriction of non-blocking mode: Don't do OCI calls at the same time
+for a same connection.</p>
+<hr />
+<p class="foottext">
+<a name="foottext-1" id="foottext-1" href="#footmark-1"><sup><small>*1</small></sup></a><small>Oracle
+Call Interface</small><br />
+</p>
+</body>
+</html>