Adding upstream version 13.4.upstream/13.4 upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-04 12:19:15 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-04 12:19:15 +0000
commit: 6eb9c5a5657d1fe77b55cc261450f3538d35a94d (patch)
tree: 657d8194422a5daccecfd42d654b8a245ef7b4c8 /doc/src/sgml/html/spi-spi-prepare.html
parent: Initial commit. (diff)
download: postgresql-13-6eb9c5a5657d1fe77b55cc261450f3538d35a94d.tar.xz
postgresql-13-6eb9c5a5657d1fe77b55cc261450f3538d35a94d.zip
1 files changed, 84 insertions, 0 deletions
diff --git a/doc/src/sgml/html/spi-spi-prepare.html b/doc/src/sgml/html/spi-spi-prepare.html
new file mode 100644
index 0000000..e5f7a38
--- /dev/null
+++ b/doc/src/sgml/html/spi-spi-prepare.html
@@ -0,0 +1,84 @@
+<?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_prepare</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 V1.79.1" /><link rel="prev" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args" /><link rel="next" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_prepare</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="46.1. Interface Functions">Up</a></td><th width="60%" align="center">46.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor">Next</a></td></tr></table><hr></hr></div><div class="refentry" id="SPI-SPI-PREPARE"><div class="titlepage"></div><a id="id-1.8.12.8.7.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_prepare</span></h2><p>SPI_prepare — prepare a statement, without executing it yet</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
+SPIPlanPtr SPI_prepare(const char * <em class="parameter"><code>command</code></em>, int <em class="parameter"><code>nargs</code></em>, Oid * <em class="parameter"><code>argtypes</code></em>)
+</pre></div><div class="refsect1" id="id-1.8.12.8.7.5"><h2>Description</h2><p>
+   <code class="function">SPI_prepare</code> creates and returns a prepared
+   statement for the specified command, but doesn't execute the command.
+   The prepared statement can later be executed repeatedly using
+   <code class="function">SPI_execute_plan</code>.
+  </p><p>
+   When the same or a similar command is to be executed repeatedly, it
+   is generally advantageous to perform parse analysis only once, and
+   might furthermore be advantageous to re-use an execution plan for the
+   command.
+   <code class="function">SPI_prepare</code> converts a command string into a
+   prepared statement that encapsulates the results of parse analysis.
+   The prepared statement also provides a place for caching an execution plan
+   if it is found that generating a custom plan for each execution is not
+   helpful.
+  </p><p>
+   A prepared command can be generalized by writing parameters
+   (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.) in place of what would be
+   constants in a normal command.  The actual values of the parameters
+   are then specified when <code class="function">SPI_execute_plan</code> is called.
+   This allows the prepared command to be used over a wider range of
+   situations than would be possible without parameters.
+  </p><p>
+   The statement returned by <code class="function">SPI_prepare</code> can be used
+   only in the current invocation of the C function, since
+   <code class="function">SPI_finish</code> frees memory allocated for such a
+   statement.  But the statement can be saved for longer using the functions
+   <code class="function">SPI_keepplan</code> or <code class="function">SPI_saveplan</code>.
+  </p></div><div class="refsect1" id="id-1.8.12.8.7.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><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">int <em class="parameter"><code>nargs</code></em></code></span></dt><dd><p>
+      number of input parameters (<code class="literal">$1</code>, <code class="literal">$2</code>, etc.)
+     </p></dd><dt><span class="term"><code class="literal">Oid * <em class="parameter"><code>argtypes</code></em></code></span></dt><dd><p>
+      pointer to an array containing the <acronym class="acronym">OID</acronym>s of
+      the data types of the parameters
+     </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.7.7"><h2>Return Value</h2><p>
+   <code class="function">SPI_prepare</code> returns a non-null pointer to an
+   <code class="type">SPIPlan</code>, which is an opaque struct representing a prepared
+   statement.  On error, <code class="symbol">NULL</code> will be returned,
+   and <code class="varname">SPI_result</code> will be set to one of the same
+   error codes used by <code class="function">SPI_execute</code>, except that
+   it is set to <code class="symbol">SPI_ERROR_ARGUMENT</code> if
+   <em class="parameter"><code>command</code></em> is <code class="symbol">NULL</code>, or if
+   <em class="parameter"><code>nargs</code></em> is less than 0, or if <em class="parameter"><code>nargs</code></em> is
+   greater than 0 and <em class="parameter"><code>argtypes</code></em> is <code class="symbol">NULL</code>.
+  </p></div><div class="refsect1" id="id-1.8.12.8.7.8"><h2>Notes</h2><p>
+   If no parameters are defined, a generic plan will be created at the
+   first use of <code class="function">SPI_execute_plan</code>, and used for all
+   subsequent executions as well.  If there are parameters, the first few uses
+   of <code class="function">SPI_execute_plan</code> will generate custom plans
+   that are specific to the supplied parameter values.  After enough uses
+   of the same prepared statement, <code class="function">SPI_execute_plan</code> will
+   build a generic plan, and if that is not too much more expensive than the
+   custom plans, it will start using the generic plan instead of re-planning
+   each time.  If this default behavior is unsuitable, you can alter it by
+   passing the <code class="literal">CURSOR_OPT_GENERIC_PLAN</code> or
+   <code class="literal">CURSOR_OPT_CUSTOM_PLAN</code> flag to
+   <code class="function">SPI_prepare_cursor</code>, to force use of generic or custom
+   plans respectively.
+  </p><p>
+   Although the main point of a prepared statement is to avoid repeated parse
+   analysis and planning of the statement, <span class="productname">PostgreSQL</span> will
+   force re-analysis and re-planning of the statement before using it
+   whenever database objects used in the statement have undergone
+   definitional (DDL) changes since the previous use of the prepared
+   statement.  Also, if the value of <a class="xref" href="runtime-config-client.html#GUC-SEARCH-PATH">search_path</a> changes
+   from one use to the next, the statement will be re-parsed using the new
+   <code class="varname">search_path</code>.  (This latter behavior is new as of
+   <span class="productname">PostgreSQL</span> 9.3.)  See <a class="xref" href="sql-prepare.html" title="PREPARE"><span class="refentrytitle">PREPARE</span></a> for more information about the behavior of prepared
+   statements.
+  </p><p>
+   This function should only be called from a connected C function.
+  </p><p>
+   <code class="type">SPIPlanPtr</code> is declared as a pointer to an opaque struct type in
+   <code class="filename">spi.h</code>.  It is unwise to try to access its contents
+   directly, as that makes your code much more likely to break in
+   future revisions of <span class="productname">PostgreSQL</span>.
+  </p><p>
+   The name <code class="type">SPIPlanPtr</code> is somewhat historical, since the data
+   structure no longer necessarily contains an execution plan.
+  </p></div></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-execute-with-args.html" title="SPI_execute_with_args">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="46.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-prepare-cursor.html" title="SPI_prepare_cursor">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_execute_with_args </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_prepare_cursor</td></tr></table></div></body></html>
+\ No newline at end of file
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-04 12:19:15 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-04 12:19:15 +0000
commit	6eb9c5a5657d1fe77b55cc261450f3538d35a94d (patch)
tree	657d8194422a5daccecfd42d654b8a245ef7b4c8 /doc/src/sgml/html/spi-spi-prepare.html
parent	Initial commit. (diff)
download	postgresql-13-6eb9c5a5657d1fe77b55cc261450f3538d35a94d.tar.xz postgresql-13-6eb9c5a5657d1fe77b55cc261450f3538d35a94d.zip