このセクションは、ecpgが内部でどのように動いているかについて書かれています。どのようにecpgが使用されるかユーザの理解を助ける内容が含まれています。
ecpgから出力される最初の4行は固定です。2行はコメントで、2行はライブラリのインターフェイスに必要なinclude行です。
プリプロセッサは入力ファイルを読み、出力に書き込みます。通常はただ出力にechoします。
EXEC SQL文になると、ecpgは間に入りこれを変更します。EXEC SQL文は、次のうちの一つです。
Declareセクションは以下のように始めます。
exec sql begin declare section;
そして以下のように終わります。
exec sql end declare section;
このセクションでは変数宣言だけが許可されています。ここで宣言される変数はすべて、型と名前がインデックスされた変数のリストにも入ります。
特に構造体や共用体の定義はdeclareセクションでリストされなければいけません。そうしないとecpgは定義を知らないためにこれらの型を扱えなくなります。
変数を通常のC変数にもするために、宣言はファイルにもechoされます。
特別な型であるVARCHARとVARCHAR2は、変数ごとに名前のある構造体に変換されます。下記のような宣言があった場合を考えてみます。
VARCHAR var[180];
これは、下のように変換されます。
struct varchar_var { int len; char arr[180]; } var;
include文は以下のようになります。
exec sql include filename;
次のものではないことに注意してください。
#include <filename.h>
そのかわり、指定されたファイルはecpg自身で構文解析します。ですから、指定されたファイルの中身は結果のCコードに含まれます。この方法だと、EXEC SQLコマンドをincludeファイルに指定することができます。
connect文は以下のようになります。
exec sql connect to connection target;
これは指定されたデータベースへの接続を作成します。
connection target(接続ターゲット)は、次のように指定することができます。
dbname[@server][:port][as connection name][user user name]
tcp:postgresql://server[:port][/dbname][as connection name][user user name]
unix:postgresql://server[:port][/dbname][as connection name][user user name]
character variable[as connection name][user user name]
character string[as connection name][user]
default
user
ユーザー名を指定するには、別の方法もあります。
userid
userid/password
userid identified by password
userid using password
最後にuseridとpasswordです。それぞれテキスト、文字変数、文字列である可能性があります。
disconnect文は以下のようになります。
exec sql disconnect [connection target];
これは指定されたデータベースへの接続を閉じます。
connection target(接続ターゲット)は次のように指定することができます。
connection name
default
current
all
open cursor 文は以下のようになります。
exec sql open cursor;
これは無視され、出力にコピーされません。かわりに、同様にカーソルをオープンする、カーソルのDECLAREコマンドが使われます。
commit文は以下のようになります。
exec sql commit;
rollback文は以下のようになります。
exec sql rollback;
他のSQL文は、exec sqlで始まり;で終わるものです。その中間はすべてSQL文として扱われ、変数の代用が構文解析されます。
変数の代用はシンボルがコロン(:)で始まる場合に起こります。そしてその名前の変数が、declareセクションで以前宣言された変数の中から探されます。変数が入力用か出力用であるかによって、関数からのアクセスを許可するために変数へのポインタが出力に書かれます。
SQL要求の一部であるすべての変数には、関数が他の引数を与えられます。
特別シンボルとしての型
値へのポインタもしくはポインタのポインタ
変数がcharかvarcharだった場合はそのサイズ
配列の要素数(配列取り出し用)
配列の次の要素のオフセット(配列取り出し用)
特別シンボルとしての指示変数の型
指示変数の値へのポインタもしくは指示変数のポインタへのポインタ
0
指示配列の要素数(配列取り出し用)
指示配列の次の要素のオフセット(配列取り出し用)
これはファイルfoo.pgcのプリプロセッサの出力を説明した完全な例です。
exec sql begin declare section; int index; int result; exec sql end declare section; ... exec sql select res into :result from mytable where index = :index;
これは次のように翻訳されます。
/* Processed by ecpg (2.6.0) */ /* These two include files are added by the preprocessor */ #include <ecpgtype.h>; #include <ecpglib.h>; /* exec sql begin declare section */ #line 1 "foo.pgc" int index; int result; /* exec sql end declare section */ ... ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ", ECPGt_int,&(index),1L,1L,sizeof(int), ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT, ECPGt_int,&(result),1L,1L,sizeof(int), ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT); #line 147 "foo.pgc"
このマニュアルでは読みやすいようにインデントしてありますが、プリプロセッサはこのようにはしません。
ライブラリの中で最も重要な関数はECPGdoです。この関数は引数の数の変数をとります。vararg()関数に許可される変数の数が限られていないマシンを使うことを願います。そうしないと50かそれ以上の引数を追加することになるからです。
引数は以下のとおりです。
エラーメッセージのみで使われた元の行の数です。
発行されるべきSQL要求です。その要求は入力変数により変更されます(たとえばコンパイル時には知られていなかったが要求時に入力された変数)。変数が行くべきところには?があります。
プリプロセッサのセクションで説明されているように、すべての入力変数は10の引数を持ちます。
入力変数がもうないことを表します。
プリプロセッサの部分で説明されるように、すべての入力変数は10の引数を受けます。これらの変数は関数で埋められています。
変数がもうないことを表します。
通常モードにおいて問い合わせはexec sql commitコマンドの発行により実行されます。Ecpgは-tオプションをつけるか、exec sql set autocommit to on文を発行することにより自動コミットをサポートします。autocommit(自動コミット)モードにおいて、それぞれの問い合わせは明確なトランザクションブロックの内部にない限り自動的にコミットされます。この機能を無効にするためにはexec sql set autocommit to offを使用してください。