<productname>PostgreSQL</productname> provides a fast-path interface to send simple function calls to the server. PostgreSQLは、サーバへの簡単な関数呼び出しを送信する近道 (fast-path) インタフェースを用意しています。

The function <function id="libpq-PQfn">PQfn</function><indexterm><primary>PQfn</primary></indexterm> requests execution of a server function via the fast-path interface: 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;

The <parameter>fnid</parameter> argument is the OID of the function to be executed. <parameter>args</parameter> and <parameter>nargs</parameter> define the parameters to be passed to the function; they must match the declared function argument list. When the <parameter>isint</parameter> field of a parameter structure is true, the <parameter>u.integer</parameter> value is sent to the server as an integer of the indicated length (this must be 2 or 4 bytes); proper byte-swapping occurs. When <parameter>isint</parameter> is false, the indicated number of bytes at <parameter>*u.ptr</parameter> are sent with no processing; the data must be in the format expected by the server for binary transmission of the function's argument data type. (The declaration of <parameter>u.ptr</parameter> as being of type <type>int *</type> is historical; it would be better to consider it <type>void *</type>.) <parameter>result_buf</parameter> points to the buffer in which to place the function's return value. The caller must have allocated sufficient space to store the return value. (There is no check!) The actual result length in bytes will be returned in the integer pointed to by <parameter>result_len</parameter>. If a 2- or 4-byte integer result is expected, set <parameter>result_is_int</parameter> to 1, otherwise set it to 0. Setting <parameter>result_is_int</parameter> to 1 causes <application>libpq</application> to byte-swap the value if necessary, so that it is delivered as a proper <type>int</type> value for the client machine; note that a 4-byte integer is delivered into <parameter>*result_buf</parameter> for either allowed result size. When <parameter>result_is_int</parameter> is 0, the binary-format byte string sent by the server is returned unmodified. (In this case it's better to consider <parameter>result_buf</parameter> as being of type <type>void *</type>.) fnid引数は実行する関数のOIDです。 argsとnargsは関数に渡すパラメータを定義します。 これらは関数宣言における引数リストに一致しなければなりません。 パラメータ構造体のisintが真の場合、u.integerの値はサーバに指定長の整数として送信されます。 (これは2もしくは4バイトでなければなりません。) この時、適切なバイト順の交換が行なわれます。 isintが偽の場合は、*u.ptrで指定されたバイト数が無処理で送信されます。 関数のパラメータデータ型をバイナリ転送で行うために、このデータはサーバで想定する書式である必要があります。 (u.ptrをint *型と宣言するのは歴史的なものです。void *と考えた方が良いでしょう。) result_bufは関数の戻り値を格納するバッファを指しています。 呼び出し側は戻り値を格納するのに十分な領域を確保しておかなければいけません。 （ライブラリ側ではこの検査はしていません！） バイト単位での結果の実データ長はresult_lenが指す整数で返されます。 結果が2、4バイト整数だと想定できるならresult_is_intを1に、そうでなければ0を設定します。 result_is_intを1にすれば、必要に応じて値のバイト順を入れ換えるようlibpqに指示することになります。 そしてクライアントマシン上で正しいint値となるように転送します。 4バイト整数は認められた結果の大きさで*result_bufに転送されることに注意してください。 result_is_intが0の場合は、バックエンドが送ったバイナリ書式のバイト列を何も修正せずに返します。 (この場合、result_bufはvoid *型と考えた方が良いでしょう。)

<function>PQfn</function> always returns a valid <structname>PGresult</structname> pointer, with status <literal>PGRES_COMMAND_OK</literal> for success or <literal>PGRES_FATAL_ERROR</literal> if some problem was encountered. The result status should be checked before the result is used. The caller is responsible for freeing the <structname>PGresult</structname> with <xref linkend="libpq-PQclear"/> when it is no longer needed. PQfnは常に有効なPGresult*ポインタを返します。 成功した場合はPGRES_COMMAND_OK、問題が発生した場合はPGRES_FATAL_ERRORのステータスが返されます。 結果を使う前にはまず、結果ステータスを調べておくべきでしょう。 結果が必要なくなった時点で、PQclearによって、PGresultを解放するのは、呼び出し側の責任です。

To pass a NULL argument to the function, set the <parameter>len</parameter> field of that parameter structure to <literal>-1</literal>; the <parameter>isint</parameter> and <parameter>u</parameter> fields are then irrelevant. 関数にNULL引数を渡すには、そのパラメータ構造体のlenフィールドを-1に設定します。 isintフィールドとuフィールドは無関係です。

If the function returns NULL, <parameter>*result_len</parameter> is set to <literal>-1</literal>, and <parameter>*result_buf</parameter> is not modified. この関数がNULLを返す場合、*result_lenは-1に設定され、*result_bufは変更されません。

Note that it is not possible to handle set-valued results when using this interface. Also, the function must be a plain function, not an aggregate, window function, or procedure. このインタフェースを使用した場合、セット値の結果を扱うことができないことに注意してください。 また、関数は、集約関数、ウィンドウ関数またはプロシージャではなく、プレーンな関数である必要があります。