[11/15開催: PostgreSQL Conference Japan 2019 参加受付中] 
他のバージョンの文書 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

ecpg

Name

ecpg  --  埋め込み SQL 用 C プリプロセッサ

Synopsis

ecpg [-v] [-t] [-I include-path] [-o outfile] file...

入力

ecpgは、以下のコマンドライン引数を受け付けます。

-v

バージョン情報を表示します。

-t

トランザクションの自動コミットを有効にします。このモードでは、各問い合わせは明示的なトランザクションブロックの内部にない限り、自動的にコミットされます。デフォルトのモードでは、 exec sql commit が発行された時にのみ問い合わせはコミットされます。

-I include-path

追加する include 用パスを指定します。デフォルトでは、 .(カレントディレクトリ)、 /usr/local/include、コンパイル時に定義される PostgreSQLの include 用パス(デフォルトでは、/usr/local/pgsql/include )、及び、/usr/includeです。

-o outfile

ecpg がその全ての出力を outfile に書き出すように指示します。このオプションが無い場合、入力ファイル名が name.pgc であると仮定すると、その出力は name.c に書き出されます。入力ファイルが想定通りの.pgcという拡張子を持っている場合、出力ファイルはその入力ファイルに .pgcをつけた場合と同じ動作になります。

file

処理対象ファイルです。

出力

ecpgはファイルを生成するか、または、 stdoutに出力します。

戻り値

ecpgは正常終了時には0を、エラー時には非 0 をシェルに返します。

説明

ecpg は、C 言語と PostgreSQL 用の埋め込み SQL プリプロセッサです。これにより、埋め込み SQL を使用した C プログラムの開発が可能です。

Linus Tolke () 氏が ecpgの元々の作者です。(バージョン0.2までです。)現在はMichael Meskes()氏が作者であり、 ecpg の管理維持を行なっています。Thomas Good()氏がecpgマニュアルページの最新版の作者です。本文書はこのマニュアルページを基にしています。

使用方法

コンパイルの前処理

埋め込みSQLのソースは、コンパイル前に以下のように前処理されなければなりません。

ecpg [ -d ] [ -o file ] file.pgc

ここで、オプションの-dフラグはデバッグ機能を有効にします。.pgcという拡張子は、 ecpgのソースであることを表す便宜的なものです。

プリプロセッサの出力をログファイルにリダイレクトした方が良いでしょう。

コンパイルおよびリンク作業

PostgreSQLのバイナリが /usr/local/pgsqlにあるとすると、下記のように前処理されたソースファイルのコンパイルとリンクを行なわなければなりません。

gcc -g -I /usr/local/pgsql/include [ -o file ] file.c -L /usr/local/pgsql/lib -lecpg -lpq

文法

ライブラリ

プリプロセッサはソースの先頭に下記の2つの指示子を付与します。

#include <ecpgtype.h>
#include <ecpglib.h>

変数宣言

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;

注釈

完全な構造体定義は宣言部内に記述しなければなりません。

他の存在しない機能については、ソースディレクトリにある、 TODOファイルを参照して下さい。