begriffs open source - ai-pg/blob - full-docs/src/sgml/html/spi-spi-cursor-parse-open.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>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="45.1. Interface Functions">Up</a></td><th width="60%" align="center">45.1. Interface Functions</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="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">
   3 Portal SPI_cursor_parse_open(const char *<em class="parameter"><code>name</code></em>,
   4                              const char *<em class="parameter"><code>command</code></em>,
   5                              const SPIParseOpenOptions * <em class="parameter"><code>options</code></em>)
   6 </pre></div><div class="refsect1" id="id-1.8.12.8.22.5"><h2>Description</h2><p>
   7    <code class="function">SPI_cursor_parse_open</code> sets up a cursor
   8    (internally, a portal) that will execute the specified query string.
   9    This is comparable to <code class="function">SPI_prepare_cursor</code> followed
  10    by <code class="function">SPI_cursor_open_with_paramlist</code>, except that
  11    parameter references within the query string are handled entirely by
  12    supplying a <code class="literal">ParamListInfo</code> object.
  13   </p><p>
  14    For one-time query execution, this function should be preferred
  15    over <code class="function">SPI_prepare_cursor</code> followed by
  16    <code class="function">SPI_cursor_open_with_paramlist</code>.
  17    If the same command is to be executed with many different parameters,
  18    either method might be faster, depending on the cost of re-planning
  19    versus the benefit of custom plans.
  20   </p><p>
  21    The <em class="parameter"><code>options-&gt;params</code></em> object should normally
  22    mark each parameter with the <code class="literal">PARAM_FLAG_CONST</code> flag,
  23    since a one-shot plan is always used for the query.
  24   </p><p>
  25    The passed-in parameter data will be copied into the cursor's portal, so it
  26    can be freed while the cursor still exists.
  27   </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>
  28       name for portal, or <code class="symbol">NULL</code> to let the system
  29       select a name
  30      </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
  31       command string
  32      </p></dd><dt><span class="term"><code class="literal">const SPIParseOpenOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>
  33       struct containing optional arguments
  34      </p></dd></dl></div><p>
  35    Callers should always zero out the entire <em class="parameter"><code>options</code></em>
  36    struct, then fill whichever fields they want to set.  This ensures forward
  37    compatibility of code, since any fields that are added to the struct in
  38    future will be defined to behave backwards-compatibly if they are zero.
  39    The currently available <em class="parameter"><code>options</code></em> fields are:
  40   </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>
  41       data structure containing query parameter types and values; NULL if none
  42      </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>cursorOptions</code></em></code></span></dt><dd><p>
  43       integer bit mask of cursor options; zero produces default behavior
  44      </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>
  45    Pointer to portal containing the cursor.  Note there is no error
  46    return convention; any error will be reported via <code class="function">elog</code>.
  47   </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="45.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 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_cursor_find</td></tr></table></div></body></html>