ecpg [ -v ] [ -t ] [ -I include-path ] [ -o outfile ] file1 [ file2 ] [ ... ]
ecpgは、以下のコマンドライン引数を 受け付けます。
バージョン情報を表示します。
自動トランザクションモードを無効にします。
追加する include 用パスを指定します。デフォルトでは、 .、/usr/local/include、 コンパイル時に定義されるPostgresのinclude用 パス(デフォルトでは、/usr/local/pgsql/lib )、及び、 /usr/includeです。
ecpg がその全ての出力を出力ファイルに書き出すように指示します。 こういったオプションが無い場合、入力ファイル名が name.pgc であると仮定すると、その出力は name.c に書き出されます。入力ファイルが想定通りの.pgcという サフィックスを持っている場合、出力ファイルはその入力ファイルに .pgcをつけた場合と同じ動作になります。
処理対象ファイルです。
ecpg は、C言語とPostgres用の 埋め込みSQLプリプロセッサです。これにより、埋め込みSQLを使用したCプログラムの 開発が可能です。
Linus Tolke (<linus@epact.se>)氏が ecpgの元々の作者です。(バージョン0.2までです。) 現在はMichael Meskes(<meskes@debian.org>)氏が作者であり、 ecpg の管理維持を行なっています。 Thomas Good(<tomg@q8.nrnet.org>)氏がecpgman ページの最新版の作者です。本書はこのマニュアルページを元にしています。
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;