Home Explore Blog CI



postgresql

46th chunk of `doc/src/sgml/spi.sgml`
9d4fef50d54d9bd9c9fb10f29b5ca6816d69407f219a802a0000000100000fa9
 <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>ncols</parameter>, describing which
      new values are null
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_modifytuple</function> assumes that no new values
      are null.  Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding new value is
      non-null, or <literal>'n'</literal> if the corresponding new value is
      null.  (In the latter case, the actual value in the corresponding
      <parameter>values</parameter> entry doesn't matter.)  Note that
      <parameter>nulls</parameter> is not a text string, just an array: it
      does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   new row with modifications, allocated in the upper executor
   context, or <symbol>NULL</symbol> on error
   (see <varname>SPI_result</varname> for an error indication)
  </para>

  <para>
   On error, <varname>SPI_result</varname> is set as follows:
   <variablelist>
    <varlistentry>
     <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       if <parameter>rel</parameter> is <symbol>NULL</symbol>, or if
       <parameter>row</parameter> is <symbol>NULL</symbol>, or if <parameter>ncols</parameter>
       is less than or equal to 0, or if <parameter>colnum</parameter> is
       <symbol>NULL</symbol>, or if <parameter>values</parameter> is <symbol>NULL</symbol>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_NOATTRIBUTE</symbol></term>
     <listitem>
      <para>
       if <parameter>colnum</parameter> contains an invalid column number (less
       than or equal to 0 or greater than the number of columns in
       <parameter>row</parameter>)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
     <listitem>
      <para>
       if SPI is not active
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-freetuple">
 <indexterm><primary>SPI_freetuple</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_freetuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freetuple</refname>
  <refpurpose>free a row allocated in the upper executor context</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
void SPI_freetuple(HeapTuple <parameter>row</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_freetuple</function> frees a row previously allocated
   in the upper executor context.
  </para>

  <para>
   This function is no longer different from plain
   <function>heap_freetuple</function>.  It's kept just for backward
   compatibility of existing code.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      row to free
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-freetupletable">
 <indexterm><primary>SPI_freetuptable</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_freetuptable</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freetuptable</refname>
  <refpurpose>free a row set created by <function>SPI_execute</function> or a similar
  function</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)
</synopsis>

Title: SPI_modifytuple Return Values and Error Conditions & SPI_freetuple: Freeing Rows in SPI
Summary
This section details the return values of the `SPI_modifytuple` function, which returns a new, modified row allocated in the upper executor context or NULL on error. It specifies error conditions that set the `SPI_result` variable, including invalid arguments, invalid column numbers, and SPI inactivity. It also describes `SPI_freetuple`, a function for freeing rows allocated in the upper executor context, noting it is kept for backward compatibility and is now equivalent to `heap_freetuple`.