<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>The Fast-Path Interface</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 8.4.20 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="libpq - C Library"
HREF="libpq.html"><LINK
REL="PREVIOUS"
TITLE="Cancelling Queries in Progress"
HREF="libpq-cancel.html"><LINK
REL="NEXT"
TITLE="Asynchronous Notification"
HREF="libpq-notify.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2014-02-17T20:05:31"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL 8.4.20 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq-cancel.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq.html"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 30. <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> - C Library</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq-notify.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="LIBPQ-FASTPATH"
>30.6. The Fast-Path Interface</A
></H1
><A
NAME="AEN34847"
></A
><P
> <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> provides a fast-path interface
to send simple function calls to the server.
</P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
> This interface is somewhat obsolete, as one can 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.
</P
></BLOCKQUOTE
></DIV
><P
> The function <CODE
CLASS="FUNCTION"
>PQfn</CODE
><A
NAME="AEN34855"
></A
>
requests execution of a server function via the fast-path interface:
</P><PRE
CLASS="SYNOPSIS"
> 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;
</PRE
><P>
</P
><P
> The <TT
CLASS="PARAMETER"
>fnid</TT
> argument is the OID of the function to be
executed. <TT
CLASS="PARAMETER"
>args</TT
> and <TT
CLASS="PARAMETER"
>nargs</TT
> define the
parameters to be passed to the function; they must match the declared
function argument list. When the <TT
CLASS="PARAMETER"
>isint</TT
> field of a
parameter structure is true, the <TT
CLASS="PARAMETER"
>u.integer</TT
> 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 <TT
CLASS="PARAMETER"
>isint</TT
>
is false, the indicated number of bytes at <TT
CLASS="PARAMETER"
>*u.ptr</TT
> 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. <TT
CLASS="PARAMETER"
>result_buf</TT
> 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
<TT
CLASS="PARAMETER"
>result_len</TT
>. If a 1, 2, or 4-byte integer result
is expected, set <TT
CLASS="PARAMETER"
>result_is_int</TT
> to 1, otherwise
set it to 0. Setting <TT
CLASS="PARAMETER"
>result_is_int</TT
> to 1 causes
<SPAN
CLASS="APPLICATION"
>libpq</SPAN
> to byte-swap the value if necessary, so that it
is delivered as a proper <TT
CLASS="TYPE"
>int</TT
> value for the client machine.
When <TT
CLASS="PARAMETER"
>result_is_int</TT
> is 0, the binary-format byte string
sent by the server is returned unmodified.
</P
><P
> <CODE
CLASS="FUNCTION"
>PQfn</CODE
> always returns a valid
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> pointer. The result status should be
checked before the result is used. The caller is responsible for
freeing the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> with
<CODE
CLASS="FUNCTION"
>PQclear</CODE
> when it is no longer needed.
</P
><P
> Note that it is not possible to handle null arguments, null results,
nor set-valued results when using this interface.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq-cancel.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq-notify.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Cancelling Queries in Progress</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Asynchronous Notification</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
