summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/libpq-fastpath.html
blob: e0db72c4f5398ac1bc12eeb6f77a8142ce2bcbd5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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 15.5 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</h2></div></div></div><a id="id-1.7.3.15.2" class="indexterm"></a><p>
   <span class="productname">PostgreSQL</span> provides a fast-path interface
   to send simple function calls to the server.
  </p><div class="tip"><h3 class="title">Tip</h3><p>
    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></div><p>
   The function <code class="function" id="LIBPQ-PQFN">PQfn</code><a id="id-1.7.3.15.5.2" class="indexterm"></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 <em class="parameter"><code>fnid</code></em> argument is the OID of the function to be
   executed.  <em class="parameter"><code>args</code></em> and <em class="parameter"><code>nargs</code></em> define the
   parameters to be passed to the function; they must match the declared
   function argument list.  When the <em class="parameter"><code>isint</code></em> field of a
   parameter structure is true, the <em class="parameter"><code>u.integer</code></em> 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 <em class="parameter"><code>isint</code></em>
   is false, the indicated number of bytes at <em class="parameter"><code>*u.ptr</code></em> 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 <em class="parameter"><code>u.ptr</code></em> as being of
   type <code class="type">int *</code> is historical; it would be better to consider
   it <code class="type">void *</code>.)
   <em class="parameter"><code>result_buf</code></em> 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
   <em class="parameter"><code>result_len</code></em>.  If a 2- or 4-byte integer result
   is expected, set <em class="parameter"><code>result_is_int</code></em> to 1, otherwise
   set it to 0.  Setting <em class="parameter"><code>result_is_int</code></em> to 1 causes
   <span class="application">libpq</span> to byte-swap the value if necessary, so that it
   is delivered as a proper <code class="type">int</code> value for the client machine;
   note that a 4-byte integer is delivered into <em class="parameter"><code>*result_buf</code></em>
   for either allowed result size.
   When <em class="parameter"><code>result_is_int</code></em> is 0, the binary-format byte string
   sent by the server is returned unmodified. (In this case it's better
   to consider <em class="parameter"><code>result_buf</code></em> as being of
   type <code class="type">void *</code>.)
  </p><p>
   <code class="function">PQfn</code> always returns a valid
   <code class="structname">PGresult</code> pointer, with
   status <code class="literal">PGRES_COMMAND_OK</code> for success
   or <code class="literal">PGRES_FATAL_ERROR</code> if some problem was encountered.
   The result status should be
   checked before the result is used.   The caller is responsible for
   freeing  the  <code class="structname">PGresult</code>  with
   <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when it is no longer needed.
  </p><p>
   To pass a NULL argument to the function, set
   the <em class="parameter"><code>len</code></em> field of that parameter structure
   to <code class="literal">-1</code>; the <em class="parameter"><code>isint</code></em>
   and <em class="parameter"><code>u</code></em> fields are then irrelevant.
  </p><p>
   If the function returns NULL, <em class="parameter"><code>*result_len</code></em> is set
   to <code class="literal">-1</code>, and <em class="parameter"><code>*result_buf</code></em> is not
   modified.
  </p><p>
   Note that it is not possible to handle set-valued results when using
   this interface.  Also, the function must be a plain function, not an
   aggregate, window function, or procedure.
  </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 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.9. Asynchronous Notification</td></tr></table></div></body></html>