codekingpro/portable-devtools

1<?xml version="1.0" encoding="UTF-8" standalone="no"?>2<!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_modifytuple</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 Vsnapshot" /><link rel="prev" href="spi-spi-returntuple.html" title="SPI_returntuple" /><link rel="next" href="spi-spi-freetuple.html" title="SPI_freetuple" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_modifytuple</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-returntuple.html" title="SPI_returntuple">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><th width="60%" align="center">47.3. Memory Management</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-freetuple.html" title="SPI_freetuple">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-MODIFYTUPLE"><div class="titlepage"></div><a id="id-1.8.12.10.11.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_modifytuple</span></h2><p>SPI_modifytuple — create a row by replacing selected fields of a given row</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">3HeapTuple SPI_modifytuple(Relation <em class="parameter"><code>rel</code></em>, HeapTuple <em class="parameter"><code>row</code></em>, int <em class="parameter"><code>ncols</code></em>,4                          int * <em class="parameter"><code>colnum</code></em>, Datum * <em class="parameter"><code>values</code></em>, const char * <em class="parameter"><code>nulls</code></em>)5</pre></div><div class="refsect1" id="id-1.8.12.10.11.5"><h2>Description</h2><p>6   <code class="function">SPI_modifytuple</code> creates a new row by7   substituting new values for selected columns, copying the original8   row's columns at other positions.  The input row is not modified.9   The new row is returned in the upper executor context.10  </p><p>11   This function can only be used while connected to SPI.12   Otherwise, it returns NULL and sets <code class="varname">SPI_result</code> to13   <code class="symbol">SPI_ERROR_UNCONNECTED</code>.14  </p></div><div class="refsect1" id="id-1.8.12.10.11.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">Relation <em class="parameter"><code>rel</code></em></code></span></dt><dd><p>15      Used only as the source of the row descriptor for the row.16      (Passing a relation rather than a row descriptor is a17      misfeature.)18     </p></dd><dt><span class="term"><code class="literal">HeapTuple <em class="parameter"><code>row</code></em></code></span></dt><dd><p>19      row to be modified20     </p></dd><dt><span class="term"><code class="literal">int <em class="parameter"><code>ncols</code></em></code></span></dt><dd><p>21      number of columns to be changed22     </p></dd><dt><span class="term"><code class="literal">int * <em class="parameter"><code>colnum</code></em></code></span></dt><dd><p>23      an array of length <em class="parameter"><code>ncols</code></em>, containing the numbers24      of the columns that are to be changed (column numbers start at 1)25     </p></dd><dt><span class="term"><code class="literal">Datum * <em class="parameter"><code>values</code></em></code></span></dt><dd><p>26      an array of length <em class="parameter"><code>ncols</code></em>, containing the27      new values for the specified columns28     </p></dd><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>nulls</code></em></code></span></dt><dd><p>29      an array of length <em class="parameter"><code>ncols</code></em>, describing which30      new values are null31     </p><p>32      If <em class="parameter"><code>nulls</code></em> is <code class="symbol">NULL</code> then33      <code class="function">SPI_modifytuple</code> assumes that no new values34      are null.  Otherwise, each entry of the <em class="parameter"><code>nulls</code></em>35      array should be <code class="literal">' '</code> if the corresponding new value is36      non-null, or <code class="literal">'n'</code> if the corresponding new value is37      null.  (In the latter case, the actual value in the corresponding38      <em class="parameter"><code>values</code></em> entry doesn't matter.)  Note that39      <em class="parameter"><code>nulls</code></em> is not a text string, just an array: it40      does not need a <code class="literal">'\0'</code> terminator.41     </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.10.11.7"><h2>Return Value</h2><p>42   new row with modifications, allocated in the upper executor43   context, or <code class="symbol">NULL</code> on error44   (see <code class="varname">SPI_result</code> for an error indication)45  </p><p>46   On error, <code class="varname">SPI_result</code> is set as follows:47   </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>48       if <em class="parameter"><code>rel</code></em> is <code class="symbol">NULL</code>, or if49       <em class="parameter"><code>row</code></em> is <code class="symbol">NULL</code>, or if <em class="parameter"><code>ncols</code></em>50       is less than or equal to 0, or if <em class="parameter"><code>colnum</code></em> is51       <code class="symbol">NULL</code>, or if <em class="parameter"><code>values</code></em> is <code class="symbol">NULL</code>.52      </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_NOATTRIBUTE</code></span></dt><dd><p>53       if <em class="parameter"><code>colnum</code></em> contains an invalid column number (less54       than or equal to 0 or greater than the number of columns in55       <em class="parameter"><code>row</code></em>)56      </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>57       if SPI is not active58      </p></dd></dl></div><p>59  </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-returntuple.html" title="SPI_returntuple">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-memory.html" title="47.3. Memory Management">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-freetuple.html" title="SPI_freetuple">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_returntuple </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_freetuple</td></tr></table></div></body></html>