EVOLUTION-MANAGER

Edit File: SPI_execute_extended.3

'\" t .\" Title: SPI_execute_extended .\" Author: The PostgreSQL Global Development Group .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> .\" Date: 2025 .\" Manual: PostgreSQL 14.18 Documentation .\" Source: PostgreSQL 14.18 .\" Language: English .\" .TH "SPI_EXECUTE_EXTENDED" "3" "2025" "PostgreSQL 14.18" "PostgreSQL 14.18 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_execute_extended \- execute a command with out\-of\-line parameters .SH "SYNOPSIS" .sp .nf int SPI_execute_extended(const char *\fIcommand\fR, const SPIExecuteOptions * \fIoptions\fR) .fi .SH "DESCRIPTION" .PP \fBSPI_execute_extended\fR executes a command that might include references to externally supplied parameters\&. The command text refers to a parameter as $\fIn\fR, and the \fIoptions\->params\fR object (if supplied) provides values and type information for each such symbol\&. Various execution options can be specified in the \fIoptions\fR struct, too\&. .PP The \fIoptions\->params\fR object should normally mark each parameter with the PARAM_FLAG_CONST flag, since a one\-shot plan is always used for the query\&. .PP If \fIoptions\->dest\fR is not NULL, then result tuples are passed to that object as they are generated by the executor, instead of being accumulated in \fISPI_tuptable\fR\&. Using a caller\-supplied DestReceiver object is particularly helpful for queries that might generate many tuples, since the data can be processed on\-the\-fly instead of being accumulated in memory\&. .SH "ARGUMENTS" .PP const char * \fIcommand\fR .RS 4 command string .RE .PP const SPIExecuteOptions * \fIoptions\fR .RS 4 struct containing optional arguments .RE .PP Callers should always zero out the entire \fIoptions\fR struct, then fill whichever fields they want to set\&. This ensures forward compatibility of code, since any fields that are added to the struct in future will be defined to behave backwards\-compatibly if they are zero\&. The currently available \fIoptions\fR fields are: .PP ParamListInfo \fIparams\fR .RS 4 data structure containing query parameter types and values; NULL if none .RE .PP bool \fIread_only\fR .RS 4 true for read\-only execution .RE .PP bool \fIallow_nonatomic\fR .RS 4 true allows non\-atomic execution of CALL and DO statements (but this field is ignored unless the SPI_OPT_NONATOMIC flag was passed to \fBSPI_connect_ext\fR) .RE .PP bool \fImust_return_tuples\fR .RS 4 if true, raise error if the query is not of a kind that returns tuples (this does not forbid the case where it happens to return zero tuples) .RE .PP uint64 \fItcount\fR .RS 4 maximum number of rows to return, or 0 for no limit .RE .PP DestReceiver * \fIdest\fR .RS 4 DestReceiver object that will receive any tuples emitted by the query; if NULL, result tuples are accumulated into a \fISPI_tuptable\fR structure, as in \fBSPI_execute\fR .RE .PP ResourceOwner \fIowner\fR .RS 4 This field is present for consistency with \fBSPI_execute_plan_extended\fR, but it is ignored, since the plan used by \fBSPI_execute_extended\fR is never saved\&. .RE .SH "RETURN VALUE" .PP The return value is the same as for \fBSPI_execute\fR\&. .PP When \fIoptions\->dest\fR is NULL, \fISPI_processed\fR and \fISPI_tuptable\fR are set as in \fBSPI_execute\fR\&. When \fIoptions\->dest\fR is not NULL, \fISPI_processed\fR is set to zero and \fISPI_tuptable\fR is set to NULL\&. If a tuple count is required, the caller\*(Aqs DestReceiver object must calculate it\&.