29.6. 近道インタフェース

Postgresは、サーバへの簡単な関数呼び出しを送信する近道 (fast-path) インタフェースを用意しています。

ティップ: この関数はどちらかというと廃れたものです。 同様の性能やそれ以上の機能を、関数呼び出しを定義した準備された文を設定することで達成できるからです。 そして、その文をパラメータと結果をバイナリ転送するように実行すれば、近道関数呼び出しを置き換えることになります。

PQfn関数は、近道インタフェースを使ってサーバ関数の実行を要求します。

PGresult *PQfn(PGconn *conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct {
    int len;
    int isint;
    union {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;

fnid引数は、実行する関数のOIDです。 argsnargsは関数に渡すパラメータを定義します。 これらは関数宣言における引数リストに一致しなければなりません。 パラメータ構造体のisintが真の場合、u.integerの値はサーバに指定長の整数として送信されます。 (これは1、2もしくは4バイトでなければなりません。) この時、適切なバイト順の交換が行なわれます。 isintが偽の場合は、*u.ptrで指定されたバイト数が無処理で送信されます。 関数のパラメータデータ型をバイナリ転送で行うために、このデータはサーバで想定する書式である必要があります。 result_buf は戻り値を格納するバッファです。 呼び出し側は戻り値を格納するのに十分な領域を確保しておかなければいけません (ライブラリ側ではこのチェックはしていません!)。 結果の実データ長は result_len が指す整数で返されます。 結果が1、2、4 バイト整数だと想定できるなら result_is_int を 1 に、そうでなければ0を設定します。 result_is_int を 1 にすれば、必要に応じて値のバイト順を入れ換えるよう libpq に指示することになります。 そしてクライアントマシン上で正しいint値となるように転送します。 result_is_int が 0 の場合は、バックエンドが送ったバイナリ書式のバイト列を何も修正せずに返します。

PQfnは常に有効な PGresult* を返します。 結果を使う前にはまず、結果ステータスを調べておくべきでしょう。 結果が必要なくなった時点で、PQclearによって、PGresult を解放するのは、呼び出し側の責任です。

NULL引数やNULLの結果を扱うことができないことに注意してください。 このインタフェースを使用した場合、結果は値が設定されています。