Last updated: 12/22/2002 Top ドキュメントTop

データベース管理システム 管理者用ガイド
データ定義ファイル

概要

データベースに関する情報やアプリケーションの細かな動作などを 定義するためのファイルです。require で呼び出されるため、 ファイルの最後は "1;" で終わる必要があります。

configure サブルーチン

ファイルの中で configure サブルーチンを定義し、 その中で設定を記述する必要があります。

configure サブルーチンは、グループ名を引数として受け取り、 各種設定が記述されたハッシュへのリファレンスを返すものとします。

大雑把な形式は次のようになります。

sub configure { my $group = shift; my $self = { };
$self->{debug} = { ... };
$self->{global} = { ... };
...
return $self; }

詳細については、サンプルを参照してください。

以下に、各項目の概要や型を示します。 (必須) と書かれたものは、 必ず設定する必要があります。 必須でない項目を省略した場合は、デフォルト値が適用されます。 デフォルト値が記されていない場合は undef が適用されます。

$self->{debug}: デバッグの設定

デバッグ時に主に有用な設定です。
$self->{debug}{no_mail} => BOOLEAN
true ならばメールを送りません。
$self->{debug}{maintenance} => BOOLEAN
true ならばメンテナンスモードで動きます。
$self->{debug}{maintenance_except_addr} => REGEX
メンテナンス対象外となる IP のパターンです。 $ENV{REMOTE_ADDR} がこの値とマッチするアクセス元は、 メンテナンスモードではない通常のモードで動きます。
$self->{debug}{maintenance_msg} => STRING
メンテナンス用のテンプレートファイル中で $nvar{maintenance_msg} として参照できる文字列です。
$self->{debug}{no_db} => BOOLEAN
true ならばデータベースに全く接続をしません (多くの機能は正しく動作しません)。
$self->{debug}{no_db_commit} => BOOLEAN
true ならばデータベースには接続しますが、 トランザクションを rollback します (データベースへの挿入が行われません)。
$self->{debug}{no_data_error} => BOOLEAN
true ならばデータをチェックする際、 データ定義ファイルの設定によるエラーをエラーとはみなさず、 警告とみなします。
$self->{debug}{check_conf} => CODE
DBIPgSystem::DB::test_conf メソッドから呼び出されるコードです。 dbipg_test_conf の実行時(通常 make test の実行時) にチェックしたいアルゴリズムがあれば記述してください。 テストを失敗させる場合はコード中で die を呼び出してください。

$self->{global}: 全般的な設定

基本的な設定

$self->{global}{primary} => STRING (必須)
主テーブルのテーブル名です。
$self->{global}{basedir} => STRING (必須)
ベースディレクトリ(各種定義ファイルやテンプレートファイル、 ログファイルなどが置かれているディレクトリ)です。 絶対パスで記述してください。以下、basedir と呼びます。
$self->{global}{tmpdir} => STRING (必須)
テンポラリファイルが生成されるディレクトリです。 basedir からの相対パスで記述してください。
$self->{global}{errorcode_file} => STRING (必須)
エラーメッセージ定義ファイルです。 basedir からの相対パスで記述してください。
$self->{global}{groups} => HASHREF (必須)
グループ名の一覧です。通常は "'グループ名' => 1" のように 記述してください。値が false の場合は、 対応するグループは無効とみなされます。
$self->{global}{staff} => HASHREF (必須)
事務局権限を持つグループです。キーがグループ名、値が BOOL値で、 値が true ならば有効です。
$self->{global}{baseuri} => HASHREF (必須)
CGIファイルやHTMLファイルが置かれるディレクトリに対応する URIです。 キーがグループ名です。

文字コードの設定

$self->{global}{html_charset} => STRING or HASHREF (必須)
HTML のデフォルトの文字コードです。 日本語の場合 Shift_JIS または x-sjis と指定すると、 機種依存文字を適切に変換する機能が働きます。 HASHREF での指定の場合は、キーがグループ名です。
$self->{global}{code_dist} => STRING or HASHREF (必須)
文字コードの識別のために使う文字列です。 通常、HTML からフォームを通してパラメータを送る場合、 code_dist の値も一緒に送るように テンプレートファイル等を記述しておくべきです。 HASHREF での指定の場合は、キーがグループ名です。
$self->{global}{code} => STRING or HASHREF (必須)
文字コードの識別のために使うハッシュへのリファレンスです。 HASHREF の場合、キーが $self->{global}{code_dist} を ブラウザから受け取ったときの文字列、値がその場合の文字コードを表します。 空文字列のキーで、デフォルトの文字コードを指定します。 STRING の場合は code_dist の値に関係なく、 指定した文字コードとみなされます。
$self->{global}{code_invalid} => STRING (必須)
データ中に含まれる不適切な文字コード (例えば使用禁止の制御文字やIBM拡張文字など)が、 この文字列に置換されます。

メールの送信に関する設定

$self->{global}{sendmail} => STRING (必須)
sendmail プログラムの絶対パスです。 sendmail プログラムでは -i, -t, -f のオプションが使える必要があります。
$self->{global}{mailfrom} => STRING (必須)
送信元のメールアドレスです。メールアドレスを直接記入するか、 '名前 <address>' の形で記入してください。 後者の記法の場合、'名前' と '<' の間には必ず空白文字を入れてください。 '名前' の箇所には日本語を記入することができます。
$self->{global}{mailto} => STRING (必須)
システムからスタッフにメールを送るときの送信先です。 メールアドレスのみを記述してください。
$self->{global}{mail_charset} ||= 'ISO-2022-JP' => STRING
メールのデフォルトの charset です。 通常は 'ISO-2022-JP' または 'US-ASCII' で指定してください。

データベースの設定

$self->{global}{db}{data_source} => STRING (必須)
データベースの datasource です。 DBI::connect の最初の引数になるべき文字列から、 先頭の 'dbi:Pg:' の文字列を除いた値を記述します。 詳細は DBI モジュールを参照してください。
$self->{global}{db}{username} => STRING (必須)
データベースのユーザ名です。
$self->{global}{db}{passwd} => STRING (必須)
データベースのパスワードです。

ユーザ情報の設定

$self->{global}{userinfo} は undef にすることもできます。 定義をする場合は、$self->{global}{userinfo}{col_user} と $self->{global}{userinfo}{col_email} を必ず記入してください。

$self->{global}{userinfo}{join} => STRING
ユーザ情報を取得するときのSELECT文に、JOIN句が必要ならば記述します。
$self->{global}{userinfo}{col_user} => STRING
ユーザ名に対応するカラムです。
$self->{global}{userinfo}{col_email} => STRING
E-mailに対応するカラムです。
$self->{global}{userinfo}{init} => HASHREF
レコード挿入時の初期値です。 キーが sys_userinfo テーブルのカラム名です。 DBIPgSystem::DB::insert_userinfo メソッドを参照してください。
$self->{global}{userinfo_default} => HASHREF
UIDが与えられなかった場合のデフォルト値です。 キーが sys_userinfo テーブルのカラム名です。

詳細表示の画面のエクスポートに関する設定

$self->{global}{export} => HASHREF (必須)
詳細表示のHTMLを書き出すか否かを表すフラグです。 キーがグループ名です。 値が true ならば、対応するグループの詳細表示のHTMLを書き出します。 値が true のときは、$self->{global}{export_file} と $self->{global}{export_uri} の対応する値を必ず記述してください。
$self->{global}{export_file} => HASHREF
エクスポート先のファイル名です。 キーがグループ名です。絶対パスで記述してください。
$self->{global}{export_uri} => HASHREF
エクスポート先のディレクトリのURIです。キーがグループ名です。

フォームからのデータの挿入に関する設定

$self->{global}{insert_mail} => CODE
送信するメールの内容を生成します。 引数は (データ, システム情報) とし、 戻り値は (送信するメールのタイトル, メールの本文) とします。

ファイルからのデータの挿入に関する設定

$self->{global}{enable_file_insert} => BOOLEAN
true ならばファイルからのデータの挿入を受け付けます。
$self->{global}{file_allow_short_col} => BOOLEAN
true ならばファイルの各行のカラム数が不足している場合を許可します。
$self->{global}{file_maxnumerr} => INTEGER
表示できる(DBIPgSystem::DB モジュールが記憶しておくことのできる) エラーや警告の数の上限です。

ファイル型の設定

各カラムの設定($self->{db}, 後述)で、type が 'file' のカラムが ひとつでもある場合、ファイル型に関する以下の項目の全てを 設定する必要があります。 さもなければ、$self->{global}{filetype} は undef でなければいけません。 ファイル型の詳細については、ファイル型 をご覧ください。

$self->{global}{filetype}{dir} => STRING
アップロードされるファイルを格納するディレクトリ名です。 絶対パスで記述してください。
$self->{global}{filetype}{pooldir} => STRING
オリジナルのファイルを格納するディレクトリ名です。
$self->{global}{filetype}{tmpdir} => STRING
アップロードされるファイルを一時的に格納するディレクトリ名です。 ファイルの挿入時で処理が完了するまでの間はここに保管されます。 絶対パスで記述してください。
$self->{global}{filetype}{mode} => NUM
ファイルを管理するときのモードです。 chmod 関数に渡すことのできるような 8進数の数字で記述してください。
$self->{global}{filetype}{fileuri} => STRING
$self->{global}{filetype}{dir} に対応する URIです。
$self->{global}{filetype}{tmpfileuri} => STRING
$self->{global}{filetype}{tmpdir} に対応する URIです。

その他の雑多な設定

$self->{global}{searchnum} ||= 50 => INTEGER
検索結果で同時に表示できる件数のデフォルト値です。
$self->{global}{session_time_limit} => STRING
セッションの有効期限です。最後のアクセスから、 指定された時間が経過したセッションへのアクセスを拒否します。 '1 day', '2 hours' のように PostgreSQL の INTERVAL型で記述してください。 (詳しくは、PostgreSQL のドキュメントを参照してください。) 指定がない場合は有効期限がないものとみなされます。

$self->{template}: テンプレートファイルの設定

$self->{template} の設定でファイル名を指定する箇所は、 全て拡張子 '.html' を省いたものを記述してください。 必須と書かれていない項目も、実際には必須であることが多いと思います。

$self->{template}{dir} => HASHREF (必須)
テンプレートファイルが置いてあるディレクトリです。 キーがグループ名です。 テンプレートファイルは全てこのディレクトリに置いてください。
$self->{template}{decoded} => BOOLEAN
テンプレートファイルを予めデコードしておく場合は true、 そうでなければ false にしてください。 この値が true の場合はやや高速に動くはずですが、 この場合はテンプレートファイルの編集後に dbipg_install (通常は make install)などでデコードする必要があります。
$self->{template}{fatalerror} => STRING (必須)
致命的エラーが起こった場合に参照されるテンプレートファイルです。
$self->{template}{error} => STRING (必須)
エラーが起こった場合に参照されるテンプレートファイルです。
$self->{template}{maintenance} => STRING (必須)
メンテナンスモードのときに参照されるテンプレートファイルです。
$self->{template}{search} => HASHREF (必須)
検索後に参照されるテンプレートファイルです。 DBIPgSystem::search メソッド で利用されます。 キーは、同メソッドの html パラメータに対応します。 キー 'default' の値は必ず記述してください。 検索を行わないアプリケーションでは未定義値とすることもできますが、 この場合は "$self->{template}{search} = undef" のように明記してください。
$self->{template}{detail} => STRING (必須)
詳細表示用のテンプレートファイルです。 DBIPgSystem::search_detail メソッド 等で利用されます。 詳細表示用のHTMLが複数ページから成るときは、 通常文字列中に '^p' を含む必要があります。 '^p' を 2桁のページ番号に展開した文字列がファイル名とみなされます。 これらのテンプレートがエクスポートの対象となります。 詳細表示を行わないアプリケーションでも $self->{template}{detail} に値が格納されていなければいけません(未定義値でも可)。 またこの場合は、$self->{template}{numpage_detail} の対応する値は 0 でなければいけません。
$self->{template}{numpage_detail} => HASHREF (必須)
詳細表示の画面のページ数です。キーがグループ名です。
$self->{template}{detail_other} => HASHREF
$self->{template}{detail} 以外の、 詳細表示用のテンプレートファイルです。 この値で示されたテンプレートは、$self->{template}{detail} の場合とは違い、エクスポートの対象外になります。 DBIPgSystem::search_detail メソッド で利用されます。 キーは、同メソッドの html パラメータに対応します。
$self->{template}{insert} => HASHREF
フォームからのデータ追加/修正用のテンプレートファイルです。 DBIPgSystem::data_check メソッド 等で利用されます。 フォームからのデータ追加/修正のHTMLが複数ページから成るときは、 通常文字列中に '^p' を含む必要があります。 '^p' を 2桁のページ番号に展開した文字列がファイル名とみなされます。
$self->{template}{numpage_insert} => NUM (必須)
フォームからのデータ追加/修正の画面のページ数です。 フォームからデータ追加/修正を行わない場合は 0 としてください。 さもなければページ数を記述し、 $self->{template}{insert}, $self->{template}{insert_verify}, $self->{template}{insert_success} を必ず記述してください。
$self->{template}{insert_verify} => STRING
フォームからのデータ追加/修正での確認用のテンプレートファイルです。 DBIPgSystem::data_check メソッド で利用されます。
$self->{template}{insert_success} => STRING
フォームからのデータ追加/修正で、 挿入が完了したときに参照されるテンプレートファイルです。 DBIPgSystem::data_insert メソッド で利用されます。
$self->{template}{remove} => HASHREF (必須)
データの削除のときに参照されるテンプレートファイルです。 DBIPgSystem::remove_data メソッド で利用されます。 キーは、'verify' と 'noverify' で、 それぞれ確認時、完了時に参照されるテンプレートに対応しています。 データの削除を行わないアプリケーションでは未定義値とすることもできますが、 この場合は "$self->{template}{remove} = undef" のように明記してください。
$self->{template}{file_head} => STRING
ファイルからのデータ追加/修正で、 途中経過を出力する場合に参照されるテンプレートファイルです。 DBIPgSystem::file_check メソッド 等で利用されます。 $self->{global}{enable_file_insert} が true の場合は、 必ず記述してください。
$self->{template}{file_verify} => STRING
ファイルからのデータ追加/修正での確認用のテンプレートファイルです。 DBIPgSystem::file_check メソッド で利用されます。 $self->{global}{enable_file_insert} が true の場合は、 必ず記述してください。
$self->{template}{file_success} => STRING
ファイルからのデータ追加/修正で、 挿入が完了したときに参照されるテンプレートファイルです。 DBIPgSystem::file_insert メソッド で利用されます。 $self->{global}{enable_file_insert} が true の場合は、 必ず記述してください。
$self->{template}{file_cancel} => STRING
ファイルからのデータ追加/修正で、 挿入をキャンセルしたときに参照されるテンプレートファイルです。 DBIPgSystem::file_insert メソッド で利用されます。 $self->{global}{enable_file_insert} が true の場合は、 必ず記述してください。

$self->{log}: ログファイルの設定

$self->{log} の各要素の値は、ログを残すファイル名を表し、 $self->{global}{basedir} からの相対パスの形で記述すべきです。 値に含まれている '^Y', '^y', '^m', '^d', '^h' の文字列は、それぞれ、 ログがとられるときの 年(4桁), 年(2桁), 月(2桁), 日(2桁), 時間(2桁) に置換されます。

$self->{log}{basefile} と $self->{log}{Fatal} は設定すべきです。 それ以外に、$self->{log} にログの種類に対応するキーに値が定義されていれば、 その種類のログはそちらに記述されます。 例えば、$self->{log}{DataError} にファイル名を指定すると、 そのファイルに DataError のログが書き出されます。 また、対応するキーの値が undef の場合は、ログを残しません。

詳細は DBIPgSystem::DB::add_log メソッド を参照してください。

$self->{log}{basefile} => STRING (必須)
ログを残すファイル名のデフォルトです。 ログの種類と同じ名前のキーが存在しないときは、 全てこのハッシュの値が使われます。
$self->{log}{Fatal} => STRING (必須)
致命的なエラーのためのログをとるファイル名です。

DBIPgSystem::DB モジュールの各メソッド別の設定

$self->{__infilter}{codelist} => HASHREF
キーの文字列が対応する値に置換されます。 キーが日本語でないものは無視されます。
$self->{__infilter}{hook} => CODE
DBIPgSystem::DB::infilter メソッドの最後に呼び出されます。 詳しくは DBIPgSystem::DB::infilter メソッドのソースをご覧ください。
$self->{__search_detail}{hook_detail} => CODE
DBIPgSystem::DB::search_detail メソッドで引数 revise が true の場合に 最後に呼び出されます。 引数は (データ, システム情報) とし、 フォームからのデータの修正の直前にこれらの値を変更することができます。 詳しくは DBIPgSystem::DB::search_detail メソッドのソースをご覧ください。
$self->{__remove_data}{hook} => CODE
DBIPgSystem::DB::remove_data メソッドの最初に呼び出されます。 ただし、同メソッドの変数 $qs_prim が定義されていなければ呼び出されません。 詳しくは DBIPgSystem::DB::remove_data メソッドのソースを ご覧ください。

$self->{deny}: チェック

$self->{deny}{data_verify_check} => CODE
フォームからのデータの挿入で、確認画面に移動する直前にチェックを 行いたい場合に利用されます。 引数は (データ, 修正元のデータのシステム情報, システム情報, データの修正) とし、戻り値はエラーコードを表す文字列 (エラーがなければ undef)とします。 戻り値が undef でなければ、確認画面には移動せず、 対応するエラーを出力して挿入画面に戻るように処理されます。 引数の 'データの修正' には、修正ならば true、 さもなければ false が格納されています。
$self->{deny}{data_insert} => CODE
フォームからのデータの挿入で、実際にデータベースに挿入する直前に チェックを行いたい場合に利用されます。 引数は (データ, 修正元のデータのシステム情報, システム情報, データの修正) とし、戻り値はエラーコードを表す文字列 (エラーがなければ undef)とします。 戻り値が undef でなければ、データの挿入を行わず、 対応するエラーを出力して挿入画面に戻るように処理されます。 引数の 'データの修正' には、修正ならば true、 さもなければ false が格納されています。

$self->{db}{sql_*}: 検索用の設定

$self->{db}{sql_join} => HASHREF
DBIPgSystem::search メソッド の join パラメータを通して 利用される値です。
$self->{db}{sql_cols} => HASHREF (必須)
DBIPgSystem::search メソッド の cols パラメータを通して 利用される値です。
$self->{db}{sql_default_order} => STRING (必須)
検索時の ORDER句のデフォルト値です。

$self->{db}{alias}: カラム名の別名

$self->{db}{alias}{$dbt} => HASHREF
カラム名の別名です。検索時に左辺値として利用できます。 $dbt はテーブル名です。 キーがカラム名、値が STRING で、 複数の別名を指定する場合は複数の値を "\n" で区切ります。

$self->{code}: コードの設定

$self->{code}{$codename} => HASHREF
$self->{db}{col}[*]{code} で利用されるコードです。 $codename はコード名です。 コードと対応する値を HASHREF の形式で記述してください。

$self->{misc}: 各アプリケーションが自由に使える領域の設定

$self->{misc} は、 各アプリケーションの管理者が自由に使える領域です。 テンプレートファイルで頻繁に使われる変数などを格納しておくと便利です。

$self->{db}: カラムの設定

全カラムに共通した設定

$self->{db}{prefilter_each} => CODE
各カラムに設定された値が最初に通るフィルタです。 引数はカラムの値へのリファレンス、戻り値はなしとし、 参照先の値を直接変更する形で記述してください。
$self->{db}{filter_all}{$dbt} => CODE
各カラムのチェックを終えた後でカラム全体が通るフィルタです。 $dbt はテーブル名です。 カラムの値を変更したり、エラー/警告を出すために利用でき、 通常は各カラム毎の設定では行えないような場合 (複数のカラムにわたるチェックなど)に使われます。 引数はデータを表すハッシュへのリファレンス、 戻り値は ($err, $warn) としてください。 データを表すハッシュへのリファレンスは、 キーがカラム名、値が対応する値になっています。 $err, $warn はそれぞれエラーの情報, 警告の情報で、 どちらも配列へのリファレンスです。 この各要素は、[ エラーコード, [ カラム1, カラム2, ...] ] の形をします。カラム1, カラム2, ... には、 エラーに関係のあるカラムを指定してください (エラーがどこで起こったかを表示するために使われます)。

$self->{db}{col}{$dbt}: 各カラムの設定

$self->{db}{col}{$dbt} (ARRAYREF) に各カラムの設定をします。 $dbt はテーブル名です。 要素の順番がデータベースのカラムの順番になります。

テーブル名には、英小文字 (a-z) またはアンダースコア (_) のみの文字を 使用できます。ただし、先頭と末尾は英小文字 (a-z) でなければいけません。 また、25文字程度より長い名前は受け付けられません。 さらに、'seq_', 'sys_' で始まる文字列や、'dbsession' は システムの内部で使用するため、受け付けられません。

$self->{db}{col}{$dbt}[*]{name} => STRING (必須)
データベースのカラム名です。
$self->{db}{col}{$dbt}[*]{print} => STRING (必須)
表示用の名前です。
$self->{db}{col}{$dbt}[*]{type} => STRING (必須)
データ型です。'int2', 'int4', 'int8', 'text', 'file', 'real' のいずれかを指定してください。 'file' 以外は、PostgreSQL のデータ型と同じです。 'file' についての詳細はファイル型 を参照してください。
$self->{db}{col}{$dbt}[*]{null} => STRING
空欄(空文字列または空白のみからなる文字列) が入力されたときの処理です。 'error', 'warning', 'warning:*', '', ':*' のいずかの文字列でなければなりません('*' は任意の文字列)。 'error' の場合は、空欄時にエラーを出します。 'warning:*' の場合は、空欄時に警告を出すと共に、 代わりに値 '*' を用います。 ':*' の場合は、代わりに値 '*' を用います。 'warning' や '' の場合は、代わりに null値を用います。
$self->{db}{col}{$dbt}[*]{plural} => BOOLEAN
true ならば複数の値を格納できます。 (code を用いる場合以外での使用は実験段階です。) この値を true とする場合は、type を 'text' にしてください。
$self->{db}{col}{$dbt}[*]{subst} => CODE
データを置換するためのコードです。 引数はスカラー変数へのリファレンスとし、 参照先の値を直接変更する形で記述してください。 値が undef の場合は置換を行いません。 type が 'file' の場合はファイル型 を参照してください。
$self->{db}{col}{$dbt}[*]{format} => CODE
値が満たすべきフォーマットです。 subst による置換が行われた後で入力制限のチェックが行われます。 値が undef の場合はチェックを行いません。 引数はカラムの値とし、戻り値は 'error|*', 'warn|*', undef のいずれかでなければいけません('*' はエラーコードです)。
$self->{db}{col}{$dbt}[*]{code} => ARRAYREF
参照するコード表の名前です。 対応する $self->{code} のキーが定義されていなければいけません。 複数のコードを指定できます。
$self->{db}{col}{$dbt}[*]{search} => CODE or BOOLEAN
type が 'file' 以外の場合は、 フィルタとなるサブルーチンへのリファレンスです。 値は CODE でなければいけません。 フィルタをかけられた文字列が検索用カラムに蓄えられます。 引数はカラムの値とし、戻り値は変換後の値とします。
type が 'file' の場合は、サムネイルの有無を表します。 値は BOOLEAN でなければいけません。
$self->{db}{col}{$dbt}[*]{stype} => STRING
検索用カラムのデータ型です。 'int2', 'int4', 'int8', 'text', 'file', 'real' のいずれかを 指定してください。 'file' 以外は、PostgreSQL のデータ型と同じです。 type が 'file' の場合でサムネイルを利用する場合は、 stype も 'file' でなければいけません。
$self->{db}{col}{$dbt}[*]{snull} => STRING
空欄(無記入)が入力されたときの検索用カラムの値です。 '', ':*' のいずかの文字列でなければなりません('*' は任意の文字列)。 また、空欄をエラーにせず、かつ検索用カラムを使うときは、 必ず値を指定しなければいけません。 ':*' の場合は、代わりに値 '*' を使用します。 '' の場合は、代わりに null値を使用します。
$self->{db}{col}{$dbt}[*]{nosearch} => BOOLEAN
true の場合は検索時に左辺値として利用できません。 ただし、対応する検索用カラムがあれば、 検索用カラムは左辺値として利用できます。

補足説明

各アプリケーション別のサブルーチン定義

テンプレートファイルで頻繁に使われるサブルーチンを、 データ定義ファイル内で定義をすることができます。 (もちろん、テンプレートファイルから require などを利用して、 独自の方法でサブルーチン呼び出しを行うなどの、 他の手もあります。)

例えば、configure サブルーチンの定義の後に、 次のように新たなパッケージを用意して、 サブルーチンを定義してください。

package DBIPgConf;
sub subroutine1 { ...
}

補足説明