Current File : //proc/thread-self/root/proc/self/root/opt/alt/postgresql11/usr/share/man/man3/SPI_prepare.3
'\" t
.\" Title: SPI_prepare
.\" Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 2017-11-06
.\" Manual: PostgreSQL 9.2.24 Documentation
.\" Source: PostgreSQL 9.2.24
.\" Language: English
.\"
.TH "SPI_PREPARE" "3" "2017-11-06" "PostgreSQL 9.2.24" "PostgreSQL 9.2.24 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
SPI_prepare \- prepare a statement, without executing it yet
.\" SPI_prepare
.SH "SYNOPSIS"
.sp
.nf
SPIPlanPtr SPI_prepare(const char * \fIcommand\fR, int \fInargs\fR, Oid * \fIargtypes\fR)
.fi
.SH "DESCRIPTION"
.PP
\fBSPI_prepare\fR
creates and returns a prepared statement for the specified command, but doesn\*(Aqt execute the command\&. The prepared statement can later be executed repeatedly using
\fBSPI_execute_plan\fR\&.
.PP
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\&.
\fBSPI_prepare\fR
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\&.
.PP
A prepared command can be generalized by writing parameters ($1,
$2, etc\&.) in place of what would be constants in a normal command\&. The actual values of the parameters are then specified when
\fBSPI_execute_plan\fR
is called\&. This allows the prepared command to be used over a wider range of situations than would be possible without parameters\&.
.PP
The statement returned by
\fBSPI_prepare\fR
can be used only in the current invocation of the procedure, since
\fBSPI_finish\fR
frees memory allocated for such a statement\&. But the statement can be saved for longer using the functions
\fBSPI_keepplan\fR
or
\fBSPI_saveplan\fR\&.
.SH "ARGUMENTS"
.PP
const char * \fIcommand\fR
.RS 4
command string
.RE
.PP
int \fInargs\fR
.RS 4
number of input parameters ($1,
$2, etc\&.)
.RE
.PP
Oid * \fIargtypes\fR
.RS 4
pointer to an array containing the
OIDs of the data types of the parameters
.RE
.SH "RETURN VALUE"
.PP
\fBSPI_prepare\fR
returns a non\-null pointer to an
SPIPlan, which is an opaque struct representing a prepared statement\&. On error,
NULL
will be returned, and
\fISPI_result\fR
will be set to one of the same error codes used by
\fBSPI_execute\fR, except that it is set to
SPI_ERROR_ARGUMENT
if
\fIcommand\fR
is
NULL, or if
\fInargs\fR
is less than 0, or if
\fInargs\fR
is greater than 0 and
\fIargtypes\fR
is
NULL\&.
.SH "NOTES"
.PP
If no parameters are defined, a generic plan will be created at the first use of
\fBSPI_execute_plan\fR, and used for all subsequent executions as well\&. If there are parameters, the first few uses of
\fBSPI_execute_plan\fR
will generate custom plans that are specific to the supplied parameter values\&. After enough uses of the same prepared statement,
\fBSPI_execute_plan\fR
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
CURSOR_OPT_GENERIC_PLAN
or
CURSOR_OPT_CUSTOM_PLAN
flag to
\fBSPI_prepare_cursor\fR, to force use of generic or custom plans respectively\&.
.PP
This function should only be called from a connected procedure\&.
.PP
SPIPlanPtr
is declared as a pointer to an opaque struct type in
spi\&.h\&. It is unwise to try to access its contents directly, as that makes your code much more likely to break in future revisions of
PostgreSQL\&.
.PP
The name
SPIPlanPtr
is somewhat historical, since the data structure no longer necessarily contains an execution plan\&.
Mini Shell