Specifications of CGI Scripts of QDBM (Japanese)
Author: Mikio Hirabayashi
Description: specifications of CGI of QDBM
Keywords: QDBM, DBM, database, CGI

# QDBM付属CGIスクリプト仕様書

Copyright (C) 2000-2006 Mikio Hirabayashi
Last Update: Thu, 26 Oct 2006 15:00:20 +0900
[English]

## 目次

1. 概要
2. ビルド
3. データベース管理用CGIスクリプト
4. ファイルアップロード用CGIスクリプト
5. 全文検索用CGIスクリプト
6. Webサーバの設定

## 概要

ユーティリティもしくはアプリケーションのサンプルとして、QDBMのパッケージには三つのCGIスクリプトが付属する。第一はDepotとCuriaとVillaのデータベースファイルを管理するものである。第二はCabinのユーティリティを用いてファイルのアップロードを行うものである。第三はOdeumのデータベースを用いて全文検索を行うものである。

## ビルド

Webサーバ上でCGIが利用でき、QDBMが `/usr/local' 以下にインストールされていることが必要である。

インストール作業は、サブディレクトリ `cgi' をカレントディレクトリにして行う。

    cd cgi

ビルド環境を設定する。

    ./configure

プログラムをビルドする。

    make

プログラムをインストールする。作業は `root' ユーザで行う。

    make install

一連の作業が終ると、以下のファイルがインストールされる。その他にも文書が `/usr/local/share/qdbm/cgi' にインストールされる。

    /usr/local/libexec/qadm.cgi
    /usr/local/libexec/qupl.cgi
    /usr/local/libexec/qfts.cgi
    /usr/local/share/qdbm/cgi/qadm.conf
    /usr/local/share/qdbm/cgi/qupl.conf
    /usr/local/share/qdbm/cgi/qfts.conf

以下の各セクションの指示に従って、利用するCGIスクリプトとその設定ファイルをWWWに公開されたディレクトリにコピーする。

## データベース管理用CGIスクリプト

`qadm.cgi' は、DepotとCuriaとVillaのデータベースを管理するためのCGIスクリプトである。これを使うと、WWWを介してデータベースの管理を行うことができる。レコードのキーと値は文字列であるものとする。Villaの比較関数は辞書順である。利用できる操作は、データベースの一覧、データベースの作成、データベースの削除、データベースのダウンロード、レコードの一覧、レコードの追加、およびレコードの削除である。

`qadm.cgi' のインストールは次の手順に従う。CGIが利用できるディレクトリに `qdbm.cgi' と `qadm.conf' をコピーする。また、同じディレクトリの直下に `qadmdir' という名前のディレクトリを作成する。例えば、CGIを置くディレクトリが /home/mikio/public_html の場合、以下のようにする。

    cd /home/mikio/public_html
    cp /usr/local/libexec/qadm.cgi .
    cp /usr/local/share/qdbm/cgi/qadm.conf .
    mkdir qadmdir

`qadmdir' ディレクトリは `qadm.cgi' のプロセスが読み書きおよび実行できるパーミッションである必要がある。最も簡単には、以下のようにする。他にも、CGIスクリプトにsetuidビットを立てたり、いわゆるsuExecのような機能を用いる方法もある。

    cd /home/mikio/public_html
    chmod 1777 qadmdir

`qadm.conf' は設定ファイルである。デフォルトでは以下のような内容を持つが、ユーザが任意に修正することができる。

    encoding: UTF-8
    lang: en
    title: Administration CGI
    datadir: qadmdir
    keychop: true
    valchop: false

`encoding' はCGIスクリプトによって表示されるページおよびデータベースファイル内のレコードの文字コードを指定する。`lang' は表示されるページの言語を指定する。`title' は表示されるページのタイトルを指定する。`datadir' はデータベースファイルが格納されるディレクトリのパスを指定する。`keychop' と `valchop' は、レコードのキーと値の内容を正規化するか否かを指定する。`true' の場合は、末尾の空白を取り除き、かつ改行コードが内容に含まれないようにする。

設置された `qadm.cgi' のURLにWebブラウザを用いてアクセスする。あとは、表示された案内にしたがってデータベースの管理を行えばよい。

自動化されたエージェントがデータベースに登録されたレコードを検索するために、URLで直接レコードを指定し、その値の内容そのものをプレーンテキストとして取得する機構もある。例えばCGIスクリプトのURLが `http://a.b.c/qadm.cgi' であり、`staff' という名前のデータベースに格納された `mikio' というキーのレコードの値を取り出すには、エージェントは `http://a.b.c/qadm.cgi/staff/mikio' を参照すればよい。すなわち、CGIスクリプトのURLの後ろに、`/' で区切ってデータベース名（接尾辞は不要）とキーを指定すればよい。

既存のデータベースファイルを管理対象にしたい場合は、`qadmdir' ディレクトリの中にそれを置けばよい。ただし、Depotによるデータベースファイルの名前には接尾辞として `.dp' をつけ、Curiaによるデータベースディレクトリの名前には接尾辞として `.cr' をつけ、Villaによるデータベースファイルの名前には接尾辞として `.vl' をつける必要がある。例えば `foo.dp'、`bar.cr'、`baz.vl' などとする。また、各データベースファイルまたはディレクトリはCGIスクリプトのプロセスによって読み書き可能である必要がある。

## ファイルアップロード用CGIスクリプト

`qupl.cgi' は、Cabinを使ってファイルをアップロードするためのCGIスクリプトである。これを使うと、Webサーバに任意のファイルをアップロードすることができる。ファイルのダウンロードや削除も可能である。

`qupl.cgi' のインストールは次の手順に従う。CGIが利用できるディレクトリに `qupl.cgi' と `qupl.conf' をコピーする。また、同じディレクトリの直下に `qupldir' という名前のディレクトリを作成する。例えば、CGIを置くディレクトリが /home/mikio/public_html の場合、以下のようにする。

    cd /home/mikio/public_html
    cp /usr/local/libexec/qupl.cgi .
    cp /usr/local/share/qdbm/cgi/qupl.conf .
    mkdir qupldir

`qupldir' ディレクトリは `qupl.cgi' のプロセスが読み書きおよび実行できるパーミッションである必要がある。最も簡単には、以下のようにする。他にも、CGIスクリプトにsetuidビットを立てたり、いわゆるsuExecのような機能を用いる方法もある。

    cd /home/mikio/public_html
    chmod 1777 qupldir

`qupl.conf' は設定ファイルである。デフォルトでは以下のような内容を持つが、ユーザが任意に修正することができる。

    encoding: UTF-8
    lang: en
    title: Administration CGI
    datadir: qupldir
    quota: 67108864

`encoding' はCGIスクリプトによって表示されるページおよびデータベースファイル内のレコードの文字コードを指定する。`lang' は表示されるページの言語を指定する。`title' は表示されるページのタイトルを指定する。`datadir' はアップロードしたファイルが格納されるディレクトリのパスを指定する。`quota' はアップロードできるファイルの総容量の上限を指定する。

設置された `qupl.cgi' のURLにWebブラウザを用いてアクセスする。あとは、表示された案内にしたがってファイルの管理を行えばよい。

## 全文検索用CGIスクリプト

`qfts.cgi' は、Odeumのデータベースを用いて全文検索を行うCGIスクリプトである。これを使うと、Webサイトの全文検索を行うことができる。インデックスの作成はコマンド `odidx' を用いて行い、`qfts.cgi' によってそのデータベースの検索を行う。検索方式には、指定した語を全て含む文書を検索する「AND検索」と、指定した語の少なくとも一つを含む「OR検索」がある。検索結果はスコアに応じて並べられる。

`qfts.cgi' のインストールは次の手順に従う。CGIが利用できるディレクトリに `qfts.cgi' と `qfts.conf' をコピーする。また、同じディレクトリの直下に `casket' という名前のインデックスを作成する。例えば、CGIスクリプトを置くディレクトリが /home/mikio/public_html の場合、以下のようにする。

    cd /home/mikio/public_html
    cp /usr/local/libexec/qfts.cgi .
    cp /usr/local/share/qdbm/cgi/qfts.conf .
    odidx register casket
    odidx relate casket

検索対象のディレクトリがCGIスクリプトを置くディレクトリの下にない場合は、そこに検索対象のディレクトリへのシンボリックリンクを作ればよい。

サイトの更新があった際には、以下の手順でインデックスも更新すべきである。この作業は `crontab' などを用いて自動化するとよい。

    cd /home/mikio/public_html
    odidx register casket
    odidx purge casket
    odidx relate casket
    odmgr optimize casket

`qfts.conf' は設定ファイルである。デフォルトでは以下のような内容を持つが、ユーザが任意に修正することができる。

    encoding: ISO-8859-1
    lang: en
    title: Full-text Search CGI
    index: casket
    prefix: ./
    diridx: index.html
    decuri: false
    help: <h1>Full-text Search CGI</h1>
    help: <p>Input search words into the above form and push the [Search] button.</p>
    help: <p>This is a sample application of the inverted API of QDBM.</p>

`encoding' はCGIスクリプトによって表示されるページおよびデータベースファイル内のレコードの文字コードを指定する。`lang' は表示されるページの言語を指定する。`title' は表示されるページのタイトルを指定する。`index' はインデックスのパスを指定する。`prefix' は各文書のURIにつける接頭辞を指定する。例えば `prefix' に `http://x.y.z/foo/' を指定すると、`./bar/baz.html' や `bar/baz.html' は `http://x.y.z/foo/bar/baz.html' として表示される。`diridx' はディレクトリの代表ファイルの名前を指定する。例えば `diridx' に `index.html' を指定すると、`./foo/index.html' は `./foo/' として表示される。`decuri' は、値が `true' なら、文書のURIをデコードして表現することを指示する。`help' は最初のページで表示されるヘルプメッセージを指定する。

設置された `qfts.cgi' のURLにWebブラウザを用いてアクセスする。あとは、表示された案内にしたがって全文検索を行えばよい。

インデックスを生成するコマンド `odidx' の詳細についてはQDBMの基本仕様書を参照すること。大規模なサイトのインデックスを生成する際には、サイズを小さくするために、ZLIBを有効にしてQDBMをビルドすることを検討すべきである。

## Webサーバの設定

CGIスクリプトを利用するには、WWWサーバの設定でCGIの実行を許可する必要がある。通常のコンテンツと同じ場所にCGIスクリプトを設置する場合、Apacheの設定ファイルには以下のように記述する。

    Options ExecCGI
    AddHandler cgi-script .cgi

あるいはCGIスクリプト専用のディレクトリを設ける場合、Apacheの設定ファイルには以下のように記述する。

    ScriptAlias /~mikio/cgi-bin/ "/home/mikio/public_html/cgi-bin"

WWWサーバのライブラリ検索パスに `/usr/local/lib' が含まれていない場合、それを明示的に指定する必要があるかもしれない。Apacheの設定ファイルには以下のように記述する。

    SetEnv LD_LIBRARY_PATH "/lib:/usr/lib:/usr/local/lib"

MicrosoftのIISを利用する場合、CGIスクリプトの設置場所と実行時のカレントディレクトリが異なる。後者は「仮想ディレクトリ」のルートとなるので、設定ファイルはそこに設置する必要がある。