OCI8::Cursor

このクラスのインスタンスはオラクルの用語ではカーソルに対応します。JDBC の java.sql.Statement, Perl/DBI の statement handle: $sth に対応します。

このクラスのインスタンスは new により生成しないでください。必ず OCI8#exec, OCI8#parse 経由で生成してください。

define(pos, type, length = nil)

fetch で取得するデータの型を明示的に指定する。parse と exec の間 に実行してください。pos は 1 から数えます。length は type に String を指定したときに有効です。

 cursor = conn.parse("SELECT ename, hiredate FROM emp")
 cursor.define(1, String, 20) # 1カラム目を String として fetch
 cursor.define(2, Time)       # 2カラム目を Time として fetch
 cursor.exec()

bind_param(key, val, type = nil, length = nil)

明示的に変数をバインドします。

key が数値の場合は、バインド変数の位置によってバインドします。位 置は1から数えます。key が文字列の場合は、バインド変数の名前によっ てバインドします。

 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

数値をバインドする場合、Integer か Fixnum か Float が使ってください。Bignum は使用できません。初期値を NULL にする場合は、val を nil にして、 type をFixnum か Float にしてください。

 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.

文字列をバインドする場合、val にそのままバインドする文字を指定し てください。バインドが出力として使われる場合、出力するのに必要な 長さの文字を指定するか、type に String を指定した上で length を指 定してください。

 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'] # => 'DATA_OU'
 # PL/SQLブロック内での :out は 8バイトだが、幅7の文字としてバインド
 # してあるので、7バイト目で切れている

文字列を RAW 型としてバインドする場合は必ず type に OCI8::RAW を 指定してください。

 cursor = conn.parse("INSERT INTO raw_table(raw_column) VALUE (:1)")
 cursor.bind_param(1, 'RAW_STRING', OCI8::RAW)
 cursor.exec()
 cursor.close()

[key]

バインド変数の値を取り出します。

明示的にバインドした場合、#bind_param で指定した key でもって取り出します。 名前でバインドしたときは名前を使用し、位置でバインドしたときは位置を使用 してください。

 cursor = conn.parse("BEGIN :out := 'BAR'; END;")
 cursor.bind_param(':out', 'FOO') # 名前でバインド
 p cursor[':out'] # => 'FOO'
 p cursor[1] # => nil
 cursor.exec()
 p cursor[':out'] # => 'BAR'
 p cursor[1] # => nil

 cursor = conn.parse("BEGIN :out := 'BAR'; END;")
 cursor.bind_param(1, 'FOO') # 位置でバインド
 p cursor[':out'] # => nil
 p cursor[1] # => 'FOO'
 cursor.exec()
 p cursor[':out'] # => nil
 p cursor[1] # => 'BAR'

OCI8#exec、OCI8::Cursor#exec を使用してバインドした場合、 バインド変数の位置でもって取得します。バインド位置は1から数えます。

 cursor = conn.exec("BEGIN :out := 'BAR'; END;", 'FOO')
 # 一番目のバインド変数は、長さ3の String としてバインドされ、初期値は 'FOO' です。
 # 実行後、バインド変数の値は 'BAR' となります。
 p cursor[1] # => 'BAR'

[key] = val

バインド変数に値を設定します。key の指定方法は OCI8::Cursor#[]と同じです。バインド変数の値を何回も変更&実行するとき に使用してください。

 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()

 ['FOO', 'BAR', 'BAZ'].each do |key|
   conn.exec("INSERT INTO test(col1) VALUES(:1)", key)
 end

両方とも結果は同じですが、前者のほうが負荷が少なくなります。

keys

バインド変数の key を配列にして返します。

exec(*bindvars)

カーソルに割当てられた SQL を実行します。SQL が SELECT文、 INSERT/UPDATE/DELETE文、CREATE/ALTER/DROP文とPL/SQL文、それぞれ場 合で戻り値の種類が異なります。

SELECT文の場合、select-list の数が返ります。

INSERT/UPDATE/DELETE文の場合、それぞれ処理した行数が返ります。

CREATE/ALTER/DROP文とPL/SQL文の場合、true が返ります。 OCI8#exec では PL/SQL文の場合、バインド変数の値が配列となって 返りますが、このメソッドでは単に true が返ります。バインド変数の 値は OCI8::Cursor#[] でもって明示的に取得してください。

type

QL文の種類を取得します。戻り値は以下のとおりです。

• OCI8::STMT_SELECT
• OCI8::STMT_UPDATE
• OCI8::STMT_DELETE
• OCI8::STMT_INSERT
• OCI8::STMT_CREATE
• OCI8::STMT_DROP
• OCI8::STMT_ALTER
• OCI8::STMT_BEGIN
• OCI8::STMT_DECLARE

のどれかです。PL/SQL文の場合は、OCI8::STMT_BEGIN か OCI8::STMT_DECLARE となります。

ruby-oci8 1.0 の場合は Fixnum です。 ruby-oci8 2.0 の場合は Symbol となります。

row_count

処理した行数を返します。

get_col_names

選択リストの名前を配列で取得します。exec した後に使用してください。

column_metadata

(new in 1.0.0 without rc)

select文のカラムの情報を取得します。 OCI8#exec または OCI8::Cursor#exec を実行した 後でないと情報を取得できません。このメソッドは OCI8::Metadata::Columnの配列を戻します。

fetch

フェッチしたデータが配列として返ります。SELECT 文のみに有効です。

 conn = OCI8.new('scott', 'tiger')
 cursor = conn.exec('SELECT * FROM emp')
 while r = cursor.fetch()
   puts r.join(',')
 end
 cursor.close
 conn.logoff

fetch_hash

Hash としてデータをフェッチします。Hash のキーはカラム名です。

close

カーソルをクローズします。

rowid

現在実行している行の ROWID を取得します。 ここで得られた値はバインド値として使用できます。 逆に言うと、バインドする目的にしか使用できません。

prefetch_rows = rows

このカーソルのプリフェッチ行数を設定します。 ここで設定した値は他のカーソルには影響しません。