ruby-oci8 1.0.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (71) hide show
  1. data/ChangeLog +569 -0
  2. data/Makefile +51 -0
  3. data/NEWS +322 -0
  4. data/README +415 -0
  5. data/VERSION +1 -0
  6. data/dist-files +70 -0
  7. data/doc/api.en.html +527 -0
  8. data/doc/api.en.rd +554 -0
  9. data/doc/api.ja.html +525 -0
  10. data/doc/api.ja.rd +557 -0
  11. data/doc/manual.css +35 -0
  12. data/ext/oci8/MANIFEST +22 -0
  13. data/ext/oci8/attr.c +415 -0
  14. data/ext/oci8/bind.c +194 -0
  15. data/ext/oci8/const.c +165 -0
  16. data/ext/oci8/define.c +53 -0
  17. data/ext/oci8/describe.c +81 -0
  18. data/ext/oci8/descriptor.c +39 -0
  19. data/ext/oci8/env.c +276 -0
  20. data/ext/oci8/error.c +234 -0
  21. data/ext/oci8/extconf.rb +118 -0
  22. data/ext/oci8/handle.c +262 -0
  23. data/ext/oci8/lob.c +386 -0
  24. data/ext/oci8/oci8.c +137 -0
  25. data/ext/oci8/oci8.h +345 -0
  26. data/ext/oci8/ocinumber.c +117 -0
  27. data/ext/oci8/oraconf.rb +1026 -0
  28. data/ext/oci8/oradate.c +426 -0
  29. data/ext/oci8/oranumber.c +445 -0
  30. data/ext/oci8/param.c +37 -0
  31. data/ext/oci8/post-config.rb +5 -0
  32. data/ext/oci8/server.c +182 -0
  33. data/ext/oci8/session.c +99 -0
  34. data/ext/oci8/stmt.c +624 -0
  35. data/ext/oci8/svcctx.c +229 -0
  36. data/lib/DBD/OCI8/OCI8.rb +549 -0
  37. data/lib/oci8.rb.in +1605 -0
  38. data/metaconfig +142 -0
  39. data/pre-distclean.rb +7 -0
  40. data/ruby-oci8.gemspec +54 -0
  41. data/ruby-oci8.spec +62 -0
  42. data/setup.rb +1331 -0
  43. data/support/README +4 -0
  44. data/support/runit/assert.rb +281 -0
  45. data/support/runit/cui/testrunner.rb +101 -0
  46. data/support/runit/error.rb +4 -0
  47. data/support/runit/method_mappable.rb +20 -0
  48. data/support/runit/robserver.rb +25 -0
  49. data/support/runit/setuppable.rb +15 -0
  50. data/support/runit/teardownable.rb +16 -0
  51. data/support/runit/testcase.rb +113 -0
  52. data/support/runit/testfailure.rb +25 -0
  53. data/support/runit/testresult.rb +121 -0
  54. data/support/runit/testsuite.rb +43 -0
  55. data/support/runit/version.rb +3 -0
  56. data/test/README +4 -0
  57. data/test/config.rb +129 -0
  58. data/test/test_all.rb +43 -0
  59. data/test/test_bind_raw.rb +53 -0
  60. data/test/test_bind_time.rb +191 -0
  61. data/test/test_break.rb +81 -0
  62. data/test/test_clob.rb +101 -0
  63. data/test/test_connstr.rb +80 -0
  64. data/test/test_dbi.rb +317 -0
  65. data/test/test_dbi_clob.rb +56 -0
  66. data/test/test_describe.rb +137 -0
  67. data/test/test_metadata.rb +243 -0
  68. data/test/test_oci8.rb +273 -0
  69. data/test/test_oradate.rb +263 -0
  70. data/test/test_oranumber.rb +149 -0
  71. metadata +118 -0
data/VERSION ADDED
@@ -0,0 +1 @@
1
+ 1.0.2
@@ -0,0 +1,70 @@
1
+ NEWS
2
+ ChangeLog
3
+ Makefile
4
+ README
5
+ VERSION
6
+ dist-files
7
+ metaconfig
8
+ pre-distclean.rb
9
+ ruby-oci8.spec
10
+ ruby-oci8.gemspec
11
+ setup.rb
12
+ doc/api.en.html
13
+ doc/api.en.rd
14
+ doc/api.ja.html
15
+ doc/api.ja.rd
16
+ doc/manual.css
17
+ ext/oci8/MANIFEST
18
+ ext/oci8/attr.c
19
+ ext/oci8/bind.c
20
+ ext/oci8/const.c
21
+ ext/oci8/define.c
22
+ ext/oci8/describe.c
23
+ ext/oci8/descriptor.c
24
+ ext/oci8/env.c
25
+ ext/oci8/error.c
26
+ ext/oci8/extconf.rb
27
+ ext/oci8/handle.c
28
+ ext/oci8/lob.c
29
+ ext/oci8/oci8.c
30
+ ext/oci8/oci8.h
31
+ ext/oci8/ocinumber.c
32
+ ext/oci8/oraconf.rb
33
+ ext/oci8/oradate.c
34
+ ext/oci8/oranumber.c
35
+ ext/oci8/param.c
36
+ ext/oci8/post-config.rb
37
+ ext/oci8/server.c
38
+ ext/oci8/session.c
39
+ ext/oci8/stmt.c
40
+ ext/oci8/svcctx.c
41
+ lib/oci8.rb.in
42
+ lib/DBD/OCI8/OCI8.rb
43
+ support/README
44
+ support/runit/assert.rb
45
+ support/runit/cui/testrunner.rb
46
+ support/runit/error.rb
47
+ support/runit/method_mappable.rb
48
+ support/runit/robserver.rb
49
+ support/runit/setuppable.rb
50
+ support/runit/teardownable.rb
51
+ support/runit/testcase.rb
52
+ support/runit/testfailure.rb
53
+ support/runit/testresult.rb
54
+ support/runit/testsuite.rb
55
+ support/runit/version.rb
56
+ test/README
57
+ test/config.rb
58
+ test/test_all.rb
59
+ test/test_bind_raw.rb
60
+ test/test_bind_time.rb
61
+ test/test_break.rb
62
+ test/test_clob.rb
63
+ test/test_connstr.rb
64
+ test/test_dbi.rb
65
+ test/test_dbi_clob.rb
66
+ test/test_describe.rb
67
+ test/test_oci8.rb
68
+ test/test_oradate.rb
69
+ test/test_oranumber.rb
70
+ test/test_metadata.rb
@@ -0,0 +1,527 @@
1
+ <?xml version="1.0" ?>
2
+ <!DOCTYPE html
3
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
+ <html xmlns="http://www.w3.org/1999/xhtml">
6
+ <head>
7
+ <title>Ruby/OCI8 High-level API</title>
8
+ <link href="manual.css" type="text/css" rel="stylesheet" />
9
+ </head>
10
+ <body>
11
+ <h1><a name="label-0" id="label-0">Ruby/OCI8 High-level API</a></h1><!-- RDLabel: "Ruby/OCI8 High-level API" -->
12
+ <p>[ <a href="index.en.html">Home</a> ] [ English | <a href="api.ja.html">Japanese</a> ]</p>
13
+ <p>Ruby/OCI8 is divided to two layer APIs. One is "Low-level
14
+ API". The other is "High-level API". This document describes how to
15
+ use the latter, but some of the former will be described as long as it
16
+ is necessary to use the latter.</p>
17
+ <p>"High-level API" is the library written by ruby, which based on
18
+ "Low-level API". This API hides complicated structure of OCI and make
19
+ it easy to issue SQL statements as possible. Please use this for general purpose.</p>
20
+ <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
21
+ and methods respectively. The handles and functions are converted by
22
+ straight mapping rule as long as ruby's syntax allows. </p>
23
+ <p>In the version 0.2 I will rewrite High-level API by C language directly.
24
+ Low-level API will be obsolete.</p>
25
+ <h2><a name="label-1" id="label-1">Contents</a></h2><!-- RDLabel: "Contents" -->
26
+ <ul>
27
+ <li><a href="#label-2">Classes List</a>
28
+ <ul>
29
+ <li><a href="#label-3">OCI8</a></li>
30
+ <li><a href="#label-4">OCI8::Cursor</a></li>
31
+ <li><a href="#label-5">OCI8::BLOB</a></li>
32
+ <li><a href="#label-6">OCI Exception Classes</a></li>
33
+ </ul></li>
34
+ <li><a href="#label-7">Methods List</a>
35
+ <ul>
36
+ <li>OCI8
37
+ <ul>
38
+ <li><a href="#label-9">new</a>(userid, password, dbname = nil, privilege = nil)</li>
39
+ <li><a href="#label-10">logoff</a>()</li>
40
+ <li><a href="#label-11">exec</a>(sql, *bindvars)</li>
41
+ <li><a href="#label-12">parse</a>(sql)</li>
42
+ <li><a href="#label-13">commit</a>()</li>
43
+ <li><a href="#label-14">rollback</a>()</li>
44
+ <li><a href="#label-15">autocommit?</a></li>
45
+ <li><a href="#label-16">autocommit</a></li>
46
+ <li><a href="#label-17">autocommit=</a></li>
47
+ <li><a href="#label-18">non_blocking?</a></li>
48
+ <li><a href="#label-19">non_blocking=</a></li>
49
+ <li><a href="#label-20">break</a>()</li>
50
+ </ul></li>
51
+ <li>OCI8::Cursor
52
+ <ul>
53
+ <li><a href="#label-22">define</a>(pos, type, length = nil)</li>
54
+ <li><a href="#label-23">bind_param</a>(key, val, type = nil, length = nil)</li>
55
+ <li><a href="#label-24">[]</a>(key)</li>
56
+ <li><a href="#label-25">[]=</a>(key, val)</li>
57
+ <li><a href="#label-26">keys</a>()</li>
58
+ <li><a href="#label-27">exec</a>(*bindvars)</li>
59
+ <li><a href="#label-28">type</a></li>
60
+ <li><a href="#label-29">row_count</a></li>
61
+ <li><a href="#label-30">get_col_names</a></li>
62
+ <li><a href="#label-31">getColNames</a></li>
63
+ <li><a href="#label-32">fetch</a>()</li>
64
+ <li><a href="#label-33">close</a>()</li>
65
+ <li><a href="#label-34">rowid</a></li>
66
+ </ul></li>
67
+ <li>OCI8::BLOB
68
+ <ul>
69
+ <li><a href="#label-36">available?</a></li>
70
+ <li><a href="#label-37">read</a>(size = nil)</li>
71
+ <li><a href="#label-38">write</a>(data)</li>
72
+ <li><a href="#label-39">size</a></li>
73
+ <li><a href="#label-40">size=</a>(len)</li>
74
+ <li><a href="#label-41">chunk_size</a></li>
75
+ <li><a href="#label-42">truncate</a>(len)</li>
76
+ <li><a href="#label-43">pos</a></li>
77
+ <li><a href="#label-44">pos=</a>(pos)</li>
78
+ <li><a href="#label-46">tell</a></li>
79
+ <li><a href="#label-47">seek</a>(pos)</li>
80
+ <li><a href="#label-48">rewind</a></li>
81
+ <li><a href="#label-45">eof?</a></li>
82
+ </ul></li>
83
+ </ul></li>
84
+ <li><a href="#label-49">Appendix</a>
85
+ <ul>
86
+ <li><a href="#label-50">Blocking/Non-Blocking Mode</a></li>
87
+ </ul></li>
88
+ </ul>
89
+ <h2><a name="label-2" id="label-2">Classes List</a></h2><!-- RDLabel: "Classes List" -->
90
+ <p>Indispensable Classes to use high-level API are <a href="#label-3">OCI8</a>,
91
+ <a href="#label-4">OCI8::Cursor</a>, <a href="#label-5">OCI8::BLOB</a> and <a href="#label-6">OCI Exception Classes</a>.</p>
92
+ <h3><a name="label-3" id="label-3">OCI8</a></h3><!-- RDLabel: "OCI8" -->
93
+ <p>The instance of this class corresponds to the connection with
94
+ database, which corresponds to java.sql.Connection of JDBC and
95
+ database handle $dbh of Perl/DBI.</p>
96
+ <p>To execute simple SQL, it can perform by this class only.</p>
97
+ <h3><a name="label-4" id="label-4">OCI8::Cursor</a></h3><!-- RDLabel: "OCI8::Cursor" -->
98
+ <p>The instance of this class corresponds to cursor in the term of
99
+ Oracle, which corresponds to java.sql.Statement of JDBC and statement
100
+ handle $sth of Perl/DBI.</p>
101
+ <p>Don't create the instance by calling 'new' method. Please create it by
102
+ calling <a href="#label-11">OCI8#exec</a> or <a href="#label-12">OCI8#parse</a>.</p>
103
+ <h3><a name="label-5" id="label-5">OCI8::BLOB</a></h3><!-- RDLabel: "OCI8::BLOB" -->
104
+ <p>This is a lob locator to read/write binary data to/from BLOB column.
105
+ This instance is automatically generated by select statement.</p>
106
+ <h3><a name="label-6" id="label-6">OCI Exception Classes</a></h3><!-- RDLabel: "OCI Exception Classes" -->
107
+ <p>The class hierarchy of OCI exception class used in high-level API is
108
+ as follows.</p>
109
+ <ul>
110
+ <li><var>OCIException</var>
111
+ <ul>
112
+ <li><var>OCIError</var></li>
113
+ <li><var>OCIInvalidHandle</var></li>
114
+ <li><var>OCIBreak</var></li>
115
+ </ul></li>
116
+ </ul>
117
+ <p><var>OCIException</var> is the abstract class for all OCI exceptions. To
118
+ rescue all OCI exceptions, please use this class.</p>
119
+ <p><var>OCIError</var> is the exception class with Oracle's error code. You
120
+ get the error message by OCIError#message. The error code by
121
+ OCIError#code.</p>
122
+ <p><var>OCIInvalidHandle</var> is raised when OCI call is performed to
123
+ the invalid handle.</p>
124
+ <p><var>OCIBreak</var> is raised when the OCI call is canceled by other thread.
125
+ See also <a href="#label-50">Blocking/Non-Blocking Mode</a>.</p>
126
+ <h2><a name="label-7" id="label-7">Methods List</a></h2><!-- RDLabel: "Methods List" -->
127
+ <h3><a name="label-8" id="label-8">OCI8</a></h3><!-- RDLabel: "OCI8" -->
128
+ <dl>
129
+ <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" -->
130
+ <dd>
131
+ <p>Connects to Oracle by userid and password. dbname is the connect
132
+ string of Net8. If you need DBA privilege, please set privilege
133
+ as :SYSDBA or :SYSOPER.</p>
134
+ <p>example:</p>
135
+ <pre># sqlplus scott/tiger@orcl.world
136
+ conn = OCI8.new("scott", "tiger", "orcl.world")</pre>
137
+ <p>example:</p>
138
+ <pre># sqlplus 'sys/change_on_install as sysdba'
139
+ conn = OCI8.new("sys", "change_on_install", nil, :SYSDBA)</pre></dd>
140
+ <dt><a name="label-10" id="label-10"><code>OCI8#logoff()</code></a></dt><!-- RDLabel: "OCI8#logoff" -->
141
+ <dd>
142
+ <p>Disconnects from Oracle. Uncommitted transaction will be
143
+ rollbacked.</p>
144
+ <p>example:</p>
145
+ <pre>conn = OCI8.new("scott", "tiger")
146
+ ... do something ...
147
+ conn.logoff</pre></dd>
148
+ <dt><a name="label-11" id="label-11"><code>OCI8#exec(<var>sql</var>, *<var>bindvars</var>)</code></a></dt><!-- RDLabel: "OCI8#exec" -->
149
+ <dd>
150
+ <p>Executes the sql statement. The type of return value depends on
151
+ the type of sql statement: select; insert, update and delete;
152
+ create, alter and drop; and PL/SQL.</p>
153
+ <p>When bindvars are specified, they are bound as bind variables
154
+ before execution.</p>
155
+ <p>In case of select statement with no block, it returns the
156
+ instance of OCI8::Cursor.</p>
157
+ <p>example:</p>
158
+ <pre>conn = OCI8.new('scott', 'tiger')
159
+ cursor = conn.exec('SELECT * FROM emp')
160
+ while r = cursor.fetch()
161
+ puts r.join(',')
162
+ end
163
+ cursor.close
164
+ conn.logoff</pre>
165
+ <p>In case of select statement with a block, it acts as iterator and
166
+ returns the processed row counts. Fetched data is passed to the
167
+ block as array. NULL value becomes nil in ruby.</p>
168
+ <p>example:</p>
169
+ <pre>conn = OCI8.new('scott', 'tiger')
170
+ num_rows = conn.exec('SELECT * FROM emp') do |r|
171
+ puts r.join(',')
172
+ end
173
+ puts num_rows.to_s + ' rows were processed.'
174
+ conn.logoff</pre>
175
+ <p>In case of insert, update or delete statement, it returns the
176
+ number of processed rows.</p>
177
+ <p>example:</p>
178
+ <pre>conn = OCI8.new('scott', 'tiger')
179
+ num_rows = conn.exec('UPDATE emp SET sal = sal * 1.1')
180
+ puts num_rows.to_s + ' rows were updated.'
181
+ conn.logoff</pre>
182
+ <p>In case of create, alter or drop statement, it returns true.</p>
183
+ <p>example:</p>
184
+ <pre>conn = OCI8.new('scott', 'tiger')
185
+ conn.exec('CREATE TABLE test (col1 CHAR(6))')
186
+ conn.logoff</pre>
187
+ <p>In case of PL/SQL statement, it returns the array of bind
188
+ variables.</p>
189
+ <p>example:</p>
190
+ <pre>conn = OCI8.new('scott', 'tiger')
191
+ conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123)
192
+ # =&gt; ["0123", 123]
193
+ conn.logoff</pre>
194
+ <p>Above example uses two bind variables which names are <var>:str</var>
195
+ and <var>:num</var>. These initial values are "the string whose width
196
+ is 4 and whose value is 'ABCD'" and "the number whose value is
197
+ 123". This method returns the array of these bind variables,
198
+ which may modified by PL/SQL statement. The order of array is
199
+ same with that of bind variables.</p></dd>
200
+ <dt><a name="label-12" id="label-12"><code>OCI8#parse(<var>sql</var>)</code></a></dt><!-- RDLabel: "OCI8#parse" -->
201
+ <dd>
202
+ Creates cursor, prepare to execute SQL statement and return the
203
+ instance of OCI8::Cursor.</dd>
204
+ <dt><a name="label-13" id="label-13"><code>OCI8#commit()</code></a></dt><!-- RDLabel: "OCI8#commit" -->
205
+ <dd>
206
+ <p>Commits the transaction.</p>
207
+ <p>example:</p>
208
+ <pre>conn = OCI8.new("scott", "tiger")
209
+ conn.exec("UPDATE emp SET sal = sal * 1.1") # yahoo
210
+ conn.commit
211
+ conn.logoff</pre></dd>
212
+ <dt><a name="label-14" id="label-14"><code>OCI8#rollback()</code></a></dt><!-- RDLabel: "OCI8#rollback" -->
213
+ <dd>
214
+ <p>Rollbacks the transaction.</p>
215
+ <p>example:</p>
216
+ <pre>conn = OCI8.new("scott", "tiger")
217
+ conn.exec("UPDATE emp SET sal = sal * 0.9") # boos
218
+ conn.rollback
219
+ conn.logoff</pre></dd>
220
+ <dt><a name="label-15" id="label-15"><code>OCI8#autocommit?</code></a></dt><!-- RDLabel: "OCI8#autocommit?" -->
221
+ <dd>
222
+ Returns the state of the autocommit mode. The default value is
223
+ false. If true, the transaction is committed automatically
224
+ whenever executing insert/update/delete statements.</dd>
225
+ <dt><a name="label-16" id="label-16"><code>OCI8#autocommit</code></a></dt><!-- RDLabel: "OCI8#autocommit" -->
226
+ <dd>
227
+ Alias of <a href="#label-15">OCI8#autocommit?</a>.</dd>
228
+ <dt><a name="label-17" id="label-17"><code>OCI8#autocommit=</code></a></dt><!-- RDLabel: "OCI8#autocommit=" -->
229
+ <dd>
230
+ <p>Changes the status of the autocommit mode. Acceptable values are
231
+ true and false.</p>
232
+ <p>example:</p>
233
+ <pre>conn = OCI8.new("scott", "tiger")
234
+ conn.autocommit = true
235
+ ... do something ...
236
+ conn.logoff</pre></dd>
237
+ <dt><a name="label-18" id="label-18"><code>OCI8#non_blocking?</code></a></dt><!-- RDLabel: "OCI8#non_blocking?" -->
238
+ <dd>
239
+ Returns the status of blocking/non-blocking mode. The default
240
+ value is false, that is blocking mode. See
241
+ <a href="#label-50">Blocking/Non-Blocking Mode</a>.</dd>
242
+ <dt><a name="label-19" id="label-19"><code>OCI8#non_blocking=</code></a></dt><!-- RDLabel: "OCI8#non_blocking=" -->
243
+ <dd>
244
+ Changes the status of blocking/non-blocking mode. Acceptable
245
+ values are true and false. See
246
+ <a href="#label-50">Blocking/Non-Blocking Mode</a>.</dd>
247
+ <dt><a name="label-20" id="label-20"><code>OCI8#break()</code></a></dt><!-- RDLabel: "OCI8#break" -->
248
+ <dd>
249
+ Cancels the OCI call performing in other thread. To use this, the
250
+ connection status must be non-blocking mode. See
251
+ <a href="#label-50">Blocking/Non-Blocking Mode</a>.</dd>
252
+ </dl>
253
+ <h2><a name="label-21" id="label-21">OCI8::Cursor</a></h2><!-- RDLabel: "OCI8::Cursor" -->
254
+ <dl>
255
+ <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" -->
256
+ <dd>
257
+ <p>explicitly indicate the date type of fetched value. run this
258
+ method within parse and exec. pos starts from 1. lentgh is used
259
+ when type is String.</p>
260
+ <p>example:</p>
261
+ <pre>cursor = conn.parse("SELECT ename, hiredate FROM emp")
262
+ cursor.define(1, String, 20) # fetch the first column as String.
263
+ cursor.define(2, Time) # fetch the second column as Time.
264
+ cursor.exec()</pre></dd>
265
+ <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" -->
266
+ <dd>
267
+ <p>Binds variables explicitly.</p>
268
+ <p>When key is number, it binds by position, which starts from 1.
269
+ When key is string, it binds by the name of placeholder.</p>
270
+ <p>example:</p>
271
+ <pre>cursor = conn.parse("SELECT * FROM emp WHERE ename = :ename")
272
+ cursor.bind_param(1, 'SMITH') # bind by position
273
+ ...or...
274
+ cursor.bind_param(':ename', 'SMITH') # bind by name</pre>
275
+ <p>To bind as number, Fixnum and Float are available, but Bignum is
276
+ not supported. If its initial value is NULL, please set nil to
277
+ <var>type</var> and Fixnum or Float to <var>val</var>.</p>
278
+ <p>example:</p>
279
+ <pre>cursor.bind_param(1, 1234) # bind as Fixnum, Initial value is 1234.
280
+ cursor.bind_param(1, 1234.0) # bind as Float, Initial value is 1234.0.
281
+ cursor.bind_param(1, nil, Fixnum) # bind as Fixnum, Initial value is NULL.
282
+ cursor.bind_param(1, nil, Float) # bind as Float, Initial value is NULL.</pre>
283
+ <p>In case of binding a string, set the string itself to
284
+ <var>val</var>. When the bind variable is used as output, set the
285
+ string whose length is enough to store or set the length.</p>
286
+ <p>example:</p>
287
+ <pre>cursor = conn.parse("BEGIN :out := :in || '_OUT'; END;")
288
+ cursor.bind_param(':in', 'DATA') # bind as String with width 4.
289
+ cursor.bind_param(':out', nil, String, 7) # bind as String with width 7.
290
+ cursor.exec()
291
+ p cursor[':out'] # =&gt; 'DATA_OU'
292
+ # Though the length of :out is 8 bytes in PL/SQL block, it is
293
+ # bound as 7 bytes. So result is cut off at 7 byte.</pre>
294
+ <p>In case of binding a string as RAW, set OCI::RAW to <var>type</var>.</p>
295
+ <p>example:</p>
296
+ <pre>cursor = conn.parse("INSERT INTO raw_table(raw_column) VALUE (:1)")
297
+ cursor.bind_param(1, 'RAW_STRING', OCI8::RAW)
298
+ cursor.exec()
299
+ cursor.close()</pre></dd>
300
+ <dt><a name="label-24" id="label-24"><code>OCI8::Cursor#[<var>key</var>]</code></a></dt><!-- RDLabel: "OCI8::Cursor#[]" -->
301
+ <dd>
302
+ <p>Gets the value of the bind variable.</p>
303
+ <p>In case of binding explicitly, use same key with that of
304
+ <a href="#label-23">OCI8::Cursor#bind_param</a>. A placeholder can be bound by
305
+ name or position. If you bind by name, use that name. If you bind
306
+ by position, use the position.</p>
307
+ <p>example:</p>
308
+ <pre>cursor = conn.parse("BEGIN :out := 'BAR'; END;")
309
+ cursor.bind_param(':out', 'FOO') # bind by name
310
+ p cursor[':out'] # =&gt; 'FOO'
311
+ p cursor[1] # =&gt; nil
312
+ cursor.exec()
313
+ p cursor[':out'] # =&gt; 'BAR'
314
+ p cursor[1] # =&gt; nil</pre>
315
+ <p>example:</p>
316
+ <pre>cursor = conn.parse("BEGIN :out := 'BAR'; END;")
317
+ cursor.bind_param(1, 'FOO') # bind by position
318
+ p cursor[':out'] # =&gt; nil
319
+ p cursor[1] # =&gt; 'FOO'
320
+ cursor.exec()
321
+ p cursor[':out'] # =&gt; nil
322
+ p cursor[1] # =&gt; 'BAR'</pre>
323
+ <p>In case of binding by <a href="#label-11">OCI8#exec</a> or <a href="#label-27">OCI8::Cursor#exec</a>,
324
+ get the value by position, which starts from 1.</p>
325
+ <p>example:</p>
326
+ <pre>cursor = conn.exec("BEGIN :out := 'BAR'; END;", 'FOO')
327
+ # 1st bind variable is bound as String with width 3. Its initial value is 'FOO'
328
+ # After execute, the value become 'BAR'.
329
+ p cursor[1] # =&gt; 'BAR'</pre></dd>
330
+ <dt><a name="label-25" id="label-25"><code>OCI8::Cursor#[<var>key</var>] = <var>val</var></code></a></dt><!-- RDLabel: "OCI8::Cursor#[]=" -->
331
+ <dd>
332
+ <p>Sets the value to the bind variable. The way to specify the
333
+ <var>key</var> is same with <a href="#label-24">OCI8::Cursor#[]</a>. This is available
334
+ to replace the value and execute many times.</p>
335
+ <p>example1:</p>
336
+ <pre>cursor = conn.parse("INSERT INTO test(col1) VALUES(:1)")
337
+ cursor.bind_params(1, nil, String, 3)
338
+ ['FOO', 'BAR', 'BAZ'].each do |key|
339
+ cursor[1] = key
340
+ cursor.exec
341
+ end
342
+ cursor.close()</pre>
343
+ <p>example2:</p>
344
+ <pre>['FOO', 'BAR', 'BAZ'].each do |key|
345
+ conn.exec("INSERT INTO test(col1) VALUES(:1)", key)
346
+ end</pre>
347
+ <p>Both example's results are same. But the former will use less resources.</p></dd>
348
+ <dt><a name="label-26" id="label-26"><code>OCI8::Cursor#keys()</code></a></dt><!-- RDLabel: "OCI8::Cursor#keys" -->
349
+ <dd>
350
+ Returns the keys of bind variables as array.</dd>
351
+ <dt><a name="label-27" id="label-27"><code>OCI8::Cursor#exec(*<var>bindvars</var>)</code></a></dt><!-- RDLabel: "OCI8::Cursor#exec" -->
352
+ <dd>
353
+ <p>Executes the SQL statement assigned the cursor. The type of
354
+ return value depends on the type of sql statement: select;
355
+ insert, update and delete; create, alter, drop and PL/SQL.</p>
356
+ <p>In case of select statement, it returns the number of the
357
+ select-list.</p>
358
+ <p>In case of insert, update or delete statement, it returns the
359
+ number of processed rows.</p>
360
+ <p>In case of create, alter, drop and PL/SQL statement, it returns
361
+ true. In contrast with <a href="#label-11">OCI8#exec</a>, it returns true even
362
+ though PL/SQL. Use <a href="#label-24">OCI8::Cursor#[]</a> explicitly to get bind
363
+ variables.</p></dd>
364
+ <dt><a name="label-28" id="label-28"><code>OCI8::Cursor#type</code></a></dt><!-- RDLabel: "OCI8::Cursor#type" -->
365
+ <dd>
366
+ <p>gets the type of SQL statement. Its value is one of the follows.</p>
367
+ <ul>
368
+ <li>OCI8::STMT_SELECT</li>
369
+ <li>OCI8::STMT_UPDATE</li>
370
+ <li>OCI8::STMT_DELETE</li>
371
+ <li>OCI8::STMT_INSERT</li>
372
+ <li>OCI8::STMT_CREATE</li>
373
+ <li>OCI8::STMT_DROP</li>
374
+ <li>OCI8::STMT_ALTER</li>
375
+ <li>OCI8::STMT_BEGIN</li>
376
+ <li>OCI8::STMT_DECLARE</li>
377
+ </ul>
378
+ <p>For PL/SQL statement, it returns OCI8::STMT_BEGIN or
379
+ OCI8::STMT_DECLARE.</p></dd>
380
+ <dt><a name="label-29" id="label-29"><code>OCI8::Cursor#row_count</code></a></dt><!-- RDLabel: "OCI8::Cursor#row_count" -->
381
+ <dd>
382
+ Returns the number of processed rows.</dd>
383
+ <dt><a name="label-30" id="label-30"><code>OCI8::Cursor#get_col_names</code></a></dt><!-- RDLabel: "OCI8::Cursor#get_col_names" -->
384
+ <dd>
385
+ Gets the names of select-list as array. Please use this
386
+ method after exec.</dd>
387
+ <dt><a name="label-31" id="label-31"><code>OCI8::Cursor#getColNames</code></a></dt><!-- RDLabel: "OCI8::Cursor#getColNames" -->
388
+ <dd>
389
+ Alias of <a href="#label-30">OCI8::Cursor#get_col_names</a>.</dd>
390
+ <dt><a name="label-32" id="label-32"><code>OCI8::Cursor#fetch()</code></a></dt><!-- RDLabel: "OCI8::Cursor#fetch" -->
391
+ <dd>
392
+ <p>Gets fetched data as array. This is available for select
393
+ statement only.</p>
394
+ <p>example:</p>
395
+ <pre>conn = OCI8.new('scott', 'tiger')
396
+ cursor = conn.exec('SELECT * FROM emp')
397
+ while r = cursor.fetch()
398
+ puts r.join(',')
399
+ end
400
+ cursor.close
401
+ conn.logoff</pre></dd>
402
+ <dt><a name="label-33" id="label-33"><code>OCI8::Cursor#close()</code></a></dt><!-- RDLabel: "OCI8::Cursor#close" -->
403
+ <dd>
404
+ close the cursor.</dd>
405
+ <dt><a name="label-34" id="label-34"><code>OCI8::Cursor#rowid()</code></a></dt><!-- RDLabel: "OCI8::Cursor#rowid" -->
406
+ <dd>
407
+ get the rowid of the last processed row.
408
+ This value is available as bind data.
409
+ On the other hand it isn't available for other purpose.</dd>
410
+ </dl>
411
+ <h2><a name="label-35" id="label-35">OCI8::BLOB</a></h2><!-- RDLabel: "OCI8::BLOB" -->
412
+ <dl>
413
+ <dt><a name="label-36" id="label-36"><code>OCI8::BLOB#available?</code></a></dt><!-- RDLabel: "OCI8::BLOB#available?" -->
414
+ <dd>
415
+ <p>check whether BLOB is available or not.
416
+ To use BLOB you need to insert EMPTY_BLOB() at first.</p>
417
+ <p>example:</p>
418
+ <pre>conn.exec("CREATE TABLE photo (name VARCHAR2(50), image BLOB)")
419
+ conn.exec("INSERT INTO photo VALUES ('null-data', NULL)")
420
+ conn.exec("INSERT INTO photo VALUES ('empty-data', EMPTY_BLOB())")
421
+ conn.exec("SELECT name, image FROM photo") do |name, image|
422
+ case name
423
+ when 'null-data'
424
+ puts "#{name} =&gt; #{image.available?.to_s}"
425
+ # =&gt; false
426
+ when 'empty-data'
427
+ puts "#{name} =&gt; #{image.available?.to_s}"
428
+ # =&gt; true
429
+ end
430
+ end</pre></dd>
431
+ <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" -->
432
+ <dd>
433
+ <p>read at most size bytes from BLOB, or to the end of file if size is omitted.</p>
434
+ <p>example: read chunks of chunk size.</p>
435
+ <pre>conn.exec("SELECT name, image FROM photo") do |name, image|
436
+ chunk_size = image.chunk_size
437
+ File.open(name, 'w') do |f|
438
+ until image.eof?
439
+ f.write(image.read(chunk_size))
440
+ end
441
+ end
442
+ end</pre>
443
+ <p>example: read at once.</p>
444
+ <pre>conn.exec("SELECT name, image FROM photo") do |name, image|
445
+ File.open(name, 'w') do |f|
446
+ f.write(image.read)
447
+ end
448
+ end</pre></dd>
449
+ <dt><a name="label-38" id="label-38"><code>OCI8::BLOB#write(<var>string</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#write" -->
450
+ <dd>
451
+ <p>write the given string to BLOB.
452
+ If old data is longer than new data, resize by <a href="#label-40">OCI8::BLOB#size=</a>.</p>
453
+ <p>example: write chunks of chunk size.</p>
454
+ <pre>cursor = conn.parse("INSERT INTO photo VALUES(:name, EMPTY_BLOB())")
455
+ Dir["*.png"].each do |fname|
456
+ cursor.exec(fname)
457
+ end
458
+ conn.exec("SELECT name, image FROM photo") do |name, image|
459
+ chunk_size = image.chunk_size
460
+ File.open(name, 'r') do |f|
461
+ until f.eof?
462
+ image.write(f.read(chunk_size))
463
+ end
464
+ image.size = f.pos
465
+ end
466
+ end
467
+ conn.commit</pre>
468
+ <p>example: write at once.</p>
469
+ <pre>conn.exec("SELECT name, image FROM photo") do |name, image|
470
+ File.open(name, 'r') do |f|
471
+ image.write(f.read)
472
+ image.size = f.pos
473
+ end
474
+ end</pre></dd>
475
+ <dt><a name="label-39" id="label-39"><code>OCI8::BLOB#size</code></a></dt><!-- RDLabel: "OCI8::BLOB#size" -->
476
+ <dd>
477
+ return the size of BLOB.</dd>
478
+ <dt><a name="label-40" id="label-40"><code>OCI8::BLOB#size=(<var>len</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#size=" -->
479
+ <dd>
480
+ set the size of BLOB.</dd>
481
+ <dt><a name="label-41" id="label-41"><code>OCI8::BLOB#chunk_size</code></a></dt><!-- RDLabel: "OCI8::BLOB#chunk_size" -->
482
+ <dd>
483
+ return the chunk size of BLOB.</dd>
484
+ <dt><a name="label-42" id="label-42"><code>OCI8::BLOB#truncate(<var>len</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#truncate" -->
485
+ <dd>
486
+ set the size of BLOB.</dd>
487
+ <dt><a name="label-43" id="label-43"><code>OCI8::BLOB#pos</code></a></dt><!-- RDLabel: "OCI8::BLOB#pos" -->
488
+ <dd>
489
+ return the current offset of BLOB.</dd>
490
+ <dt><a name="label-44" id="label-44"><code>OCI8::BLOB#pos=(<var>pos</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#pos=" -->
491
+ <dd>
492
+ set the current offset of BLOB.</dd>
493
+ <dt><a name="label-45" id="label-45"><code>OCI8::BLOB#eof?</code></a></dt><!-- RDLabel: "OCI8::BLOB#eof?" -->
494
+ <dd>
495
+ return true if BLOB is at end of file</dd>
496
+ <dt><a name="label-46" id="label-46"><code>OCI8::BLOB#tell</code></a></dt><!-- RDLabel: "OCI8::BLOB#tell" -->
497
+ <dd>
498
+ Synonym for <a href="#label-43">OCI8::BLOB#pos</a>.</dd>
499
+ <dt><a name="label-47" id="label-47"><code>OCI8::BLOB#seek(<var>pos</var>)</code></a></dt><!-- RDLabel: "OCI8::BLOB#seek" -->
500
+ <dd>
501
+ Synonym for <a href="#label-44">OCI8::BLOB#pos=</a>.</dd>
502
+ <dt><a name="label-48" id="label-48"><code>OCI8::BLOB#rewind</code></a></dt><!-- RDLabel: "OCI8::BLOB#rewind" -->
503
+ <dd>
504
+ set the current offset to zero.</dd>
505
+ </dl>
506
+ <h2><a name="label-49" id="label-49">Appendix</a></h2><!-- RDLabel: "Appendix" -->
507
+ <h3><a name="label-50" id="label-50">Blocking/Non-Blocking Mode</a></h3><!-- RDLabel: "Blocking/Non-Blocking Mode" -->
508
+ <p>The default mode is blocking mode. You can change the mode by
509
+ <a href="#label-19">OCI8#non_blocking=</a>.</p>
510
+ <p>When the mode is blocking, heavy OCI calls will block the process
511
+ itself even though multithread application because ruby's thread is
512
+ not native one.</p>
513
+ <p>when the mode is non-blocking, heavy OCI calls will not block the
514
+ process, but block the thread only. Instead of the merit, each OCI
515
+ call become a bit slower because it polls many times whether the OCI
516
+ call is finished or not.</p>
517
+ <p>You can cancel a OCI call by using <a href="#label-20">OCI8#break</a> from other thread.
518
+ The canceled OCI call raises <var>OCIBreak</var> exception.</p>
519
+ <p>Restriction of non-blocking mode: Don't do OCI calls at the same time
520
+ for a same connection.</p>
521
+ <hr />
522
+ <p class="foottext">
523
+ <a name="foottext-1" id="foottext-1" href="#footmark-1"><sup><small>*1</small></sup></a><small>Oracle
524
+ Call Interface</small><br />
525
+ </p>
526
+ </body>
527
+ </html>