Home • Explore • Blog • CI
☰



postgresql
44th chunk of `doc/src/sgml/spi.sgml`
5f7f7630c60439cb2f1e46871cca524a6041a9debc050f710000000100000fb4
 context</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_copytuple</function> makes a copy of a row in the
   upper executor context.  This is normally used to return a modified
   row from a trigger.  In a function declared to return a composite
   type, use <function>SPI_returntuple</function> instead.
  </para>

  <para>
   This function can only be used while connected to SPI.
   Otherwise, it returns NULL and sets <varname>SPI_result</varname> to
   <symbol>SPI_ERROR_UNCONNECTED</symbol>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      row to be copied
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   the copied row, or <symbol>NULL</symbol> on error
   (see <varname>SPI_result</varname> for an error indication)
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-returntuple">
 <indexterm><primary>SPI_returntuple</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_returntuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_returntuple</refname>
  <refpurpose>prepare to return a tuple as a Datum</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_returntuple</function> makes a copy of a row in
   the upper executor context, returning it in the form of a row type <type>Datum</type>.
   The returned pointer need only be converted to <type>Datum</type> via <function>PointerGetDatum</function>
   before returning.
  </para>

  <para>
   This function can only be used while connected to SPI.
   Otherwise, it returns NULL and sets <varname>SPI_result</varname> to
   <symbol>SPI_ERROR_UNCONNECTED</symbol>.
  </para>

  <para>
   Note that this should be used for functions that are declared to return
   composite types.  It is not used for triggers; use
   <function>SPI_copytuple</function> for returning a modified row in a trigger.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      row to be copied
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      descriptor for row (pass the same descriptor each time for most
      effective caching)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   <type>HeapTupleHeader</type> pointing to copied row,
   or <symbol>NULL</symbol> on error
   (see <varname>SPI_result</varname> for an error indication)
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-modifytuple">
 <indexterm><primary>SPI_modifytuple</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_modifytuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_modifytuple</refname>
  <refpurpose>create a row by replacing selected fields of a given row</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parameter>row</parameter>, int <parameter>ncols</parameter>,
                          int * <parameter>colnum</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>)
Title: SPI Tuple Handling Functions: SPI_copytuple, SPI_returntuple, and SPI_modifytuple
Summary
This section describes three SPI functions related to tuple manipulation. `SPI_copytuple` creates a copy of a row (HeapTuple) in the upper executor context, commonly used in triggers to return modified rows. `SPI_returntuple` also copies a row but returns it as a row type Datum, meant for functions returning composite types. Both functions return NULL and set SPI_result to SPI_ERROR_UNCONNECTED if not connected to SPI. The section begins to introduce `SPI_modifytuple`, used for creating a row by replacing selected fields of an existing row.