postgresql/src/backend/utils/mb/conversion_procs

新しいエンコーディング変換関数の追加方法

	2006/04/15 Tatsuo Ishii

はじめに

PostgreSQLには，データベースとフロントエンドのエンコーディングが異なる
ときに，自動的にエンコーディングの変換を行う機能があります．このディレ
クトリには，そのときに使われる関数が登録されています．これらの関数はユー
ザ定義C関数として，initdbの中で登録されます．具体的には，
/usr/local/pgsql/share/conversion_create.sql の中で登録されます(このファ
イルはこのディレクトリでmakeしたときに自動生成されます)．

また，これらの関数はconvert()関数からも呼び出されることもあります．

このREADMEでは，C関数を定義する方法と，それをMakefileなどに追加する方
法を説明します．

o C関数の呼び出し形式

  エンコーディング変換関数の呼び出し形式は次のようになります．

  conv_proc(
	INTEGER,	-- source encoding id
	INTEGER,	-- destination encoding id
	CSTRING,	-- source string (null terminated C string)
	INTERNAL,	-- destination string (null terminated C string)
	INTEGER		-- source string length
  ) returns VOID;

  唯一の出力引数は4番目のdestination stringです．ユーザ定義関数は必要
  なメモリをpallocし，そこに変換結果をNULLターミネートされたC文字列と
  して出力しなければなりません．また，適切な大きさのメモリを確保するの
  は，このC関数の責任です．というのは，一般に変換された文字列の長さは
  ソース文字列の長さ(5番目の引数で指定されます．単位はNULLターミネート
  を含まないバイト数です)とは一致しないからです．

  エンコーディングIDはinclude/mb/pg_wchar.hのtypedef enum pg_encで定義
  されています．

o 関数の登録とコンパイル

  作ったC関数はサブディレクトリを作り，その中に納めます．その中に
  Makefileも必要になりますが，他のディレクトリにあるMakefileを参考にす
  れば簡単に作成できるでしょう．

  次にメインのMakefile(このファイルが置いてある同じディレクトリにあり
  ます)に関数に関する記述を追加します．

  (1) DIRS=の後にサブディレクトリ名を追加します．

  (2) @set \ で始まる項目に記述を追加します．1関数につき1行の追加が必要
    です．

    コンバージョンの名前
    ソースエンコーディング名
    デスティネーションエンコーディング名
    関数名
    オブジェクトファイル名

    を1行の中にスペースで区切って追加します．

o テスト

  以上が終わったら，このファイルがあるディレクトリでmakeし，すべてがう
  まくいくことを確認します．特に，create_conversion.sqlがちゃんとした
  内容になっているかどうか確認しましょう．良さそうだったら，テスト用に
  新しいデータベースを作り，そこでこのスクリプトを実行します．

  $ psql -e -f create_conversion.sql test

  これも正常だったら，最後にregression test suiteにテスト項目を追加し
  てください．具体的には，src/test/regress/sql/conversion.sqlに追加し，
  regression testを行います．

o 注意事項

  デフォルトのエンコーディング変換として使用できるためには，ソースエン
  コーディングとデスティネーションエンコーディングの間で双方向の変換が
  できることが必要です．すなわち，あるエンコーディングのペアに付き，2
  個の関数の作成が必要です．これらの関数は別々のサブディレクトリに登録
  しても良いですが，通常は一つのソースファイル中に2個の関数を書くこと
  が多いでしょう．