
			Ruby  InterBase  module



[1] 拡張ライブラリ「interbase」

　実体は「interbase.so」という名前のシェアードライブラリです。このモジュールを
Ruby のスクリプトで使う場合には、以下のように最初にインポートしておかなければ
なりません。

    require "interbase"

　Ruby インタプリタのサーチパスリスト中のディレクトリに、シェアードライブラリ
（interbase.so）を移動（または転記）しておけば、ライブラリをロードすることが
できます。ただし、シェアードライブラリ「interbase.so」の名前は、変更しないで
ください。

　このライブラリ、以下のクラス，モジュールが定義されています。

    ・InterBase モジュール
    ・InterBase::Connection クラス
    ・InterBase::Cursor クラス
    ・InterBase::Blob クラス(あるだけ)

　以下は、上記クラスのメソッドなどについて記述しています。ただし、メソッドな
どの構文中で、[] で囲まれた引数は省略可能なものを表しています。また、データタ
イプの中で | で区切られたものは、そのいずれかを選択することができることを表し
ています。

[2] InterBase モジュール

　InterBaseへのアクセスを行う機能をまとめたモジュールです．

【モジュール関数】

connect(db[,user,pass,charset])

    ・db〈String〉	接続するデータベース名
    ・user〈String〉	ユーザー名
    ・pass〈String〉	パスワード
    ・charset〈String〉	接続時のキャラクタセット（デフォルトは nil）
			EUC は EUCJ_0208、SJIS は SJIS_0208、その他は
			InterBase のマニュアルを参照してください。

    　データベースへの接続が完了すると、Connection オブジェクトを返します。
    　ユーザー名、パスワードは InterBase のセキュリティデータベースに登録されて
    いるもので、UNIXのユーザーではありません。
    　引数の中で database 以外は省略可能です。

    《例》
        con = InterBase::connect('/home/db1.gdb', 'usr1', 'ps1')

transaction([option,db...])
    ・option〈String〉	トランザクションオプション
    ・db〈Connection〉	トランザクション対象のConnection

    　引数で指定されたトランザクションオプションでトランザクションを開始させ
    ます。このメソッドを使用しなくても、Cursor オブジェクトのメソッド
    execute()を実行させた時にトランザクションが開始されていなければ、自動的に
    開始されます。このメソッドは、SQL文によるデータ操作を行う前に、明示的にト
    ランザクションを開始させたい場合に使用します。
    　オプションの書式は、InterBase の SET TRANSACTION に指定するものと全く同
    じです。
    　デフォルトのトランザクションオプションは、以下のオプションを指定した場合
    と同様のものです。

        READ WRITE NO WAIT ISOLATION LEVEL SNAPSHOT

    　トランザクション対象のConnectionが省略されると全Connectionがトランザク
    ションの対象になります。

commit

    　トランザクションをコミットします。アクティブなトランザクションが無い
    場合は、何も行いません。

rollback

    　トランザクションをロールバックします。アクティブなトランザクションが無い
    場合は、何も行いません。

[3] InterBase::Connection クラス

　接続したデータベースの情報を保持するオブジェクトのクラスです。

【クラスメソッド】

connect(db[,user,pass,charset])
open(db[,user,pass,charset])
new(db[,user,pass,charset])

   　InterBase::connectと同様にConnectionを行います。

【メソッド】

cursor
    　接続中のデータベースに対する操作を行うための、カーソルオブジェクトを返し
    ます。

execute(sql[,arg...])
    ・sql〈String〉	実行させる SQL 文
    ・arg〈any〉	上記 SQL 文に渡すパラメータ

    　引数で指定された SQL 文を実行させます。
    　実行させた SQL 文の種類によって、以下の戻り値を返します。

        ・データ定義文（DDL）の場合は nil
        ・非問い合わせ文（INSERT、UPDATE、DELETE など）の場合は nil
        ・問い合わせ文（SELECT）の場合は Cusorオブジェクト

    　詳細は InterBase::Cursor#execute を参照してください。

transaction([option])
    ・option〈String〉	トランザクションオプション

    　引数で指定されたトランザクションオプションでトランザクションを開始させ
    ます。このメソッドを使用しなくても、Cursor オブジェクトのメソッド
    execute()を実行させた時にトランザクションが開始されていなければ、自動的に
    開始されます。このメソッドは、SQL文によるデータ操作を行う前に、明示的にト
    ランザクションを開始させたい場合に使用します。
    　オプションの書式は、InterBase の SET TRANSACTION に指定するものと全く同
    じです。
    　デフォルトのトランザクションオプションは、以下のオプションを指定した場合
    と同様のものです。

        READ WRITE NO WAIT ISOLATION LEVEL SNAPSHOT

commit
    　トランザクションをコミットします。アクティブなトランザクションが無い
    場合は、何も行いません。
rollback
    　トランザクションをロールバックします。アクティブなトランザクションが無い
    場合は、何も行いません。
close
    　データベースとの接続を解除します。アクティブなトランザクションが有る
    場合は、ロールバックします。

[4] InterBase::Cursor

　接続中のデータベースに対するデータ操作を行うためのオブジェクトで、問合せに
対する結果へのポインタなどを保持します。

【注意】配列型のフィールドへのアクセスはサポートしていません。

【メソッド】

execute(sql[,arg...])
	sql <String>		SQL statement
	arg <any>		Argument to the above SQL statement

    ・sql〈String〉	実行させる SQL 文
    ・arg...		上記 SQL 文に渡すパラメータ

    　引数で指定された SQL 文を実行させます。
    　実行させた SQL 文の種類によって、以下の戻り値を返します。

        ・データ定義文（DDL）の場合は 1
        ・非問い合わせ文（INSERT、UPDATE、DELETE など）の場合は 0
        ・問い合わせ文（SELECT）の場合は nil

    　SQL 文にパラメータを渡す場合は、SQL 文中のパラメータに置き換えたい位置に
    「?」を記述し、引数として「?」を置き換えるデータを指定します。
    

    《例》
        execute('select * from table1 where field1=?', 10)
        execute('select * from table1 where field1=? and field2=?',
		10, 'text1')
        execute('insert into table1( field1, field2 ) values( ?, ? )',
		10, 'text1')

    　また、引数として nil を指定すると、該当するフィールド
    は NULL に設定されます。（ただし、フィールドの属性に NOT NULL が定義されて
    いる場合はエラーとなります。）

    《例》
        execute('insert into table1( field1, field2 ) values( ?, ? )',
		nil, nil)

    　さらに、SQL文が非問合せ文（INSERT、UPDATE など）の場合は、置き換えるデータ
    を構成要素とする配列を指定することにより、複数の SQL 文（パラメータのみ異な
    るもの）を一度の呼び出しで実行させることができます。

    《例》
        execute('insert into table1(field1, field2) values(?, ?)',
                [10, 'text1'], [20, 'text2'], [30, 'text3'],
                [40, 'text4'], [50, 'text5'])
            （5レコード文の insert が行われます。）

        【注意】配列と非配列の引数を混在させることは出来ません。

    　パラメータとして指定するデータのオブジェクトタイプは、データベースのデータ
    タイプに対応して、それぞれ以下のものを使用することができます。（先頭に記述し
    たオブジェクトタイプが推奨するタイプです。）
        ┌───────────┬───────────┐
        │DB data type          │Ruby object type      │
        ├───────────┼───────────┤
        │CHAR                  │String, Integer, Float│
        │VARCHAR               │String, Integer, Float│
        │SMALLINT              │Integer, Float, String│
        │INTEGER               │Integer, Float, String│
        │FLOAT                 │Float, Integer, String│
        │DOUBLE PRECISION      │Float, Integer, String│
        │DATE                  │Time                  │
        │BLOB                  │Blob, String          │
        └───────────┴───────────┘

description

    　メソッド execute() により問合せ文（select 文）を実行させた時に、データを
    取り出そうとするフィールドの情報（フィールド名、データタイプなど）が格納され
    ます。
    　この属性は、取り出そうとするフィールド数分のフィールド情報を構成要素と
    するタプルです。各フィールド情報は、さらに以下の7つの項目で構成されるタプル
    です。

        ・name〈String〉	フィールド名
        ・type_code〈Int〉	データタイプを表すコード
					CHAR			452
					VARCHAR			448
					SMALLINT		500
					INTEGER			496
					FLOAT			482
					DOUBLE PRECISION	480
					DATE			510
					BLOB			520
        ・display_size〈Int〉	データサイズ（バイト数）
        ・internal_size〈Int〉	内部的なデータサイズ（バイト数）
				（VARCHAR 以外の時は display_size と同じ）
        ・precision〈Int〉		精度（現在未使用、常に0）
        ・scale〈Int〉		スケール値
        ・null_ok〈Int〉	NULL が許可されているか否か（true：許可、false：禁止）

    　初期状態、および execute() により非問合せ文が実行された場合は、この属性は
    nil になっています。

fetch
    　execute() で実行させた問合せ文（SELECT 文）の結果を1レコード分取り出し、
    レコード内のフィールドのデータを構成要素とする配列を返します。また、配列
    内のフィールドのデータは、フィールドのデータタイプに対応して、それぞれ以下の
    タイプのオブジェクトとして返します。
        ┌───────────┬───────────┐
        │DB data type          │Ruby object type      │
        ├───────────┼───────────┤
        │CHAR                  │String                │
        │VARCHAR               │String                │
        │SMALLINT              │Integer               │
        │INTEGER               │Integer               │
        │FLOAT                 │Float                 │
        │DOUBLE PRECISION      │Float                 │
        │DATE                  │Time                  │
        │BLOB                  │Blob                  │
        └───────────┴───────────┘
    　このメソッドを繰り返し呼び出すことにより、問合せの結果を順次取り出すこと
    ができます。結果を全て取り出した後に、このメソッドが呼び出された場合は nil
    を返します。

fetchall
    　execute() で実行させた問合せ文（select 文）の結果を全て取り出します。取り
    出した結果は、各レコードが前記 fetchone() と同様の配列で、それらレコード数
    分の配列を構成要素とする配列で返します。

each{|record|...}
    　execute() で実行させた問合せ文（select 文）の結果に対して繰り返します。

close
    　カーソルをクローズします。
    　execute() により問合せ文を実行させ、結果を全て取得せず別の SQL 文を
    execute() により実行させた場合は、自動的に前の問合せの結果を指すカーソルは
    クローズされます。

drop
    　カーソルを廃棄します。

[5] InterBase::Blob

　接続中のデータベースの BLOb フィールドへのデータの入出力を行うためのオブジェ
クトで、BLOb の属性と BLOb データを保持します..のはずですが，未対応です。

[6] エラー処理

　interbasedb モジュールは、データベースの操作においてエラーが発生した場合には、
例外「InterBase::Error」をあげます。
