このセクションはecpgツールの使い方を説明します。
プリプロセッサはecpgと呼ばれます。PostgreSQLのbin/ディレクトリにインストールされています。
ecpgライブラリは、libecpg.aもしくはlibecpg.soと呼ばれます。さらに、このライブラリはPostgreSQLサーバーとの通信にlibpqライブラリを使用します。よって、プログラムを-lecpg -lpqというリンクオプションを使用してリンクする必要があります。
このライブラリはいくつか"隠された"メソッドを持っていて、とても便利な場合があります。
ECPGdebug(int on, FILE *stream)――第1引数が0以外で渡された場合、デバッグログをonにします。デバッグログはstreamで実行されます。ほとんどのSQL文は引数と結果をログに出力します。
最も重要な関数ECPGdoは、拡張された文字列(たとえばすべての引数用変数が挿入されたもの)とPostgreSQLサーバーからの結果の両方をログに出力します。これはSQL文のエラーを探すのにとても便利です。
ECPGstatus() このメソッドはデータベースと接続されている場合TRUEを返し、それ以外はFALSEを返します。
PostgreSQLサーバーからのエラーを見つけるためにはファイルのincludeセクションに下記のような行を追加してください。
exec sql include sqlca;
この一文は下記のようなsqlcaという名前の構造体と変数を定義します。
struct sqlca { char sqlcaid[8]; long sqlabc; long sqlcode; struct { int sqlerrml; char sqlerrmc[70]; } sqlerrm; char sqlerrp[8]; long sqlerrd[6]; /* 0: 空 */ /* 1: 処理されたタプルの OID(あるならば) */ /* 2: INSERT、UPDATE、DELTE で処理された行数 */ /* 3: 空 */ /* 4: 空 */ /* 5: 空 */ char sqlwarn[8]; /* 0: 少なくともどれかが 'W'ならば'W' */ /* 1: 'W' ならば、少なくとも 1 つの文字列がホストの */ /* 変数に保存されるときに切りつめられている */ /* 2: 空 */ /* 3: 空 */ /* 4: 空 */ /* 5: 空 */ /* 6: 空 */ /* 7: 空 */ char sqlext[8]; } sqlca;
もし上のSQL文でエラーが発生しなかった場合、sqlca.sqlcodeが0(ECPG_NO_ERROR)になります。もしsqlca.sqlcodeが0よりも小さい場合、データベース定義が与えられた問い合わせと合わないといった深刻なエラーです。もし0より大きい場合はテーブルが要求された行を含まないといった通常のエラーです。
sqlca.sqlerrm.sqlerrmcは、エラーを説明する文字列を持っています。その文字列はソースファイルの行数で終わります。
起こり得るエラーを以下に示します。
通常は起こりません。仮想メモリに空きがないことを知らせるものです。
通常は起こりません。ライブラリの知らないものをプリプロセッサが作ったことを知らせます。プリプロセッサとライブラリのバージョンが互換性のないものを使っている可能性があります。
PostgreSQLが、持っている変数より多い引数を返した場合です。おそらくINTO :var1,:var2リストでいくつかのホスト変数を忘れたのでしょう。
PostgreSQLが、持っているホスト変数より少ない引数を返した場合です。おそらくINTO :var1,:var2リストにホスト変数を多く入れすぎています。
問い合わせが数行を返したにもかかわらず、指定された変数が配列になっていないことを示します。入力したSELECTが一意なものではなかったのでしょう。
ホスト変数がint型でPostgreSQLデータベースのフィールドがintでは表せない別の型を含んでいることを示します。ライブラリはこの変換にstrtolを使います。
ホスト変数がunsigned int型でPostgreSQLデータベースのフィールドがunsigned int型では表せない型を含んでいることを示します。ライブラリはこの変換にstrtolを使います。
ホスト変数がfloat型でPostgreSQLデータベースのフィールドがfloatでは表せない別の型を含んでいるということを示します。ライブラリはこの変換にstrtodを使います。
ホスト変数がbool型でPostgreSQLデータベースのフィールドが't'でも'f'でもないということを示します。
おそらく問い合わせが空だったために、PostgreSQLがPGRES_EMPTY_QUERYを返しました。
NULLを許容しない変数に対してNULLを返したため、PostgreSQLはECPG_MISSING_INDICATORを返しました。
通常の変数が再問い合わせの配列に使用されたため、PostgreSQLはECPG_NO_ARRAYを返しました。
PostgreSQL returned ECPG_DATA_NOT_ARRAY because the database returned an ordinary variable in a place that requires array value.配列が要求されている変数に対し通常の変数を返したため、PostgreSQLはECPG_DATA_NOT_ARRAYを返しました。
プログラムが、存在しない接続にアクセスしようとしています。
プログラムが、存在するけれども開いていない接続にアクセスしようとしています。
使おうとしている文が用意されていません。
指定された記述子が見つかりません。使用しようとしている文が用意されていません。
指定された記述子インデックスは範囲外です。
指定された記述子が見つかりません。使用しようとしている文が用意されていません。
数値型でない変数に対してデータベースが数値を返しました。
数値型の変数に対してデータベースが数値以外の値を返しました。
PostgreSQLのエラーです。このメッセージはPostgreSQLのバックエンドからのエラーメッセージを含んでいます。
スタート、コミット、トランザクションのロールバックができないことをPostgreSQLが警告しています。
データベースへの接続ができませんでした。
"一般的な"エラーで、問い合わせているものが見つけられないか、カーソルで通りすぎてしまったものです。