<!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.0.11 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="2007-02-02T03:57:22"></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.0.11 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 27. <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" >27.6. The Fast-Path Interface</A ></H1 ><A NAME="AEN24168" ></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 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.</P ></BLOCKQUOTE ></DIV ><P >The function <CODE CLASS="FUNCTION" >PQfn</CODE ><A NAME="AEN24176" ></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 >