【JPUG主催】PostgreSQLカンファレンス2020【11月13日開催】
他のバージョンの文書 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

6.3. ecpgの使い方

このセクションはecpgツールの使い方を説明します。

6.3.1. プリプロセッサ

プリプロセッサはecpgと呼ばれます。PostgreSQLbin/ディレクトリにインストールされています。

6.3.2. ライブラリ

ecpgライブラリは、libecpg.aもしくはlibecpg.soと呼ばれます。さらに、このライブラリはPostgreSQLサーバーとの通信にlibpqライブラリを使用します。よって、プログラムを-lecpg -lpqというリンクオプションを使用してリンクする必要があります。

このライブラリはいくつか"隠された"メソッドを持っていて、とても便利な場合があります。

6.3.3. エラー処理

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は、エラーを説明する文字列を持っています。その文字列はソースファイルの行数で終わります。

起こり得るエラーを以下に示します。

-12, Out of memory in line %d.

通常は起こりません。仮想メモリに空きがないことを知らせるものです。

-200 (ECPG_UNSUPPORTED): Unsupported type %s on line %d.

通常は起こりません。ライブラリの知らないものをプリプロセッサが作ったことを知らせます。プリプロセッサとライブラリのバージョンが互換性のないものを使っている可能性があります。

-201 (ECPG_TOO_MANY_ARGUMENTS): Too many arguments line %d.

PostgreSQLが、持っている変数より多い引数を返した場合です。おそらくINTO :var1,:var2リストでいくつかのホスト変数を忘れたのでしょう。

-202 (ECPG_TOO_FEW_ARGUMENTS): Too few arguments line %d.

PostgreSQLが、持っているホスト変数より少ない引数を返した場合です。おそらくINTO :var1,:var2リストにホスト変数を多く入れすぎています。

-203 (ECPG_TOO_MANY_MATCHES): Too many matches line %d.

問い合わせが数行を返したにもかかわらず、指定された変数が配列になっていないことを示します。入力したSELECTが一意なものではなかったのでしょう。

-204 (ECPG_INT_FORMAT): Not correctly formatted int type: %s line %d.

ホスト変数がint型でPostgreSQLデータベースのフィールドがintでは表せない別の型を含んでいることを示します。ライブラリはこの変換にstrtolを使います。

-205 (ECPG_UINT_FORMAT): Not correctly formatted unsigned type: %s line %d.

ホスト変数がunsigned int型でPostgreSQLデータベースのフィールドがunsigned int型では表せない型を含んでいることを示します。ライブラリはこの変換にstrtolを使います。

-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating-point type: %s line %d.

ホスト変数がfloat型でPostgreSQLデータベースのフィールドがfloatでは表せない別の型を含んでいるということを示します。ライブラリはこの変換にstrtodを使います。

-207 (ECPG_CONVERT_BOOL): Unable to convert %s to bool on line %d.

ホスト変数がbool型でPostgreSQLデータベースのフィールドが't'でも'f'でもないということを示します。

-208 (ECPG_EMPTY): Empty query line %d.

おそらく問い合わせが空だったために、PostgreSQLPGRES_EMPTY_QUERYを返しました。

-209 (ECPG_MISSING_INDICATOR): NULL value without indicator in line %d.

NULLを許容しない変数に対してNULLを返したため、PostgreSQLECPG_MISSING_INDICATORを返しました。

-210 (ECPG_NO_ARRAY): Variable is not an array in line %d.

通常の変数が再問い合わせの配列に使用されたため、PostgreSQLECPG_NO_ARRAYを返しました。

-211 (ECPG_DATA_NOT_ARRAY): Data read from backend is not an array in line %d.

PostgreSQL returned ECPG_DATA_NOT_ARRAY because the database returned an ordinary variable in a place that requires array value.配列が要求されている変数に対し通常の変数を返したため、PostgreSQLECPG_DATA_NOT_ARRAYを返しました。

-220 (ECPG_NO_CONN): No such connection %s in line %d.

プログラムが、存在しない接続にアクセスしようとしています。

-221 (ECPG_NOT_CONN): Not connected in line %d.

プログラムが、存在するけれども開いていない接続にアクセスしようとしています。

-230 (ECPG_INVALID_STMT): Invalid statement name %s in line %d.

使おうとしている文が用意されていません。

-240 (ECPG_UNKNOWN_DESCRIPTOR): Descriptor %s not found in line %d.

指定された記述子が見つかりません。使用しようとしている文が用意されていません。

-241 (ECPG_INVALID_DESCRIPTOR_INDEX): Descriptor index out of range in line %d.

指定された記述子インデックスは範囲外です。

-242 (ECPG_UNKNOWN_DESCRIPTOR_ITEM): Descriptor %s not found in line %d.

指定された記述子が見つかりません。使用しようとしている文が用意されていません。

-243 (ECPG_VAR_NOT_NUMERIC): Variable is not a numeric type in line %d.

数値型でない変数に対してデータベースが数値を返しました。

-244 (ECPG_VAR_NOT_CHAR): Variable is not a character type in line %d.

数値型の変数に対してデータベースが数値以外の値を返しました。

-400 (ECPG_PGSQL): Postgres error: %s line %d.

PostgreSQLのエラーです。このメッセージはPostgreSQLのバックエンドからのエラーメッセージを含んでいます。

-401 (ECPG_TRANS): Error in transaction processing line %d.

スタート、コミット、トランザクションのロールバックができないことをPostgreSQLが警告しています。

-402 (ECPG_CONNECT): Could not connect to database %s in line %d.

データベースへの接続ができませんでした。

100 (ECPG_NOT_FOUND): Data not found line %d.

"一般的な"エラーで、問い合わせているものが見つけられないか、カーソルで通りすぎてしまったものです。