diff options
Diffstat (limited to 'doc/src/sgml/html/spi-spi-prepare.html')
| -rw-r--r-- | doc/src/sgml/html/spi-spi-prepare.html | 84 |
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 |