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です。
args
とnargs
は関数に渡すパラメータを定義します。
これらは関数宣言における引数リストに一致しなければなりません。
パラメータ構造体の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の結果を扱うことができないことに注意してください。 このインタフェースを使用した場合、結果は値が設定されています。