DB_FILE(3)               USER COMMANDS                 DB_FILE(3)



NAME
     DB_File - Perl5 からバークレイ DB へのアクセスを行なう

SYNOPSIS
      use DB_File ;

      [$X =] tie %hash,  DB_File, $filename [, $flags, $mode, $DB_HASH] ;
      [$X =] tie %hash,  DB_File, $filename, $flags, $mode, $DB_BTREE ;
      [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ;

      $status = $X->del($key [, $flags]) ;
      $status = $X->put($key, $value [, $flags]) ;
      $status = $X->get($key, $value [, $flags]) ;
      $status = $X->seq($key, $value [, $flags]) ;
      $status = $X->sync([$flags]) ;
      $status = $X->fd ;

      untie %hash ;
      untie @array ;


DESCRIPTION
     DB_File は、Perl プログラムがバークレイ DB で用意された機能
     を使えるようにするためのモジュールです。 このモジュールを使
     おうとするならば、バークレイ DB のマニュアルを必ず入手してお
     くべきでしょう。 ここに定義されるインタフェースは、バークレ
     イ DB インタフェースをそっくりまねています。

     バークレイ DB は、多くのデータベース形式への一貫したインタフ
     ェースを提供する C ライブラリです。 DB_File は、バークレイ
     DB で現在サポートされている、三つのデータベースタイプへのイ
     ンタフェースを提供します。

     ファイルタイプ:

     DB_HASH
          このデータベースタイプでは、データファイルに任意の key
          と data のペアを蓄えることができるものです。 これは、
          DBM、NDBM、ODBM、GDBM、SDBM のような他のハッシュを行な
          うパッケージが提供する機能と同じものです。 しかながら、
          DB_HASH で作られたファイルは、他のパッケージでのものと
          互換性がありません。

          デフォルトのハッシュアルゴリズムは、ほとんどのアプリケ
          ーションに適合できるもので、バークレイ DB に組み込まれ
          ています。 自分のハッシュアルゴリズムを使う必要がある
          ときには、Perl で書いて、DB_File に使わせることもできま
          す。

     DB_BTREE
          btree 形式では、key と data のペアをソートした平衡型バ
          イナリトリーに蓄えます。



Perl module manpages Last change: Release 5.0 Patchlevel 00     1






DB_FILE(3)               USER COMMANDS                 DB_FILE(3)



          DB_HASH 形式と同じく、key の比較を行なう Perl ルーティ
          ンをユーザが定義することができますが、デフォルトでは、
          key は文字の順に蓄えられます。

     DB_RECNO
          DB_RECNO では、DB_HASH や DB_BTREE と同じ key と value
          のペアのインタフェースを使って操作できる、固定長、可変
          長のテキストファイルが許容されます。 この場合、key は、
          レコード (行) 番号が使われます。

     DB_File は、どのようにバークレイ DB とやり取りを行なうのでし
     ょうか。

     DB_File は、Perl 5 の tie() 機構を使ってバークレイ DB ファイ
     ルをアクセスします (詳しくは、perlfunc manpage の tie() の項
     を参照してください)。 この機能によって、DB_File はバークレ
     イ DB ファイルを (DB_HASH と DB_BTREE ファイル型のため) 連想
     配列でも、(DB_RECNO ファイル型のため) 通常の配列でもアクセス
     することができます。

     tie() インタフェースに加えて、バークレイ DB API で用意されて
     いるほとんどの関数を使うことができます。

     バークレイ DB との違い

     バークレイ DB では、データベースをオープンしたり、生成したり
     するのに dbopen() 関数を使います。 以下は、dbopen() の C プ
     ロトタイプです。

           DB*
           dbopen (const char * file, int flags, int mode,
                   DBTYPE type, const void * openinfo)

     パラメータ type は、三つのインタフェース手法 (DB_HASH、
     DB_BTREE、DB_RECNO) のどれが使われるかを示す列挙型です。 こ
     のどれを選ぶかによって、最終パラメータ openinfo が、特定のイ
     ンタフェース手法の合わせたデータ構造を指します。

     このインタフェースは、DB_File では、多少異なった形で扱われま
     す。 DB_File を使った呼び出しは、以下のようになります。

             tie %array, DB_File, $filename, $flags, $mode, $DB_HASH ;

     パラメータ filename と flags と mode は、dbopen() のものと同
     じです。 最終パラメータ $DB_HASH は、dbopen() のパラメータ
     type と openinfo の両方の役割を果たすものとなります。

     たとえば、上記の $DB_HASH は、実際にはハッシュオブジェクトへ
     のリファレンスです。 DB_File には、あらかじめ定義された三つ
     のリファレンスがあります。 $DB_HASH の他に、$DB_BTREE と
     $DB_RECNO が定義されています。




Perl module manpages Last change: Release 5.0 Patchlevel 00     2






DB_FILE(3)               USER COMMANDS                 DB_FILE(3)



     これらのあらかじめ定義されたリファレンスで許される key は、
     同値な C の構造体で使われている名前に限られます。 これは、
     たとえば、リファレンス $DB_HASH では、bsize、cashesize、
     ffactor、hash、lorder、nelem という key だけが許されます。

     これらの要素のいずれかの変更を行なうには、

             $DB_HASH{cachesize} = 10000 ;

     のように代入するだけです。

     RECNO

     RECNO をより Perl とコンパチブルにするために、すべての RECNO
     配列の配列オフセットをバークレイ DN のように 1 とするのでは
     なく、0 から始めるようにしています。

     メモリ内データベース

     バークレイ DB では、ファイル名の場所に NULL (これは、C の
     (char *)0 です) を使うことによって、メモリ内データベースが作
     れます。 DB_File で、この機能を使うには、NULL の代わりに
     undef を使います。

     バークレイ DB インタフェースを直接使う

     結合されたハッシュや配列を使ったバークレイ DB のアクセスはも
     ちろん、バークレイ DB のドキュメントに定義された、ほとんどの
     関数を直接使うことも可能です。

     そのためには、tie からの返却値を覚えておく必要があります。

             $db = tie %hash, DB_File, "filename"

     一旦これを行なえば、バークレイ DB API を直接アクセスすること
     ができます。

             $db->put($key, $value, R_NOOVERWRITE) ;

     dbx(3X) manapge で定義されている関数は、close() と dbopen()
     を除いて使用可能です。 これらの関数への DB_File インタフェ
     ースは、バークレイ DB の動作をまねるようにインプリメントされ
     ています。 特に、すべての関数は、ステータス値だけを返すこと
     に注意しなくてはなりません。 バークレイ DB 関数が、パラメー
     タを介してデータを返すときには、DB_File の方も全く同じことを
     行ないます。

     dbopen manpage で定義されている定数も、すべて利用可能です。







Perl module manpages Last change: Release 5.0 Patchlevel 00     3






DB_FILE(3)               USER COMMANDS                 DB_FILE(3)



     以下に利用可能な関数をあげます。

     get  flags パラメータが省略可であることを除いて、recno での
          場合と同じです。 要求した key に伴う value は、$value
          パラメータに返されます。

     put  通常どおり、flags パラメータは省略可。

          flags に R_IAFTER か R_IBEFORE を使っていれば、key パラ
          メータは、挿入する key/value ペアのレコード番号が設定さ
          れます。

     del  flags パラメータは省略可。

     fd   recno と同じ。

     seq  flags パラメータは省略可。

          key パラメータと value パラメータ両方が設定されます。

     sync flags パラメータは省略可。

EXAMPLES
     実例を見た方が、理解しやすいことでしょうから、ここにいくつか
     示すことにします。

     HASH を使う

             use DB_File ;
             use Fcntl ;

             tie %h,  DB_File, "hashed", O_RDWR|O_CREAT, 0640, $DB_HASH ;

             # key/value をファイルに追加する
             $h{"apple"} = "orange" ;

             # key の存在を確認する
             print "Exists\n" if $h{"banana"} ;

             # 削除
             delete $h{"apple"} ;

             untie %h ;


     BTREE を使う

     次は、BTREE を使った実例です。 少しでも興味あるものとするだ
     けのために、デフォルトの比較ルーティンを使わないようにしまし
     た。 代わりに Perl のサブルーティン Compare() で、大文字小
     文字を区別しない比較を行なっています。




Perl module manpages Last change: Release 5.0 Patchlevel 00     4






DB_FILE(3)               USER COMMANDS                 DB_FILE(3)



             use DB_File ;
             use Fcntl ;

             sub Compare
             {
                 my ($key1, $key2) = @_ ;

                 "\L$key1" cmp "\L$key2" ;
             }

             $DB_BTREE->{compare} = 'Compare' ;

             tie %h,  DB_File, "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE ;

             # key/value ペアをファイルに追加する
             $h{'Wall'} = 'Larry' ;
             $h{'Smith'} = 'John' ;
             $h{'mouse'} = 'mickey' ;
             $h{'duck'}   = 'donald' ;

             # 削除
             delete $h{"duck"} ;

             # key を一通り巡って、順に出力します。
             # btree では、自動的に順番に並べられますので、key の
             # sort は必要ないことに注意
             foreach (keys %h)
               { print "$_\n" }

             untie %h ;

     以下は、上記の出力です。

             mouse
             Smith
             Wall



















Perl module manpages Last change: Release 5.0 Patchlevel 00     5






DB_FILE(3)               USER COMMANDS                 DB_FILE(3)



     RECNO を使う

             use DB_File ;
             use Fcntl ;

             $DB_RECNO->{psize} = 3000 ;

             tie @h,  DB_File, "text", O_RDWR|O_CREAT, 0640, $DB_RECNO ;

             # key/value ペアをファイルに追加する
             $h[0] = "orange" ;

             # key の存在を確認する
             print "Exists\n" if $h[1] ;

             untie @h ;


WARNINGS
     このモジュールのソースに定義されている関数で、このドキュメン
     トに書かれていないものがあれば、注意してください。 すぐに、
     捨ててしまったかもしれません。

     もし、そういったものが見つからなければ、探し方が悪いか、時間
     が経って、破棄してしまったものです。

BUGS
     バージョンの古いバークレイ DB では、RECNO ファイル形式を使っ
     た固定長レコードに問題がありました。 このマニュアル執筆時点
     での最新バージョンは 1.85 で、この RECNO の問題は回避されて
     いるようです。

     コードにバグがあることは、間違いありません。 お気付きの点、
     拡張のご意見があれば、コメントをお待ちしています。

AVAILABILITY
     バークレイ DB は、ftp.cs.berkeley の /ucb/4bsd/db.tar.gz デ
     ィレクトリに納められているものが入手できます。 これは、GPL
     に従うものでは *ありません*。

SEE ALSO
     perl(1) manpage、dbopen(3) manpage、hash(3) manpage、recno(3)
     manpage、btree(3) manpage

     バークレイ DB は、ftp.cs.berkeley.edu の /ucb/4bsd ディレク
     トリから入手できます。

AUTHOR
     DB_File インタフェースは、Paul Marquess
     <pmarquess@bfsec.bt.co.uk> によって書かれました。 DB システ
     ム自身についての疑問は、Keith Bostic <bostic@cs.berkeley.edu>
     へ知らせると良いでしょう。



Perl module manpages Last change: Release 5.0 Patchlevel 00     6