ecpg

Name

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

Synopsis

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

入力

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

-v

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

-t

自動トランザクションモードを無効にします。

-I path

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

-o

ecpg がその全ての出力を出力ファイルに書き出すように指示します。 こういったオプションが無い場合、入力ファイル名が name.pgc であると仮定すると、その出力は name.c に書き出されます。 入力ファイルが想定通りの .pgc というサフィッ クスを持たない場合、出力ファイルはその入力ファイルに .pgcをつけた場合と同じ動作になります。 (訳注: the input file does have を the input file does not have として訳しています。ソースでは、拡張子を持たない(.がない)よう な場合に拡張子.pgc があるものとして扱っています。何らかの拡張 子がある場合、その拡張子部分を.c に置き換えます。)

file

処理対象ファイル。

出力

ecpg はファイルを生成、もしくは、 stdout に出力します。

return value

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

Description

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

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

使用法

コンパイルの前処理

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

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

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

コンパイル及びリンク作業

Postgres のバイナリが /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 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;
    

注意

EXEC SQL PREPARE 文はありません。

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

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