begriffs open source - ai-pg/blob - full-docs/html/libpq-fastpath.html

   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>32.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="32.7. Canceling Queries in Progress" /><link rel="next" href="libpq-notify.html" title="32.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">32.8. The Fast-Path Interface</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-cancel.html" title="32.7. Canceling Queries in Progress">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-notify.html" title="32.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">32.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 interface
   4    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 similar
   7     performance and greater functionality by setting up a prepared
   8     statement to define the function call.  Then, executing the statement
   9     with binary transmission of parameters and results substitutes for a
  10     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">
  15 PGresult *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
  23 typedef struct
  24 {
  25     int len;
  26     int isint;
  27     union
  28     {
  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 be
  36    executed.  <em class="parameter"><code>args</code></em> and <em class="parameter"><code>nargs</code></em> define the
  37    parameters to be passed to the function; they must match the declared
  38    function argument list.  When the <em class="parameter"><code>isint</code></em> field of a
  39    parameter structure is true, the <em class="parameter"><code>u.integer</code></em> value is sent
  40    to the server as an integer of the indicated length (this must be
  41    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> are
  43    sent with no processing; the data must be in the format expected by
  44    the server for binary transmission of the function's argument data
  45    type.  (The declaration of <em class="parameter"><code>u.ptr</code></em> as being of
  46    type <code class="type">int *</code> is historical; it would be better to consider
  47    it <code class="type">void *</code>.)
  48    <em class="parameter"><code>result_buf</code></em> points to the buffer in which to place
  49    the function's return value.  The caller must have allocated sufficient
  50    space to store the return value.  (There is no check!) The actual result
  51    length in bytes will be returned in the integer pointed to by
  52    <em class="parameter"><code>result_len</code></em>.  If a 2- or 4-byte integer result
  53    is expected, set <em class="parameter"><code>result_is_int</code></em> to 1, otherwise
  54    set it to 0.  Setting <em class="parameter"><code>result_is_int</code></em> to 1 causes
  55    <span class="application">libpq</span> to byte-swap the value if necessary, so that it
  56    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 string
  60    sent by the server is returned unmodified. (In this case it's better
  61    to consider <em class="parameter"><code>result_buf</code></em> as being of
  62    type <code class="type">void *</code>.)
  63   </p><p>
  64    <code class="function">PQfn</code> always returns a valid
  65    <code class="structname">PGresult</code> pointer, with
  66    status <code class="literal">PGRES_COMMAND_OK</code> for success
  67    or <code class="literal">PGRES_FATAL_ERROR</code> if some problem was encountered.
  68    The result status should be
  69    checked before the result is used.   The caller is responsible for
  70    freeing  the  <code class="structname">PGresult</code>  with
  71    <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, set
  74    the <em class="parameter"><code>len</code></em> field of that parameter structure
  75    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 set
  79    to <code class="literal">-1</code>, and <em class="parameter"><code>*result_buf</code></em> is not
  80    modified.
  81   </p><p>
  82    Note that it is not possible to handle set-valued results when using
  83    this interface.  Also, the function must be a plain function, not an
  84    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="32.7. Canceling Queries in Progress">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-notify.html" title="32.9. Asynchronous Notification">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.7. Canceling Queries in Progress </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.9. Asynchronous Notification</td></tr></table></div></body></html>