'\" t
.\"     Title: SPI_modifytuple
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 2016
.\"    Manual: PostgreSQL 9.5.2 Documentation
.\"    Source: PostgreSQL 9.5.2
.\"  Language: English
.\"
.TH "SPI_MODIFYTUPLE" "3" "2016" "PostgreSQL 9.5.2" "PostgreSQL 9.5.2 Documentation"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
SPI_modifytuple \- create a row by replacing selected fields of a given row
.SH "SYNOPSIS"
.sp
.nf
HeapTuple SPI_modifytuple(Relation \fIrel\fR, HeapTuple \fIrow\fR, int \fIncols\fR,
                          int * \fIcolnum\fR, Datum * \fIvalues\fR, const char * \fInulls\fR)
.fi
.SH "DESCRIPTION"
.PP

\fBSPI_modifytuple\fR
creates a new row by substituting new values for selected columns, copying the original row\(aqs columns at other positions\&. The input row is not modified\&.
.SH "ARGUMENTS"
.PP
Relation \fIrel\fR
.RS 4
Used only as the source of the row descriptor for the row\&. (Passing a relation rather than a row descriptor is a misfeature\&.)
.RE
.PP
HeapTuple \fIrow\fR
.RS 4
row to be modified
.RE
.PP
int \fIncols\fR
.RS 4
number of columns to be changed
.RE
.PP
int * \fIcolnum\fR
.RS 4
an array of length
\fIncols\fR, containing the numbers of the columns that are to be changed (column numbers start at 1)
.RE
.PP
Datum * \fIvalues\fR
.RS 4
an array of length
\fIncols\fR, containing the new values for the specified columns
.RE
.PP
const char * \fInulls\fR
.RS 4
an array of length
\fIncols\fR, describing which new values are null
.sp
If
\fInulls\fR
is
NULL
then
\fBSPI_modifytuple\fR
assumes that no new values are null\&. Otherwise, each entry of the
\fInulls\fR
array should be
\(aq\ \&\(aq
if the corresponding new value is non\-null, or
\(aqn\(aq
if the corresponding new value is null\&. (In the latter case, the actual value in the corresponding
\fIvalues\fR
entry doesn\(aqt matter\&.) Note that
\fInulls\fR
is not a text string, just an array: it does not need a
\(aq\e0\(aq
terminator\&.
.RE
.SH "RETURN VALUE"
.PP
new row with modifications, allocated in the upper executor context;
NULL
only if
\fIrow\fR
is
NULL
.PP
On error,
\fISPI_result\fR
is set as follows:
.PP
SPI_ERROR_ARGUMENT
.RS 4
if
\fIrel\fR
is
NULL, or if
\fIrow\fR
is
NULL, or if
\fIncols\fR
is less than or equal to 0, or if
\fIcolnum\fR
is
NULL, or if
\fIvalues\fR
is
NULL\&.
.RE
.PP
SPI_ERROR_NOATTRIBUTE
.RS 4
if
\fIcolnum\fR
contains an invalid column number (less than or equal to 0 or greater than the number of column in
\fIrow\fR)
.RE