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

ruby-oci8 2.0.4-x86-mingw32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

data/doc/api.en.html ADDED

@@ -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>