[pod] [xml]

名前

Oraperl - 古いoraperlスクリプトに代わるPerlからOracleデータベースへのアクセス

概要

  eval 'use Oraperl; 1;' || die $@ if $] >= 5;  # 古いスクリプトには、この行を追加してください
  $lda = &ora_login($system_id, $name, $password)
  $csr = &ora_open($lda, $stmt [, $cache])
  &ora_bind($csr, $var, ...)
  &ora_fetch($csr [, $trunc])
  &ora_close($csr)
  &ora_logoff($lda)
  &ora_do($lda, $stmt)
  &ora_titles($csr)
  &ora_lengths($csr)
  &ora_types($csr)
  &ora_commit($lda)
  &ora_rollback($lda)
  &ora_autocommit($lda, $on_off)
  &ora_version()
  $ora_cache
  $ora_long
  $ora_trunc
  $ora_errno
  $ora_errstr
  $ora_verno
  $ora_debug

説明

Oraperl はOracleデータベースへのアクセスを可能にする拡張機能です。

オリジナルのoraperlはOracle OCIと一緒にコンパイルされたPerl 4 バイナリです。 ここで説明されるPerl 5 Oraperlモジュールは、(DBIの中で働くデータベース・ドライバ) DBD::Oracleと一緒に配布され、DBIメソッド呼び出しの上に特別なレイヤを 追加します。 Oraperlモジュールは既存のPerl 4 oraperlスクリプトを最低限の変更で走らせるられる ようにだけ使われるべきです;新しい開発はすべて、DBIを直接使うべきです。

この拡張機能を実現する関数群については、以下のセクションで説明します。 すべての関数は、失敗するとfalseまたは（Perlでの）未定義値(undef)を 返します。これらの説明の中のOCIのリファレンスについて理解する必要は ありません。ルーチンを拡張したり、新しいマシンに移植したいという人の ために書いてあります。

この文書は、Kevin Stok<kstock@auspex.fr>により書かれた元のPerl4 oraperl マニュアルから大きく変更されていません。DBD::Oracle、Oraperlエミュレーションに 特有のコメントについては、頭にDBD:をつけています。より詳しい情報については、 DBD::OracleとDBIマニュアルをご覧下さい。

DBD: oraperlの関数定義をPerl5で使えるようにするには、それを使用する ファイルまたはパッケージでOraperl.pmモジュールをuseする必要があります。 これは各ファイルまたはパッケージにuser Oraperl;という行を単に 加えるだけでできます。perl4 oraperlとperl5の両方でスクリプトが動くようにする 必要があれば、代わりに以下のテキストを加えて下さい: 

  eval 'use Oraperl; 1;' || die $@ if $] >= 5;

基本的な関数

データベースにアクセスするための主要な関数は&ora_login(), &ora_open(), &ora_bind(), &ora_fetch(), &ora_close(), &ora_do() そして &ora_logoff()です。

補助的な関数

以下の追加の関数を使うことが出来ます: &ora_titles(), &ora_lengths(), &ora_types(), &ora_autocommit(), &ora_commit(), &ora_rollback() そして &ora_version()。

前の３つは主にSQL文が対話的に入力されることを可能と しているプログラムのなかで使われます。Oraperlと 一緒に提供され、あなたのサイトにインストールされて いるはずのプログラム例をご覧下さい。

変数

以下の６つの特殊な変数$ora_cache, $ora_long, $ora_trunc, $ora_errno, $ora_errstr ,$ora_vernoが提供されています。

カスタマイズのための変数

これらの変数はある状況でのOraperlの動きを指令するために 使われます。

状態を表す変数

これらの変数はエラー状態またはOraperlそのものの情報を示します。 これらは読込のみが許されるかもしれません；プログラムが変更しようとすると 致命的なエラーが発生します。

置換変数

OraperlではSQL文に置換変数を入れることができます。これらは先頭に コロン（：）が付いた数字です。例えば、電話番号リストにレコードを 追加するプログラムは以下のように&ora_open()を呼び出すことが出来ます：

  $csr = &ora_open($lda, "insert into telno values(:1, :2)");

（訳者注： 原文では「&ora_open($csr」となっていますが、間違いでしょう。） ２つの名前 :1 と :2 は置換変数と呼ばれます。&ora_bind() 関数は、これらの 変数に値を代入するために使われます。例えば、以下の文は新しい２人を リストに追加します：

  &ora_bind($csr, "Annette", "472-8836");
  &ora_bind($csr, "Brian", "937-1823");

&ora_bind()がその引数を順番に代入するため、置換変数は、各SQL文で １から始まって連続して代入されることに注意して下さい。 名前付きの置換変数（例えば :NAME, :TELNO) は許されていません。

DBD: 置換変数は現在、デフォルトでは、type 1(VARCHAR2)あるいは type 5(STRING)として結びつけられます。これは、charフィールドと 置換変数を比較するSQLコードの動きを変えてしまうこともあります。 詳細についてはOracle OCIマニュアルの「データ型(=Datatypes)」の章の 文字列比較(String Comparison)のセクションをご覧下さい。

フィールド毎に使われるOracle型を指定するというDBD::Oracleの機能を 使って、これを回避することが出来ます：

  $char_attrib = { ora_type => 5 }; # 5 = STRING (oraperl2.4と同等)
  $csr = ora_open($dbh, "select foo from bar where x=:1 and y=:2");
  $csr->bind_param(1, $value_x, $char_attrib);
  $csr->bind_param(2, $value_y, $char_attrib);
  ora_bind($csr);  # bind_param()をしてあるので、パラメータなしでbind

デバッグ方法

DBD: Oraperl $ora_debug 変数はサポートされていません。 しかし以下のようにすることで、いつでもデバッグが可能になります

  $h->debug(2);

$hには$lda または$csrのどちらも設定できます。$ldaに対してデバッグが 可能になると、&ora_open()によって返されたすべてのカーソルに対しても 自動的に渡されます。

例

  format STDOUT_TOP =
  Name Phone
  ==== =====
  .
  format STDOUT =
  @<<<<<<<<<< @>>>>>>>>>>
  $name, $phone
  .
  die "You should use oraperl, not perl\n" unless defined &ora_login;
  $ora_debug = shift if $ARGV[0] =~ /^\-#/;
  $lda = &ora_login('t', 'kstock', 'kstock')
            || die $ora_errstr;
  $csr = &ora_open($lda, 'select * from telno order by name')
            || die $ora_errstr;
  $nfields = &ora_fetch($csr);
  print "Query will return $nfields fields\n\n";
  while (($name, $phone) = &ora_fetch($csr)) { write; }
  warn $ora_errstr if $ora_errno;
  die "fetch error: $ora_errstr" if $ora_errno;
  do ora_close($csr) || die "can't close cursor";
  do ora_logoff($lda) || die "can't log off Oracle";

注意

Perlの考え方を保つため、同時ログインやアクティブにできるSQL文の数、 あるいは問い合わせにより返されるデータ・フィールドの数に、上限は あらかじめ設けていません。強制される制限は利用できるメモリの量に よるもの、あるいはOracleによるものだけです。

警告

Oraperlエミュレーション・ソフトウェアは元のoraperlとコードを何ら 共用していません。それは新しいPerl5 DBIとDBD::Oracleモジュールの 上に構築されています。これらのモジュールはまだ開発中です （Oraperlエミュレーション・ソフトウェアの目標の１つに、 インターフェイスの変更を続けながらユーザーからはそれを切り離し、 DBIとODB::Oracleモジュールによって有効な作業を実現することがあります）

いくつか動きに違いがある可能性が高く、まず間違いありません。 これらはおそらくエラーの取り扱いに限られます。

この文書に記述されていない全ての動き違いは、dbi-users@perl.orgに 報告してください。

参考資料

作者

Perl by Larry Wall <lwall@netlabs.com>.

ORACLE by Oracle Corporation, California.

Original Oraperl 2.4 code and documentation by Kevin Stock <kstock@auspex.fr>.

DBI and Oraperl emulation using DBD::Oracle by <Tim.Bunce@ig.co.uk>