codekingpro/portable-devtools

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_execute_plan_extended</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-execute-plan.html" title="SPI_execute_plan" /><link rel="next" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist" /></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_execute_plan_extended</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-plan.html" title="SPI_execute_plan">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.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE-PLAN-EXTENDED"><div class="titlepage"></div><a id="id-1.8.12.8.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute_plan_extended</span></h2><p>SPI_execute_plan_extended — execute a statement prepared by <code class="function">SPI_prepare</code></p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">3int SPI_execute_plan_extended(SPIPlanPtr <em class="parameter"><code>plan</code></em>,4                              const SPIExecuteOptions * <em class="parameter"><code>options</code></em>)5</pre></div><div class="refsect1" id="id-1.8.12.8.16.5"><h2>Description</h2><p>6   <code class="function">SPI_execute_plan_extended</code> executes a statement7   prepared by <code class="function">SPI_prepare</code> or one of its siblings.8   This function is equivalent to <code class="function">SPI_execute_plan</code>,9   except that information about the parameter values to be passed to the10   query is presented differently, and additional execution-controlling11   options can be passed.12  </p><p>13   Query parameter values are represented by14   a <code class="literal">ParamListInfo</code> struct, which is convenient for passing15   down values that are already available in that format.  Dynamic parameter16   sets can also be used, via hook functions specified17   in <code class="literal">ParamListInfo</code>.18  </p><p>19   Also, instead of always accumulating the result tuples into a20   <code class="varname">SPI_tuptable</code> structure, tuples can be passed to a21   caller-supplied <code class="literal">DestReceiver</code> object as they are22   generated by the executor.  This is particularly helpful for queries23   that might generate many tuples, since the data can be processed24   on-the-fly instead of being accumulated in memory.25  </p></div><div class="refsect1" id="id-1.8.12.8.16.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SPIPlanPtr <em class="parameter"><code>plan</code></em></code></span></dt><dd><p>26      prepared statement (returned by <code class="function">SPI_prepare</code>)27     </p></dd><dt><span class="term"><code class="literal">const SPIExecuteOptions * <em class="parameter"><code>options</code></em></code></span></dt><dd><p>28      struct containing optional arguments29     </p></dd></dl></div><p>30   Callers should always zero out the entire <em class="parameter"><code>options</code></em>31   struct, then fill whichever fields they want to set.  This ensures forward32   compatibility of code, since any fields that are added to the struct in33   future will be defined to behave backwards-compatibly if they are zero.34   The currently available <em class="parameter"><code>options</code></em> fields are:35  </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>36      data structure containing query parameter types and values; NULL if none37     </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><dt><span class="term"><code class="literal">bool <em class="parameter"><code>allow_nonatomic</code></em></code></span></dt><dd><p>38      <code class="literal">true</code> allows non-atomic execution of CALL and DO39      statements40     </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>must_return_tuples</code></em></code></span></dt><dd><p>41      if <code class="literal">true</code>, raise error if the query is not of a kind42      that returns tuples (this does not forbid the case where it happens to43      return zero tuples)44     </p></dd><dt><span class="term"><code class="literal">uint64 <em class="parameter"><code>tcount</code></em></code></span></dt><dd><p>45      maximum number of rows to return,46      or <code class="literal">0</code> for no limit47     </p></dd><dt><span class="term"><code class="literal">DestReceiver * <em class="parameter"><code>dest</code></em></code></span></dt><dd><p>48      <code class="literal">DestReceiver</code> object that will receive any tuples49      emitted by the query; if NULL, result tuples are accumulated into50      a <code class="varname">SPI_tuptable</code> structure, as51      in <code class="function">SPI_execute_plan</code>52     </p></dd><dt><span class="term"><code class="literal">ResourceOwner <em class="parameter"><code>owner</code></em></code></span></dt><dd><p>53      The resource owner that will hold a reference count on the plan while54      it is executed.  If NULL, CurrentResourceOwner is used.  Ignored for55      non-saved plans, as SPI does not acquire reference counts on those.56     </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.16.7"><h2>Return Value</h2><p>57   The return value is the same as for <code class="function">SPI_execute_plan</code>.58  </p><p>59   When <em class="parameter"><code>options-&gt;dest</code></em> is NULL,60   <code class="varname">SPI_processed</code> and61   <code class="varname">SPI_tuptable</code> are set as in62   <code class="function">SPI_execute_plan</code>.63   When <em class="parameter"><code>options-&gt;dest</code></em> is not NULL,64   <code class="varname">SPI_processed</code> is set to zero and65   <code class="varname">SPI_tuptable</code> is set to NULL.  If a tuple count66   is required, the caller's <code class="literal">DestReceiver</code> object must67   calculate it.68  </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-execute-plan.html" title="SPI_execute_plan">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-execute-plan-with-paramlist.html" title="SPI_execute_plan_with_paramlist">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_plan </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_execute_plan_with_paramlist</td></tr></table></div></body></html>