Oracle7 用拡張モジュール version 0.2.11 吉田正人 - 概要 本モジュールは，Rubyから Oracle 7 にアクセスするための拡張モ ジュールです。Oracle8 でもほとんどの機能は動作します。 Oracle の機能のうち，個人的に使う範囲の機能しか実装していま せん。 Solaris2 用の Oracle 7.3.3, 8.0.4，Linux 用 8.0.5 (試用版)， WindowsNT 用 8.0.5 で動作確認しています。 Linux 用 Oracle8i での動作報告もありました。 - インストール Ruby-1.4 以降でしか動作確認されていません。Ruby-1.6.1 以降の 使用をおすすめします。Oracle Call Interface (OCI) がインストー ルされている必要があります。 extconf.rb を適当に編集してから，通常のモジュールインストー ルを行ってください。動的リンクに対応している場合は以下の通り です。 ruby extconf.rb make make site-install VisualC++ でコンパイルする場合 extconf.rb を適当に書き換えて，環境変数を set INCLUDE=c:\orant\OCI80\INCLUDE;%INCLUDE% set LIB=c:\orant\OCI80\LIB\MSVC;%LIB% のように設定してください。そして win32 ディレクトリで ntsetup.bat を実行したあと，Makefile の LIBS に OCI.LIB 追加， ext\Setup に oracle を追加し，nmake してください。 CYGWIN の場合 以下のように DLL から インポートライブラリを作成し， extconf.rb を適当に変更してコンパイルしてみてください。 Oracle8 の場合 dlltool -d OCI.def -D $ORACLE_HOME/BIN/OCI.DLL -l libOCI.a Oracle7.3 の場合 dlltool -d OCI73.def -D $ORACLE_HOME/BIN/ORA73.DLL -l libOCI.a - 使い方 まず， require "oracle" としてモジュールをロードしてから使用してください。 API として OCI の機能に近い下位 API とより簡単に扱える上位 API を用意しています。 ・上位 API 上位 API は検索をなるべく簡単に行なうため，データ領域を自 動的に確保し，データ型もある程度自動的に認識します。 Oracle クラス 特異メソッド new(uid=nil, pswd=nil, conn=nil) Oracle に接続します。uid でユーザ ID，pswd でパスワー ド，conn で SQL*Net の接続文字列を指定します。 接続に成功すると Oracle オブジェクトを返します。接続 に失敗すると例外が発生します。 Pro*C を使って既に接続済みの場合，全ての引数を省略し て接続を得ることができます。Pro*C で記述されたコード と混在している場合に便利かも知れません。 Oracle::Binary(str) Oracle#exec メソッドで bindvars 引数を LONG RAW 型 データとして束縛したいときに使います。 Oracle::RawData クラスのインスタンスを返します。 samples/lotest.rb を参考にして下さい。 メソッド logoff 切断します。コミットされていないトランザクションをロー ルバックします。 Pro*C と混在する場合，Pro*C 側で切断するべきです。 exec(sql, *bindvars) SQL を実行します。 SQL が実行結果を返す場合，fetch メソッドで取り出して 下さい。 bindvars が指定された場合，それぞれの文字列を sql 内 の SQL 変数 :0, :1, :2, ... に束縛してから実行します。 LONG RAW 型データに束縛するときは Oracle::Binary(str) でデータ型を指定して下さい。 成功すると Cursor オブジェクトを返します。エラーがあ る場合は例外が発生します。 イテレータとして呼び出すこともできます。ブロックパラ メータは fetch された値の配列です。 parse(sql) Parse and prepare a SQL statement and return the cursor connected to it. If you want to execute this statement you have first to Cursor#bind values to them, or pass the values during the call to Cursor#exec commit トランザクションをコミットします。 rollback トランザクションをロールバックします。 autocommit オートコミットするかどうか調べます。 autocommit=(mode) オートコミットモード (true または false) を設定します。 Oracle::Cursor クラス メソッド initialize(conn, sql=nil, *bindvars) Initialize the new ORAcursor instance. If a SQL statement was given, the statement will be parsed/prepared. The values contained in *bindvars will be bound to the ORAcursor instance and ORAcursor#exec will be invoked. However, if there was no SQL statement given, no preparation or execution takes place. parse(sql) Parse and prepare a SQL statement and connect it with the current Cursor instance (and therefore with the underlying ORAcursor instance). bind(*bindvars) Binds the values of *bindvars to the internal ORAcursor instance. Necessary before you call Cursor#exec. But you may pass the *bindvars also to Cursor#exec instead. exec(*bindvars) Binds the values of *bindvars to the internal ORAcursor and executes the statement. You may fetch the rows with Cursor#fetch afterwards. getColNames SQL が実行結果を返すとき，列名の配列を得ることができ ます。 getDWidth SQL が実行結果を返すとき，列の表示長の配列を得ること ができます。 fetch SQL が実行結果を返すとき，行を配列で取り出すことがで きます。全ての行を取り出すと nil を返します。 イテレータとして呼び出した場合は行をブロックパラメー タとして yield します。 NUMBER 型は，整数精度だった場合は整数 (Fixnum か Bignum)，そうでなければ実数型 (Float) で返します。そ れ以外のデータ型は文字列型 (String) で返します。 close カーソルを閉じます。場合によってはかなりのメモリを使っ ている可能性もあるので，使い終わったら閉じて下さい。 ・下位 API よりきめ細かな制御をするための API です。ただし，個人的に 使わない引数が決め打ちになっていたりします。 ORAconn クラス 特異メソッド new(uid, pswd=nil, conn=nil) logon(uid, pswd=nil, conn=nil) Oracle に接続します。uid でユーザ ID，pswd でパスワー ド，conn で SQL*Net の接続文字列を指定します。 uid だけ "user/passwd@seavice" のように指定して， paswd, conn を省略してもかまいません。 接続に成功すると ORAconn オブジェクトを返します。接続 に失敗すると例外が発生します。 getConnection Pro*C を使って既に接続済みの場合，その接続を得ること ができます。Pro*C で記述されたコードと混在している場 合に便利かも知れません。 接続が得られると ORAconn オブジェクトを返します。接続 が得られないと例外が発生します。 メソッド disconnect logoff 切断します。 open カーソルを作成します。成功すると ORAcursor オブジェ クトを返します。 commit トランザクションをコミットします。 rollback トランザクションをロールバックします。 nbset 非ブロックモードにします。 nbclear ブロックモードにします。 nbtest 現在，非ブロックモードならば true, ブロックモードな らば false を返します。 break 実行中の SQL を中断します。 commiton オートコミットを有効にします。 commitoff オートコミットを無効にします。 ORAcursor クラス メソッド close カーソルを閉じます。 parse(sql) sql をパースします。 describe(pos) 指定位置のカラムの情報を得ます。 pos は 1 以上です。 戻値は [DB 内サイズ, データ型, カラム名, 表示サイズ, 精度, スケール, NULLを許すか] です。 define(pos, buflen, datatype) 指定位置のデータサイズとデータ型を指定して，fetch 用 のバッファを用意します。 pos は 1 以上です。buflen は 65535 までです。 データ型は以下の整数を使って下さい。 VARCHAR2 = 1 NUMBER = 2 INTEGER = 3 FLOAT = 4 LONG = 8 ROWID = 11 DATE = 12 RAW = 23 LONG_RAW = 24 UNSIGNED_INT = 68 CHAR = 96 MLSLABEL = 105 INTEGER, UNSIGNED_INT, FLOAT の時は指定されたデータ サイズを無視して，処理系の int または double 型のサ イズを使います。 VARCHAR2 などは取り出しエンコーディングによっては， describe で得られる DB 内サイズよりも大きくなること があるので，バッファサイズを大きめに指定して下さい。 LONG, LONG RAW は describe では DB 内サイズが分から ないので，適当なバッファサイズ (65535 バイト推奨) を 指定して下さい。バッファサイズに関わらずフルサイズで 取り出します。 exec parse で指定した SQL を実行します。DML の場合，実行 した行数を返します。 fetch exec の結果を一行取り出します。取り出し済み行数を返 します。データの終わりに達したときは nil を返します。 取り出したデータは内部的なバッファに格納されているの で getCol で取得して下さい。 cancel fetch を中断します。 bindrv(var, progv, ftype = CHAR) SQL 変数にオブジェクトを束縛します。var は ':' で始 まる SQL 変数名，progv は文字列を指定して下さい。 ftype でデータ型を指定します。define と同様に整数で指 定して下さい。省略時は CHAR です。 progv は exec を呼び出す時に参照/更新されます。 値を受け取るときは十分な長さの文字列変数を指定して下 さい。 変数に文字列を代入するとオブジェクトのアドレスが変わっ てしまうので，exec の前に束縛し直して下さい。 getCol(index) fetch で取り出したデータを取得します。 index は 1 以上です。 戻値は [データ，インジケータ，エラーコード]です。 define でデータ型として INTEGER, UNSIGNED を指定した 場合は整数型，FLOAT を指定した場合は実数，それ以外は 文字列で返します。NULL は nil を返します。 getROWID SQL を実行した時の ROWID を返します。機種依存領域の データを参照しているので，正しい値を返すとは限りませ ん。 Oracle8 では正しい値を返しません。 - バグ DB 内文字コードと取り出し文字コードが一致しない場合，64K バ イトを越える LONG 型データが正しく取り出せません (取り出し済 データサイズから DB 内データのオフセットが予想できないため)。 LONG RAW 型は文字コード変換されないので大丈夫です。 - 権利 本拡張モジュールの著作権は吉田正人が保持します。 本拡張モジュールは，Ruby 本体のライセンスにしたがって利用す ることができます。 - 作者 吉田正人 - 履歴 Dec 23, 2000 version 0.2.11 Oracle#exec のイテレータ対応 Dec 21, 2000 version 0.2.10 オートコミット対応 Nov 19, 2000 version 0.2.9 Clemens Hintze 氏による Oracle::Cursor の拡張を取り込みました。 Dec 15, 1999 version 0.2.8 バッファが小さいときに 65534 バイ ト未満の LONG データが一部しか取 り出せない問題を修正 Dec 14, 1999 version 0.2.7 32K バイト以上の LONG データを fetch できないバグを修正 64K バイトを越える LONG, LONG RAW データに対応 Oct 10, 1999 veriosn 0.2.6 ドキュメントのみ変更 Jul 1, 1999 version 0.2.5 Oracle#exec で第二引数以降の値を SQL 変数 :0, :1, :2, ... に束縛する ようにした。 Jun 29, 1999 version 0.2.4 Oracle::Cursor#exec で，データの 出力エンコーディングによっては (例えば japanese_japan.utf8 など) 出力長が足りないので，VARCHAR2, CHAR の場合は 1.5 倍とした Jun 8, 1999 version 0.2.3 Oracle::Cursor#fetch で NUMBER 型 データの整数対応 Apr 22, 1999 version 0.2.2 WindowNT で動作確認 Apr 13, 1999 version 0.2.1 Ruby 1.3 対応 Nov 17, 1998 version 0.2 OCI 関数追加 Sep 21, 1998 version 0.1 最初のリリース