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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>28.6.The Fast-Path Interface</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="libpq.html" title="Chapter28.libpq - C Library">
<link rel="prev" href="libpq-cancel.html" title="28.5.Cancelling Queries in Progress">
<link rel="next" href="libpq-notify.html" title="28.7.Asynchronous Notification">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="libpq-fastpath"></a>28.6.The Fast-Path Interface</h2></div></div></div>
<a name="id683357"></a><p><span class="productname">PostgreSQL</span> provides a fast-path interface to send
simple function calls to the server.</p>
<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Tip</h3>
<p>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>
</div>
<p>The function <code class="function">PQfn</code><a name="id683394"></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> 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 1, 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.
<em class="parameter"><code>result_buf</code></em> 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 <em class="parameter"><code>result_len</code></em>.
If a 1, 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. When
<em class="parameter"><code>result_is_int</code></em> 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 <code class="structname">PGresult</code> pointer. The result status
should be checked before the result is used. The
caller is responsible for freeing the <code class="structname">PGresult</code> 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></body>
</html>
|
