Firebird用DBI/DBDのリファレンスのソース

--[[プログラミングガイド]]~


*Firebird用DBI/DBDのリファレンス [#u80a5b56]
　Perlモジュールの DBD::ＩｎｔｅｒＢａｓｅ は、
Firebird & ＩｎｔｅｒＢａｓｅ RDBMS サーバー用 DBI
ドライバに関するリファレンスと使い方のガイドです。
　本ドキュメントは、Version 0.43 の "DBD/ＩｎｔｅｒＢａｓｅ.pm"
を概ね基にしていますが、記述や内容を大量に追加・改変してあります。
そのため、間違いなども多々あるかもしれません。~
　''更に詳細が知りたい場合や疑わしいときは、モジュール本体の一部の "DBI/FAQ.pm" や "DBD/ＩｎｔｅｒＢａｓｅ.pm" も参照してみて下さい。''~
　もしも明確な間違いを発見した場合は指摘をお願いします。~
&br;
　ここではモジュールの取得やセットアップなどに関しては触れません。その辺り
のことは、[[Perl+DBI/DBDでFirebirdをアクセス]]を読んでください。

#contents

-Tips
--[[実質的なテーブルロック処理>#tips_tablelock]]


*基本的な使い方 [#y9e79515]
　DBIモジュールから使います。基本的には次のように使用します。

 use DBI;
 
 $dbh = DBI->connect("dbi:InterBase:db=$dbname", "sysdba", "masterkey");
 #-------- ここにクエリなどの処理が入る --------
 $dbh->disconnect();

　$dbnameはデータベース名が入っているものとします。~
　基本的にはこのような感じなのですが、SELECTなどで行を取得する場合とそうでない
場合で多少途中の処理が違います。

&aname(noselect);
**取得するデータが無い場合 [#jfb443c1]
　SQLを実行して成功・失敗などの結果を受取るだけですので、比較的単純な処理
になります。

 # モジュールの読み込み
 use DBI;
 # 接続(兼DBDのセットアップ)
 $dbh = DBI->connect("dbi:InterBase:db=$dbname", "sysdba", "masterkey");
 # SQL実行準備
 $sth = $dbh->prepare($sql_statement);
 # 実行
 $res = $sth->execute;
 # 切断
 $dbh->disconnect();

　$sql_statement は実行する SQL 文が入っているものとします。セミコロンなどの
行終端文字は不要です。~
　$dbh はデータベースハンドル、$sth はステートメントハンドル、$res,$res2は
実行結果が格納されます。
　どの返り値も、失敗時には値が FALSE となります。実際の使用時には、エラー処理
などのために使用します。


**取得するデータがある場合(SELECT等) [#u30ff1a0]
　基本的にはデータが無い場合と同じですが、データを取得するための処理が
必要となります。内容が重複している部分(変数等)に関する説明は省きますので、
上述の[[取得するデータが無い場合>#noselect]]も併読してください。~
　基本処理は、次のような形になります。

 # モジュールの読み込み
 use DBI;
 # 接続(兼DBDのセットアップ)
 $dbh = DBI->connect("dbi:InterBase:db=$dbname", "sysdba", "masterkey");
 # SQL実行準備
 $sth = $dbh->prepare($sql_statement);
 # 実行
 $res = $sth->execute();
 # 行取得ループ
 while ($result = $sth->fetch()) {
     print "$result\n";
 }
 # ステートメントハンドルクローズ(すぐに切断する場合は不要??)
 $res2 = $sth->finish();
 # 切断
 $dbh->disconnect();

　$resultには、取得したレコードが格納されます。取得するデータが無い場合は
undefが返ります。


*リファレンス [#y8609d72]
　DBIのクラスメンバに関するリファレンスです。DBD::ＩｎｔｅｒＢａｓｅ使用に即した
内容になってますので、他 DBD の場合にはまったく同じ動きになるとは限りません
ので注意して下さい。

**DBIのクラスメソッド [#pbc3d4fd]
　DBI->で使用するメソッドです。
***connect [#e7f2d4c9]
　データベースに接続します。~

  $dbh = DBI->connect($data_source, $username, $password)
            or die $DBI::errstr;
  $dbh = DBI->connect($data_source, $username, $password, %attr)
            or die $DBI::errstr;

　%attr パラメータで、[[AutoCommit>#AutoCommit]],[[PrintError>#PrintError]],[[RaiseError>#RaiseError]]などのアトリビュート
のデフォルト値を変更することができます。~

  $dbh = DBI->connect($data_source, $user, $pass, {
        RaiseError => 1,
        AutoCommit => 0
  });

　$data_sourceパラメータの中で接続属性の値を定義することもできます。~

  dbi:DriverName(PrintError=>0,Taint=>1):...

　この方法で指定された値は、%attrパラメータで指定された値より優先されます。


※IB/FBでの補足事項
　FB/IBに接続する場合に指定する接続パラメータは次のようになっています。
必須項目はデータベース名のみです。大抵はデータベース名とホスト名の指定
程度での使用が多いでしょう。~

|パラメータ|説明|必須項目|h
|database&br;又はdbname&br;又はdb|データベース名|○|
|host|ホスト名||
|port|ポート番号||
|ib_dialect|Dialect数||
|ib_role|ロール名||
|ib_charset|キャラクタセットの指定||
|ib_cache|キャッシュバッファサイズ||

　実際の指定は、ＩｎｔｅｒＢａｓｅ用DBD使用の指定と、独自の接続パラメータの指定
を同時に行います。同時の接続パラメータが複数ある場合は、パラメータの間を
セミコロンで区切ります。~
　例えば、次のような形になります。

 $dbh = DBI->connect("dbi:InterBase:dbname=$dbname","sysdba","masterkey");

　マルチラインでの指定も可能です。

 $dsn =<< "DSN";
 dbi:InterBase:dbname=$dbname;
 host=$host;
 port=$port;
 ib_dialect=$dialect;
 ib_role=$role;
 ib_charset=$charset;
 ib_cache=$cache
 DSN

　リモートホストに接続する場合の接続パラメータは、例えば次のようになります。
ここではデータベースパラメータに別名の"db"を使用しています。

 $dsn = "dbi:InterBase:db=C:/temp/test.fdb;host=server.intranet";

　ポート番号はhostパラメータで同時に指定することも出来ます。

 $dsn = 'dbi:InterBase:db=/data/test.fdb;host=localhost/3060';

***connect_cached [#s1e53684]
　基本的にはconnect()と同じですが、パラメータの値がキャッシュされ、過去と
同じパラメータが指定された場合には同じハンドルを設定します。~
　''Apache::DBIで提供される永続的な接続とは多くの点で異なります。''


***available_drivers [#g7744351]
　有効なドライバ群を取得します。(DBIに実装)

 @driver_names = DBI->available_drivers;

***data_sources [#dd3cda8f]
　DBD::ＩｎｔｅｒＢａｓｅでは未実装です。

**DBIの動的アトリビュート [#t506915b]

***$DBI::err [#d6d48279]
　[[err>#err]]参照。

***$DBI::errstr [#q931f133]
　[[errstr>#errstr]]参照。

***$DBI::rows [#efa3f146]
　[[rows>#rows]]参照。

***$DBI::state [#y0875414]
　エラーコードを標準の SQLSTATE5 文字形式で返します。
DBD::ＩｎｔｅｒＢａｓｅでは未実装です。
　[[state>#state]]と同じです。

***$DBI::lasth [#c173d52b]
　最後のDBIメソッド呼び出しに使われたDBIオブジェクト・ハンドルを返します。
　最後のDBIメソッド呼び出しが破棄の場合う、もしも存在するならば破棄された
ハンドルの親のハンドルを返します。


**全ハンドル共通のクラスメソッド [#j5b0f8bf]
　全てのハンドルで使用できるメソッドです。

&aname(err);
***[[err>#err]] [#rcffd175]
　エラーの取得

 $rv = $h->err;

&aname(errstr);
***[[errstr>#errstr]] [#vea36cce]
　エラーの取得(文字列)

 $str = $h->errstr;

&aname(state);
***[[state>#state]] [#n3d71268]
　DBD::ＩｎｔｅｒＢａｓｅでは未実装です。

***trace [#be70bd1b]
　トレースの指定。DBI本体の機能です。

 $h->trace($trace_level, $trace_filename);

***trace_msg [#rff8545b]
　トレースメッセージ。DBI本体の機能です。

 $h->trace_msg($message_text);

***func [#pa7765fe]
　DBDの機能呼び出し。DBD:ＩｎｔｅｒＢａｓｅではトランザクション関係で使用します。~
　詳細は、[[トランザクション>#tran]]を参照して下さい。


**全ハンドル共通のアトリビュート [#jf59be1c]

***Warn [#v89d0a0d]
　論理型です。DBI本体の機能です。

***Active [#d6a05659]
　読込み専用の論理型です。~
　アクティブ状態であることを示します。データベースハンドルの場合は
データベースに接続中であることを示します。

***Kids [#yb738889]
　読込み専用の論理型です。DBI本体の機能です。~
　「子」のハンドル数を示します。例えば、データーベースハンドルや
ステートメントハンドルの数です。

***[[ActiveKids>#ActiveKids]] [#mf563f8c]
　読込み専用の論理型です。DBI本体の機能です。~
　アクティブになっているデータベースハンドルやステートメントハンドル
の数です。

***[[CachedKids>#CacheKids]] [#kefa6341]
　ハッシュで、DBI本体の機能です。~
　「子」のハンドルに関するキャッシュです。例えば、ステートメントハンドル
のprepareに関するキャッシュなどです。

***[[CompatMode>#CompatMode]] [#l5440457]
　読込み専用の論理型です。~
　DBD:ＩｎｔｅｒＢａｓｅでは意味がありません。

***[[InactiveDestroy>#InactiveDestroy]] [#ea34ad63]
　論理型で、DBI本体の機能です。~
　新プロセスでハンドルを破棄しないように設定します。

&aname(PrintError);
***[[PrintError>#PrintError]] [#lb0ffe39]
　論理型で、DBI本体の機能です。~
　エラーを詳細に報告するかを設定します。デフォルトはTRUEです。

&aname(RaiseError);
***[[RaiseError>#RaiseError]] [#f3f89e39]
　論理型で、DBI本体の機能です。~
　エラーを例外で発生させるかを設定します。デフォルトはFALSEです。

&aname(ChopBlanks);
***[[ChopBlanks>#ChopBlanks]] [#lf65ae46]
　論理型で、DBI本体の機能です。~
　CHARなどの固定幅項目のスペースに対するトリミング動作を設定します。
デフォルトはFALSEです。

&aname(LongReadLen);
***[[LongReadLen>#LongReadLen]] [#w793db67]
　整数型で、DBI本体の機能です。~
　BLOBでの取り扱い最大長を制御します。デフォルトは80です。
これに0を設定すると、BLOBのデータが取得できません。

&aname(LongTruncOk);
***[[LongTruncOk>#LongTruncOk]] [#l6188ce4]
　論理型で、DBI本体の機能です。~
　[[LongReadLen>#LongReadLen]]で設定した値よりも大きい BLOB の取得を許可(切捨て)
します。FALSEにすると、設定値よりも大きいBLOBを取得すると失敗します。
デフォルトはFALSEです。

&aname(Taint);
***Taint [#b249d7cc]
　論理型で、DBI本体の機能です。~
　Taintモードに設定します。


**データベースハンドルのメソッド [#a2de59bc]
　DBI->connectで取得したデータベースハンドルで使用するメソッドです。

***selectrow_array [#d1963a4f]
　prepare, execute ,fetchrow_arrayの3メソッドの処理を一度に行います。

  @row_ary = $dbh->selectrow_array($statement);
  @row_ary = $dbh->selectrow_array($statement, %attr);
  @row_ary = $dbh->selectrow_array($statement, %attr, @bind_values);

***selectall_arrayref [#r502d9b4]
　prepare, execute ,fetchall_arrayrefの3メソッドの処理を一度に行います。
　取り出されたデータ各行の配列へのリファレンスが入った配列へのリファレンスを返します。

  $ary_ref = $dbh->selectall_arrayref($statement);
  $ary_ref = $dbh->selectall_arrayref($statement, %attr);
  $ary_ref = $dbh->selectall_arrayref($statement, %attr, @bind_values);

***selectcol_arrayref [#adb3ab73]
　prepare, executeを行い、全ての行の特定のカラムを取り出します。
　各行の最初のカラムの値が入った配列へのリファレンスを返します。

  $ary_ref = $dbh->selectcol_arrayref($statement);
  $ary_ref = $dbh->selectcol_arrayref($statement, %attr);
  $ary_ref = $dbh->selectcol_arrayref($statement, %attr, @bind_values);

***prepare [#xb004539]
　SQL文実行の準備を行います。

  $sth = $dbh->prepare($statement)
  $sth = $dbh->prepare($statement, %attr);

　[[AutoCommit>#AutoCommit]]がTRUEになっている場合、SQL実行のために新たに暗黙のトランザクション
を開始し、次の execute() または最後の fetch() を実行すると自動的に変更が
コミットされます。SELECT文の場合は、最後のfetch()またはfinsh()が呼び出された
ときにコミットされます。


***prepare_cached [#m6514c8b]
　キャッシングが行われる以外はprepareと同様です。DBI本体の機能です。~
　アプリケーションによっては問題を起こすことがありますので注意が必要です。

***do [#n7b27aff]
　１ステートメントをprepareし、executeします。
成功ならば影響を受けた行数を、エラーであればundefを返します。
行数が不明の場合は-1を返します。

  $rc  = $dbh->do($statement);
  $rc  = $dbh->do($statement, %attr);
  $rv  = $dbh->do($statement, %attr, @bind_values);

　SELECT文で使用した場合は結果が受取れません。

***commit [#ece03440]
　コミットを行います。[[トランザクション>#tran]]を参照して下さい。
  $rc  = $dbh->commit;

***rollback [#q1b977f4]
　ロールバックを行います。[[トランザクション>#tran]]を参照して下さい。
  $rc  = $dbh->roolback;


***disconnect [#ndc0c594]
　データベースハンドルをデータベースから切断します

  $rc  = $dbh->disconnect;

***ping [#fc70a29d]
　データベースハンドルが有効か検証します。

  $rc = $dbh->ping;

***table_info [#efd3470c]
　テーブルの情報を取得するためのステータスハンドルを取得します。

  $sth = $dbh->table_info;

***tables [#m9902d57]
　テーブルの名前のリストを返します。

  @names = $dbh->tables;

***type_info_all [#b0e97452]
　使用できるデータ型の情報を返します。

  $type_info_all = $dbh->type_info_all;

***type_info [#y6b6e47c]
　データ型の情報を返します。DBI本体の機能です。????~

  @type_info = $dbh->type_info($data_type);


***quote [#ya8c6200]
　クォーテーション文字を変更します。DBI本体の機能です。~

  $sql = $dbh->quote($value, $data_type);

**データベースハンドルのアトリビュート [#tf2a792e]
　DBI->connectで取得したデータベースハンドルで使用するアトリビュートです。

&aname(AutoCommit);
***[[AutoCommit>#AutoCommit]] [#r6f2cadd]
　論理型です。~
　ＩｎｔｅｒＢａｓｅの場合、ON(TRUE)ならば暗黙的なトランザクションが使用されます。
デフォルトは ON です。詳しくは[[トランザクション>#tran]]を参照して下さい。

***Driver [#f5cc58bb]
　親ドライバのハンドルを保持します。

***Name [#ke97e388]
　DBD::ＩｎｔｅｒＢａｓｅでは未実装です。

&aname(RowCahceSize);
***[[RowCacheSize>#RowCacheSize]] [#zde9ba76]
　DBIには実装されていますが、DBD::ＩｎｔｅｒＢａｓｅでは使用していません。

***ib_softcommit [#pa7ae669]
　論理型です。''DBD::ＩｎｔｅｒＢａｓｅ独自の機能です。''~

　ソフトコミット機能を有効にします。トランザクションを完全に終了せずに変更
されたレコードを更新し、参照などでロックされているアクセスを許可します。
デフォルトではFALSEになっています。
　これにより、トランザクションで待ちに入っているアプリケーションの処理が
実行できる場合があります。[[AutoCommit>#AutoCommit]] がTRUEになっている場合は
特に有用です。

　値を現在の設定値より変更すると、現在のトランザクションが強制的に
ハードコミットされます。


**ステートメントハンドルのメソッド [#aee05813]

***bind_param [#t67390bf]
　変数を、prepareされたSQL文に埋め込まれたプレースホルダに関連付けます。
プレースホルダは疑問符(?)により示されます。BLOB使用時には、よく本メソッド
を使用します。prepare後に使用します。

 $rc = $sth->bind_param($p_num, $bind_value);
 $rv = $sth->bind_param($p_num, $bind_value, %attr);
 $rv = $sth->bind_param($p_num, $bind_value, $bind_type);

　3番目の引数で渡される SQL データタイプは、DBD::ＩｎｔｅｒＢａｓｅ
では無視されます。

***bind_param_inout [#rbd32451]
　DBD::ＩｎｔｅｒＢａｓｅでは未実装です。

***execute [#w6099e42]
　repareで準備されたSQL文を実行します。

 $rv = $sth->execute;
 $rv = $sth->execute(@bind_values)

***fetchrow_arrayref [#qaee0046]
　次の行を取り出し、フィールドの値をもった配列へのリファレンスを返します。
NULLフィールドはundefとなります。fetchという別名も使用できます。データが
無いかエラーの場合、undefを返します。

  $ary_ref = $sth->fetchrow_arrayref;
  $ary_ref = $sth->fetch;

***fetchrow_array [#ldfba8a6]
　fetchrow_arrayrefと同じですが、配列そのものを返します。

 @ary = $sth->fetchrow_array;

***fetchrow_hashref [#a19ed8a3]
　fetchrow_arrayrefと同じですが、結果をハッシュで返します。

 $hash_ref = $sth->fetchrow_hashref;
 $hash_ref = $sth->fetchrow_hashref($name);

***fetchall_arrayref [#t41766ce]
　DBI本体の機能です。~
　すべてデータを取り出します。行ごとの配列へのリファレンスが格納された配列
へのリファレンスを返します。

  $tbl_ary_ref = $sth->fetchall_arrayref;


***finish [#uefbcafa]
　もう一度executeされるまで、このステートメント・ハンドルからのデータ
取り出しは行われないことを示します。

  $rc = $sth->finish;

&aname(rows);
***[[rows>#rows]] [#m4fc3646]
　最後のコマンドにより影響を受けた行数を返します。行数が不明また使用不能
の場合は、-1になります。

  $rv = $sth->rows;

　SELECT文の場合は、今までの処理で取得した行数が格納されます。

***bind_col [#l1883919]
　SELECT文による取得列(フィールド)の指定された項目に、 Perl 変数を関連
付けます。bind_columnsも参照して下さい。番号は1から数えます。
結果が変数に直接コピーされるため、処理高速化のために非常に有効です。

  $rc = $sth->bind_col($column_number, \$var_to_bind, %attr);

***bind_columns [#c6c3cf35]
　SELECT文による取得列(フィールド)に Perl の変数を関連付けます。
結果が変数に直接コピーされるため、処理高速化のために非常に有効です。
変数の数とSQLで取り出す列の数が一致していないと、dieとなります。

  $rc = $sth->bind_columns(%attr, @list_of_refs_to_vars_to_bind);


***dump_results [#f703c8a5]
　DBI本体の機能です。~
　結果をダンプ出力します。デバッグ時などの簡易テスト用です。

  $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh);


**ステートメントハンドルのアトリビュート [#afaab2e9]

***NUM_OF_FIELDS [#zbcb3d1b]
　整数型で読込み専用です。DBI本体の機能です。~
　準備されたSQL文の列数（カラム数）を示します。SELECT文以外は０になります。

***NUM_OF_PARAMS [#r450cd0c]
　整数型で読込み専用です。DBI本体の機能です。~
　準備されたSQL文のプレースホルダ('?')数を示します。

***NAME [#xb13fcd7]
　配列へのリファレンスで読込み専用です。~
　各列に対応するフィールド名の配列へのリファレンスを返します。表現の文字種
(大文字/小文字)は実装に依存します。FBでは大文字固定かな？

***NAME_lc [#x9e56230]
　配列へのリファレンスで読込み専用です。DBI本体の機能です。~
　各列に対応するフィールド名の配列へのリファレンスを返します。
表現はかならず小文字になります。

***NAME_uc [#v5077c90]
　配列へのリファレンスで読込み専用です。DBI本体の機能です。~
　各列に対応するフィールド名の配列へのリファレンスを返します。
表現はかならず大文字になります。

***TYPE [#x6486a73]
　配列へのリファレンスで読込み専用です。~
　各列に対応した、整数値の配列へのリファレンスを返します。
値は対応する列のデータ型を示します。 データ型は、国際標準ではなく、
IB/FB特有のデータタイプとなります。

***PRECISION [#y4c691c4]
　配列へのリファレンスで読込み専用です。~
　各列の数値が格納されます。数値以外の列は、通常は最大長や定義長
が格納されます。

***SCALE [#m272d692]
　配列へのリファレンスで読込み専用です。~
　各列に対応した整数値が格納されます。NULL(undef)のい場合は、SCALE
が適用されないことを示します。

***NULLABLE [#b41c61b2]
　配列へのリファレンスで読込み専用です。~
　各列にNULLを設定出来るかを示します。(0:不可,1:可,2:不明)

&aname(CursorName);
***[[CursorName>#CursorName]] [#n239c543]
　文字列で読込み専用です。~
　カーソル名が、可能な限りにおいて格納されます。

***Statement [#jaedbf24]
　文字列で読込み専用です。~
　prepare()で渡された文を保持します。

&aname(RowCache);
***[[RowCache>#RowCache]] [#na07b97a]
　整数型で読込み専用です。DBI本体の機能です。~
　DBD::ＩｎｔｅｒＢａｓｅでは未実装です。


*ドライバ特有の事項 [#w027133f]

&aname(tran);
**トランザクション [#o8873b82]
　トランザクションの動作は、[[AutoCommit>#AutoCommit]]の設定により制御されます。~

　[[AutoCommit>#AutoCommit]]の値はデフォルトでは TRUE となっており、変更は直ちにデータベース
に反映されます。明示的に呼び出したcommit()やrollback()は拒否されます。~
&br;
　[[AutoCommit>#AutoCommit]]をFALSEに設定すると、ただちに新しいトランザクションが
開始されます。そこで rollback()を呼び出せば、トランザクションは
ロールバックされます。また、disconnet()を呼び出した場合もロールバック
されます。

　ＩｎｔｅｒＢａｓｅ/Firebirdはトランザクションに対して非常に詳細な制御
を行うことが出来ます。制御できる項目は、アクセスモード、アイソレーション
レベル、ロックレゾリューション、テーブル予約などです。
　具体的には、データベースハンドルのメソッドである、ib_set_tx_param()
を使用します。~
&br;

　connect()が成功したとき、トランザクションのデフォルトの設定値は
次のようになっています。

 アクセスモード:           read/write
 アイソレーションレベル:   concurrency(一致)
 ロックレゾリューション:   wait

　これを必要に応じ、ib_set_tx_param()で変更します。~

***[[AutoCommit>#AutoCommit]]をオフにしたときのトランザクション処理 [#l0c89520]
　詳細は DBI のドキュメントを参照してもらうとして、ここでは概要を書きます。~
&br;
　[[AutoCommit>#AutoCommit]]がFALSEになっている場合、トランザクションの開始は自動で
行われますが、コミットの処理は明示的に行う必要があります。~
&br;
　お勧めの方法は、アトリビュートの"[[RaiseError>#RaiseError]]"と"eval{}"を
併用し、例外処理により処理を行う方法です。
[[RaiseError>#RaiseError]]が TRUE になっているときに該当するハンドルやその子供のハンドルに
対する処理でエラーが発生すると、例外が発生してDBIが"die"します。
それを"eval{}"で捕まえようという発想です。~
　evel{} を使用するのは、eval "..." よりも通常は処理が軽いためです。~

&br;
例: (接続等の処理は省いて書いてあります。)

  # 次の2項を事前に設定しておく
  $dbh->{RaiseError} = 1; #エラーを例外化
  $dbh->{AutoCommit} = 0; #自動コミットオフ
 
  eval {
      #---- ここでINSER/UPDATEなどの処理が入る ----
      $dbh->commit;       # ここまで来たらコミット
  };
  if ($@) {
      warn "トランザクション中に例外発生 $@";
      $dbh->rollback;     # ロールバック
      # ロールバック時の、その他の処理
  } else {
      # コミット時の、その他の処理
  }

　この方法ならば、トランザクション中に不測の事態が発生しても、可能な限り
エラーをハンドリングできます。また、DBIのエラーチェックが自動で行われます
ので、バグが発生しにくくなる利点もあります。~
&br;
　[[RaiseError>#RaiseError]]を設定しない場合には、DBI呼び出し時に手動で
エラーのチェックをする必要があります。例えば次のように行います。

  $dbh->method(@args) or die $h->errstr;


***ib_set_tx_param [#ya35c993]
　データベースハンドルのfunc()メソッドを使用して、次のようにして
呼び出します。

 $dbh->func(
    -access_mode     => 'read_write',
    -isolation_level => 'read_committed',
    -lock_resolution => 'wait',
    'ib_set_tx_param'
 );

アクセスモード(-access_mode)には次のものが設定できます。
&br;
・read_write
&br;
　読書きがロックされます。
&br;
・read_only
&br;
　読込みは許可されます。
&br;

ロックレゾリューション(-lock_resolution)には次のものが設定できます
&br;
・wait
&br;
　衝突した場合、処理が待たされます。
&br;
・no_wait
&br;
　処理は待たされずにエラーとなります。

アイソレーションレベルには次のものが設定できます。
&br;
・snapshot
&br;
　トランザクション開始以降に他で変更された項目は変更後の内容が見えません。
&br;
・read_committed
&br;
　他トランザクションでコミットされた瞬間に最新の変更内容が参照できます。
最新版候補のレコードとの矛盾を生じ無ければ変更も出来ます。
いずれにせよ、コミット前の変更は見えません。
&br;
　read_comittedを設定した場合は、さらに次の項目のどれかが設定できます。
&br;
・record_version
&br;
　たとえ更に新しいバージョンの行が存在していても、常に最後にコミットされた
行のみが見えます。
&br;
・no_record_version
&br;
　未指定時のデフォルトです。常に行の最新バージョンのみが見えます。
WAITと同時に指定された場合、列の処理が衝突した場合にはトランザクションが
完了するまで処理が待たされます。~
　例えば次のようにして指定します。

 $dbh->func(
    -isolation_level => ['read_committed', 'record_version'],
    'ib_set_tx_param'
 );

　テーブル予約は、Version0.30以降でサポートされました。~
　トランザクションの開始でテーブル予約を行う時には、希望するアクセス
レベルを指定できます。予約を行うことにより、デッドロックの危険性を
縮小出来るかもしれません。予約するテーブルの名前は、-reservingで指定
します。
　例えば、次のように指定を行います。

 $dbh->func(
    -access_mode     => 'read_write',
    -isolation_level => 'read_committed',
    -lock_resolution => 'wait',
    -reserving       =>
        {
            foo_table => {
                lock    => 'read',
            },
            bar_table => {
                lock    => 'read',
                access  => 'protected',
            },
        },
    'ib_set_tx_param'
 );

　予約時のオプションは、次のものが設定できます。~
・access (オプション指定項目です)~
　sharedもしくはprotectedを指定します。~
・lock (必須指定項目)~
　readもしくはwriteを設定します。~
&br;

&aname(tips_tablelock);
 ※Tips※
 SNAPSHOT,WAITの設定とテーブル予約(read/protced)を
 併用すると、テーブルレベルの排他ロック(WAIT)と同じ
 効果が得られます。テーブル予約付きトランザクション
 開始の時点で予約の衝突が起こるためなんでしょうね。

&br;
　[[AutoCommit>#AutoCommit]]が TRUE の場合でも、ib_set_tx_param()で値を設定すること自体は
出来ます。現在のトランザクションが完了して、新たに始まるトランザクション
から設定したパラメータが有効になります。~
　パラメータなしで呼び出した場合、デフォルトの設定値にリセットします。

**その他のFB/IB独自機能に対する拡張 [#u790a62d]


***ib_database_info [#xf6085b4]
　現在接続中のデータベース情報を検索します。

 $hash_ref = $dbh->func(@info, 'ib_database_info');
 $hash_ref = $dbh->func([@info], 'ib_database_info');


***ib_plan [#ec656739]
　SQL文からクエリプランを検索します。

 $plan = $sth->func('ib_plan');

　例えば、次のようにして使用します。

 my $sth = $dbh->prepare('SELECT * FROM foo');
 print $sth->func('ib_plan');       # PLAN (FOO NATURAL)


**日時の表現について [#yb0a4067]
　DBD::ＩｎｔｅｒＢａｓｅでは、日時用のデータ型として、DATE,TIME,TIMESTAMP
をサポートしています。~
　デフォルト動作では、クエリ実行の結果に対してTIMESTAMPは"%c"、DATEは"%x"、
TIMEは"%X"を変換規則として ANSI C の strftime() 関数に渡して、文字列への
変換を行います。~
　変換規則を変更したい場合は、アトリビュート ib_timestampformat,
ib_dateformat,ib_timeformatを設定することにより実現できます。~

・データベースハンドルレベル($dbh)での設定~
　デフォルト設定を変更する例です。

 $dbh->{ib_timestampformat} = '%m-%d-%Y %H:%M';
 $dbh->{ib_dateformat} = '%m-%d-%Y';
 $dbh->{ib_timeformat} = '%H:%M';

&br;
・ステートメントハンドルレベル($sth)での設定~

　今回の prepare で、一時的に設定する例です。

 $attr = {
    ib_timestampformat => '%m-%d-%Y %H:%M',
    ib_dateformat => '%m-%d-%Y',
    ib_timeformat => '%H:%M',
 };
 # then, pass it to prepare() method.
 $sth = $dbh->prepare($sql, $attr);

&br;
　strftime()は地域設定の影響を受けますので、事前に適切な設定が必要です。~
　もし、あなたのアプリケーションが複数の地域での使用が想定されるならば、
２つの特別なフォーマットの採用を考えてもいいかもしれません。('TM'と'ISO')~
　'TM'は、Perlのlocaltime()と同じ９個の要素を返します。'ISO'は、データ型
に依存した、次のような形式の値を返します。~

|データ型|sprintf()でのフォーマット指定|h
|TIMESTAMP|"%04d-%02d-%02d %02d:%02d:%02d.%04d"|
|DATE|"%04d-%02d-%02d"|
|TIME|"%02d:%02d:%02d.%04d"|

　$dbh-E<gt>{ib_time_all}を設定することにより、３つのデータ項目全て
の設定を一括して行うことが出来ます。例えば、すべてを'TM'に設定する場合
には次のようなります。

 $dbh->{ib_time_all} = 'TM';

**イベントアラータに関する追加機能 [#tb752edd]

***ib_init_event [#zdf90c51]
　イベント名を指定してイベントハンドルを初期化します。

 $evh = $dbh->func(@event_names, 'ib_init_event');

***ib_wait_event [#y467d1a7]
　指定したイベントハンドルに対して同期を行います。

 $dbh->func($evh, 'ib_wait_event');

***ib_register_callback [#r23e8353]
　非同期待ち用コールバックを登録します。

 $dbh->func($evh, sub { print "callback..\n" }, 'ib_register_callback');

***ib_reinit_event [#te2dfd97]
　指定したイベントハンドルを再初期化します。

 $dbh->func($evh, 'ib_reinit_event');

**DBD::ＩｎｔｅｒＢａｓｅで使用できないSQLとその対処法 [#o3d1c358]

***SET TRANSACTION [#cf4c8b53]
　$dbh->func(..., 'set_tx_param') を使用してください。~
　詳しくは、[[トランザクション>#tran]]や[[set_tx_param>#set_tx_param]]
を参照して下さい。

***DESCRIBE [#i87078a5]
　カラム名の取得は、$sth->{NAME}アトリビュートによって代用できます。

***EXECUTE IMMEDIATE [#v23bea8c]
　do()を使用してください。

***CLOSE, OPEN, DECLARE CURSOR [#e78a4ee3]

　"$sth->{[[CursorName>#CursorName]]}" の実行により、"SELECT .. FOR UPDATE" 文で自動的に
同じ効果が得られます。~
　カーソルのクローズは、最後の fetch() 呼び出しまたは $sth->finsh() により
行われます。


***PREPARE, EXECUTE, FETCH [#hf800f7a]

　prepare(), execute(), fetch() メソッドで同様なことが出来ます。


**概知のバグや制限事項 [#nb71ab0d]
-概知のバグは今のところありません。しかし、これはバグが無いことを永久に
保証するものではありません。
-FB/IB独自機能である配列の格納はサポートしていません。
-BLOBのブロック読書きは今のところはまだサポートされません。最大の読書き
サイズは、安全重視のプログラムならば、概ね 1MB 程度と思っておけば安全です。

----