blob: 176d409fab915009ce8d16d3600cb428ce28fa06 (
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
|
<?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>SPI_cursor_parse_open</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="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist" /><link rel="next" href="spi-spi-cursor-find.html" title="SPI_cursor_find" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_cursor_parse_open</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><th width="60%" align="center">47.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-cursor-find.html" title="SPI_cursor_find">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-CURSOR-PARSE-OPEN"><div class="titlepage"></div><a id="id-1.8.12.8.22.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_cursor_parse_open</span></h2><p>SPI_cursor_parse_open — set up a cursor using a query string and parameters</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
Portal SPI_cursor_parse_open(const char *<em class="parameter"><code>name</code></em>,
const char *<em class="parameter"><code>command</code></em>,
const SPIParseOpenOptions * <em class="parameter"><code>options</code></em>)
</pre></div><div class="refsect1" id="id-1.8.12.8.22.5"><h2>Description</h2><p>
<code class="function">SPI_cursor_parse_open</code> sets up a cursor
(internally, a portal) that will execute the specified query string.
This is comparable to <code class="function">SPI_prepare_cursor</code> followed
by <code class="function">SPI_cursor_open_with_paramlist</code>, except that
parameter references within the query string are handled entirely by
supplying a <code class="literal">ParamListInfo</code> object.
</p><p>
For one-time query execution, this function should be preferred
over <code class="function">SPI_prepare_cursor</code> followed by
<code class="function">SPI_cursor_open_with_paramlist</code>.
If the same command is to be executed with many different parameters,
either method might be faster, depending on the cost of re-planning
versus the benefit of custom plans.
</p><p>
The <em class="parameter"><code>options->params</code></em> object should normally
mark each parameter with the <code class="literal">PARAM_FLAG_CONST</code> flag,
since a one-shot plan is always used for the query.
</p><p>
The passed-in parameter data will be copied into the cursor's portal, so it
can be freed while the cursor still exists.
</p></div><div class="refsect1" id="id-1.8.12.8.22.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>name</code></em></code></span></dt><dd><p>
name for portal, or <code class="symbol">NULL</code> to let the system
select a name
</p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
command string
</p></dd><dt><span class="term"><code class="literal">const SPIParseOpenOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
struct containing optional arguments
</p></dd></dl></div><p>
Callers should always zero out the entire <em class="parameter"><code>options</code></em>
struct, then fill whichever fields they want to set. This ensures forward
compatibility of code, since any fields that are added to the struct in
future will be defined to behave backwards-compatibly if they are zero.
The currently available <em class="parameter"><code>options</code></em> fields are:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">ParamListInfo <em class="parameter"><code>params</code></em></code></span></dt><dd><p>
data structure containing query parameter types and values; NULL if none
</p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
integer bit mask of cursor options; zero produces default behavior
</p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.22.7"><h2>Return Value</h2><p>
Pointer to portal containing the cursor. Note there is no error
return convention; any error will be reported via <code class="function">elog</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-cursor-open-with-paramlist.html" title="SPI_cursor_open_with_paramlist">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="47.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-cursor-find.html" title="SPI_cursor_find">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_cursor_open_with_paramlist </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.2 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_find</td></tr></table></div></body></html>
|
