ecpg [-v] [-t] [-I include-path] [-o outfile] file...
ecpgは、以下のコマンドライン引数を受け付けます。
バージョン情報を表示します。
トランザクションの自動コミットを有効にします。このモードでは、各問い合わせは明示的なトランザクションブロックの内部にない限り、自動的にコミットされます。デフォルトのモードでは、 exec sql commit が発行された時にのみ問い合わせはコミットされます。
追加する include 用パスを指定します。デフォルトでは、 .(カレントディレクトリ)、 /usr/local/include、コンパイル時に定義される PostgreSQLの include 用パス(デフォルトでは、/usr/local/pgsql/include )、及び、/usr/includeです。
ecpg がその全ての出力を outfile に書き出すように指示します。このオプションが無い場合、入力ファイル名が name.pgc であると仮定すると、その出力は name.c に書き出されます。入力ファイルが想定通りの.pgcという拡張子を持っている場合、出力ファイルはその入力ファイルに .pgcをつけた場合と同じ動作になります。
処理対象ファイルです。
ecpg は、C 言語と PostgreSQL 用の埋め込み SQL プリプロセッサです。これにより、埋め込み SQL を使用した C プログラムの開発が可能です。
Linus Tolke (<linus@epact.se>) 氏が ecpgの元々の作者です。(バージョン0.2までです。)現在はMichael Meskes(<meskes@debian.org>)氏が作者であり、 ecpg の管理維持を行なっています。Thomas Good(<tomg@q8.nrnet.org>)氏がecpgマニュアルページの最新版の作者です。本文書はこのマニュアルページを基にしています。
ecpgのソース内で宣言される変数は、下記で始まらなければなりません。
EXEC SQL BEGIN DECLARE SECTION;
同様に、変数宣言部は下記で終らなければなりません。
EXEC SQL END DECLARE SECTION;
Note: バージョン2.1.0以前では、各変数は単独の行で宣言しなければなりませんでした。バージョン2.1.0では、以下のように1行に複数の変数を宣言することができます。
char foo[16], bar[16];
下記によりSQL通信部分が定義されます。
EXEC SQL INCLUDE sqlca;
Note: sqlcaは小文字で表します。SQLの慣習、例えば、埋め込みSQLとC言語の文を区別するために大文字を使用することなどには従った方が良いのですが、(sqlca.hヘッダファイルをincludeすることを示す) sqlcaは必ず小文字でなければなりません。EXEC SQLという前置詞は、このINCLUDEが ecpgによって解析されることを示しているからです。 ecpgは大文字小文字の違いをそのまま使用します。(SQLCA.h ではファイルを検出できません。)EXEC SQL INCLUDEは大文字小文字の違いさえ守られていれば、他のヘッダファイルをincludeする場合にも使用することができます。
sqlprint コマンドは下記のように EXEC SQL WHENEVER 文内で使用され、これによりプログラム全体を通してエラー処理が有効になります。
EXEC SQL WHENEVER sqlerror sqlprint;
および
EXEC SQL WHENEVER not found sqlprint;
Note: これはEXEC SQL WHENEVER文の完全な使用例では ありません。より多くの使用例がSQLのマニュアル(例えば、Groff氏とWeinberg氏の The LAN TIMES Guide to SQL)に掲載されています。
データベースに接続するには下記の様にします。
EXEC SQL CONNECT TO dbname;
ここで、データベース名は引用符で括られていません。バージョン2.1.0以前ではデータベース名は単一引用符で括る必要がありました。
connect文でサーバ名とポート番号を指定することも可能です。下記がその構文です。
dbname[@server][:port]
または
<tcp|unix>:postgresql://server[:port][/dbname][?options]
通常、psqlなどの他アプリケーションで使用できるSQL問い合わせはCのコードに埋め込むことができます。ここで、埋め込む方法を示す例をいくつか示します。
テーブルを作成します。
EXEC SQL CREATE TABLE foo (number int4, ascii char(16)); EXEC SQL CREATE UNIQUE index num1 on foo(number); EXEC SQL COMMIT;
挿入します。
EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad'); EXEC SQL COMMIT;
削除します。
EXEC SQL DELETE FROM foo WHERE number = 9999; EXEC SQL COMMIT;
1タプルを選択します。
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
カーソルを使用して選択します。
EXEC SQL DECLARE foo_bar CURSOR FOR
SELECT number, ascii FROM foo
ORDER BY ascii;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;
更新します。
EXEC SQL UPDATE foo
SET ascii = 'foobar'
WHERE number = 9999;
EXEC SQL COMMIT;