PostgreSQL provides a fast-path interface to send simple function calls to the server.
This interface is somewhat obsolete, as one may achieve similar performance and greater functionality by setting up a prepared statement to define the function call. Then, executing the statement with binary transmission of parameters and results substitutes for a fast-path function call.
The function PQfn
requests execution of a server function via the fast-path interface:
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 fnid
argument is the OID of the function to be
executed. args
and nargs
define the
parameters to be passed to the function; they must match the declared
function argument list. When the isint
field of a
parameter
structure is true,
the u.integer
value is sent to the server as an integer
of the indicated length (this must be 1, 2, or 4 bytes); proper
byte-swapping occurs. When isint
is false, the
indicated number of bytes at *u.ptr
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.
result_buf
is the buffer in which
to place the return value. The caller must have allocated
sufficient space to store the return value. (There is no check!)
The actual result length will be returned in the integer pointed
to by result_len
.
If a 1, 2, or 4-byte integer result is expected, set
result_is_int
to 1, otherwise set it to 0.
Setting result_is_int
to 1
causes libpq to byte-swap the value if necessary, so that
it is
delivered as a proper int
value for the client machine. When
result_is_int
is 0, the binary-format byte string sent by
the server is returned unmodified.
PQfn
always returns a valid PGresult
pointer. The result status
should be checked before the result is used. The
caller is responsible for freeing the PGresult
with
PQclear
when it is no longer needed.
Note that it is not possible to handle null arguments, null results, nor set-valued results when using this interface.