codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.8. The Fast-Path Interface</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress" /><link rel="next" href="libpq-notify.html" title="34.9. Asynchronous Notification" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.8. The Fast-Path Interface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notify.html" title="34.9. Asynchronous Notification">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-FASTPATH"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.8. The Fast-Path Interface <a href="#LIBPQ-FASTPATH" class="id_link">#</a></h2></div></div></div><a id="id-1.7.3.15.2" class="indexterm"></a><p>3   <span class="productname">PostgreSQL</span> provides a fast-path interface4   to send simple function calls to the server.5  </p><div class="tip"><h3 class="title">Tip</h3><p>6    This interface is somewhat obsolete, as one can achieve similar7    performance and greater functionality by setting up a prepared8    statement to define the function call.  Then, executing the statement9    with binary transmission of parameters and results substitutes for a10    fast-path function call.11   </p></div><p>12   The function <code class="function" id="LIBPQ-PQFN">PQfn</code><a id="id-1.7.3.15.5.2" class="indexterm"></a>13   requests execution of a server function via the fast-path interface:14</p><pre class="synopsis">15PGresult *PQfn(PGconn *conn,16               int fnid,17               int *result_buf,18               int *result_len,19               int result_is_int,20               const PQArgBlock *args,21               int nargs);22 23typedef struct24{25    int len;26    int isint;27    union28    {29        int *ptr;30        int integer;31    } u;32} PQArgBlock;33</pre><p>34  </p><p>35   The <em class="parameter"><code>fnid</code></em> argument is the OID of the function to be36   executed.  <em class="parameter"><code>args</code></em> and <em class="parameter"><code>nargs</code></em> define the37   parameters to be passed to the function; they must match the declared38   function argument list.  When the <em class="parameter"><code>isint</code></em> field of a39   parameter structure is true, the <em class="parameter"><code>u.integer</code></em> value is sent40   to the server as an integer of the indicated length (this must be41   2 or 4 bytes); proper byte-swapping occurs.  When <em class="parameter"><code>isint</code></em>42   is false, the indicated number of bytes at <em class="parameter"><code>*u.ptr</code></em> are43   sent with no processing; the data must be in the format expected by44   the server for binary transmission of the function's argument data45   type.  (The declaration of <em class="parameter"><code>u.ptr</code></em> as being of46   type <code class="type">int *</code> is historical; it would be better to consider47   it <code class="type">void *</code>.)48   <em class="parameter"><code>result_buf</code></em> points to the buffer in which to place49   the function's return value.  The caller must have allocated sufficient50   space to store the return value.  (There is no check!) The actual result51   length in bytes will be returned in the integer pointed to by52   <em class="parameter"><code>result_len</code></em>.  If a 2- or 4-byte integer result53   is expected, set <em class="parameter"><code>result_is_int</code></em> to 1, otherwise54   set it to 0.  Setting <em class="parameter"><code>result_is_int</code></em> to 1 causes55   <span class="application">libpq</span> to byte-swap the value if necessary, so that it56   is delivered as a proper <code class="type">int</code> value for the client machine;57   note that a 4-byte integer is delivered into <em class="parameter"><code>*result_buf</code></em>58   for either allowed result size.59   When <em class="parameter"><code>result_is_int</code></em> is 0, the binary-format byte string60   sent by the server is returned unmodified. (In this case it's better61   to consider <em class="parameter"><code>result_buf</code></em> as being of62   type <code class="type">void *</code>.)63  </p><p>64   <code class="function">PQfn</code> always returns a valid65   <code class="structname">PGresult</code> pointer, with66   status <code class="literal">PGRES_COMMAND_OK</code> for success67   or <code class="literal">PGRES_FATAL_ERROR</code> if some problem was encountered.68   The result status should be69   checked before the result is used.   The caller is responsible for70   freeing  the  <code class="structname">PGresult</code>  with71   <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when it is no longer needed.72  </p><p>73   To pass a NULL argument to the function, set74   the <em class="parameter"><code>len</code></em> field of that parameter structure75   to <code class="literal">-1</code>; the <em class="parameter"><code>isint</code></em>76   and <em class="parameter"><code>u</code></em> fields are then irrelevant.77  </p><p>78   If the function returns NULL, <em class="parameter"><code>*result_len</code></em> is set79   to <code class="literal">-1</code>, and <em class="parameter"><code>*result_buf</code></em> is not80   modified.81  </p><p>82   Note that it is not possible to handle set-valued results when using83   this interface.  Also, the function must be a plain function, not an84   aggregate, window function, or procedure.85  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notify.html" title="34.9. Asynchronous Notification">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.7. Canceling Queries in Progress </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.9. Asynchronous Notification</td></tr></table></div></body></html>