| Current File : //usr/share/doc/postgresql-9.2.24/html/libpq-fastpath.html |
<!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 9.2.24 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="libpq - C Library"
HREF="libpq.html"><LINK
REL="PREVIOUS"
TITLE="Canceling 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="2017-11-06T22:43:11"></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"
><A
HREF="index.html"
>PostgreSQL 9.2.24 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Canceling Queries in Progress"
HREF="libpq-cancel.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 31. <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> - C Library</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Asynchronous Notification"
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"
>31.7. The Fast-Path Interface</A
></H1
><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
>
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
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. (The declaration of <TT
CLASS="PARAMETER"
>u.ptr</TT
> as being of
type <TT
CLASS="TYPE"
>int *</TT
> is historical; it would be better to consider
it <TT
CLASS="TYPE"
>void *</TT
>.)
<TT
CLASS="PARAMETER"
>result_buf</TT
> 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
<TT
CLASS="PARAMETER"
>result_len</TT
>. If a 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;
note that a 4-byte integer is delivered into <TT
CLASS="PARAMETER"
>*result_buf</TT
>
for either allowed result size.
When <TT
CLASS="PARAMETER"
>result_is_int</TT
> is 0, the binary-format byte string
sent by the server is returned unmodified. (In this case it's better
to consider <TT
CLASS="PARAMETER"
>result_buf</TT
> as being of
type <TT
CLASS="TYPE"
>void *</TT
>.)
</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"
>Canceling 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
>