spi.sgml

PostgreSQL7.4.6 for Linux

   The data type name of the specified column, or
   <symbol>NULL</symbol> on error.  <varname>SPI_result</varname> is
   set to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-gettypeid">
 <refmeta>
  <refentrytitle>SPI_gettypeid</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_gettypeid</refname>
  <refpurpose>return the data type <acronym>OID</acronym> of the specified column</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_gettypeid</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
Oid SPI_gettypeid(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_gettypeid</function> returns the
   <acronym>OID</acronym> of the data type of the specified column.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      input row description
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>colnumber</parameter></literal></term>
    <listitem>
     <para>
      column number (count starts at 1)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The <acronym>OID</acronym> of the data type of the specified column
   or <symbol>InvalidOid</symbol> on error.  On error,
   <varname>SPI_result</varname> is set to
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol>.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-getrelname">
 <refmeta>
  <refentrytitle>SPI_getrelname</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_getrelname</refname>
  <refpurpose>return the name of the specified relation</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_getrelname</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
char * SPI_getrelname(Relation <parameter>rel</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_getrelname</function> returns the name of the
   specified relation.  (You can use <function>pfree</function> to
   release the copy of the name when you don't need it anymore.)
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Relation <parameter>rel</parameter></literal></term>
    <listitem>
     <para>
      input relation
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The name of the specified relation.
  </para>
 </refsect1>
</refentry>

 </sect1>

 <sect1 id="spi-memory">
  <title>Memory Management</title>

  <para>
   <productname>PostgreSQL</productname> allocates memory within
   <firstterm>memory contexts</firstterm><indexterm><primary>memory
   context</primary><secondary>in SPI</secondary></indexterm>, which provide a convenient method of
   managing allocations made in many different places that need to
   live for differing amounts of time.  Destroying a context releases
   all the memory that was allocated in it.  Thus, it is not necessary
   to keep track of individual objects to avoid memory leaks; instead
   only a relatively small number of contexts have to be managed.
   <function>palloc</function> and related functions allocate memory
   from the <quote>current</> context.
  </para>

  <para>
   <function>SPI_connect</function> creates a new memory context and
   makes it current.  <function>SPI_finish</function> restores the
   previous current memory context and destroys the context created by
   <function>SPI_connect</function>.  These actions ensure that
   transient memory allocations made inside your procedure are
   reclaimed at procedure exit, avoiding memory leakage.
  </para>

  <para>
   However, if your procedure needs to return an object in allocated
   memory (such as a value of a pass-by-reference data type), you
   cannot allocate that memory using <function>palloc</function>, at
   least not while you are connected to SPI.  If you try, the object
   will be deallocated by <function>SPI_finish</function>, and your
   procedure will not work reliably.  To solve this problem, use
   <function>SPI_palloc</function> to allocate memory for your return
   object.  <function>SPI_palloc</function> allocates memory in the
   <quote>upper executor context</quote>, that is, the memory context
   that was current when <function>SPI_connect</function> was called,
   which is precisely the right context for return a value from your
   procedure.
  </para>

  <para>
   If <function>SPI_palloc</function> is called while the procedure is
   not connected to SPI, then it acts the same as a normal
   <function>palloc</function>.  Before a procedure connects to the
   SPI manager, the current memory context is the upper executor
   context, so all allocations made by the procedure via
   <function>palloc</function> or by SPI utility functions are made in
   this context.
  </para>

  <para>
   When <function>SPI_connect</function> is called, the private
   context of the procedure, which is created by
   <function>SPI_connect</function>, is made the current context.  All
   allocations made by <function>palloc</function>,
   <function>repalloc</function>, or SPI utility functions (except for
   <function>SPI_copytuple</function>,
   <function>SPI_copytupledesc</function>,
   <function>SPI_copytupleintoslot</function>,
   <function>SPI_modifytuple</function>, and
   <function>SPI_palloc</function>) are made in this context.  When a
   procedure disconnects from the SPI manager (via
   <function>SPI_finish</function>) the current context is restored to
   the upper executor context, and all allocations made in the
   procedure memory context are freed and cannot be used any more.
  </para>

  <para>
   All functions described in this section may be used by both
   connected and unconnected procedures.  In an unconnected procedure,
   they act the same as the underlying ordinary server functions
   (<function>palloc</>, etc.).
  </para>

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

<refentry id="spi-spi-palloc">
 <refmeta>
  <refentrytitle>SPI_palloc</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_palloc</refname>
  <refpurpose>allocate memory in the upper executor context</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_palloc</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
void * SPI_palloc(Size <parameter>size</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_palloc</function> allocates memory in the upper
   executor context.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Size <parameter>size</parameter></literal></term>
    <listitem>
     <para>
      size in bytes of storage to allocate
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   pointer to new storage space of the specified size
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-realloc">
 <refmeta>
  <refentrytitle>SPI_repalloc</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_repalloc</refname>
  <refpurpose>reallocate memory in the upper executor context</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_repalloc</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_repalloc</function> changes the size of a memory
   segment previously allocated using <function>SPI_palloc</function>.
  </para>

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

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>pointer</parameter></literal></term>
    <listitem>
     <para>
      pointer to existing storage to change
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Size <parameter>size</parameter></literal></term>
    <listitem>
     <para>
      size in bytes of storage to allocate
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   pointer to new storage space of specified size with the contents
   copied from the existing area
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-pfree">
 <refmeta>
  <refentrytitle>SPI_pfree</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_pfree</refname>
  <refpurpose>free memory in the upper executor context</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_pfree</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
void SPI_pfree(void * <parameter>pointer</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_pfree</function> frees memory previously allocated
   using <function>SPI_palloc</function> or
   <function>SPI_repalloc</function>.
  </para>

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

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>pointer</parameter></literal></term>
    <listitem>
     <para>
      pointer to existing storage to free
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-copytuple">
 <refmeta>
  <refentrytitle>SPI_copytuple</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_copytuple</refname>
  <refpurpose>make a copy of a row in the upper executor context</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_copytuple</primary></indexterm>

 <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.
  </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; <symbol>NULL</symbol> only if
   <parameter>tuple</parameter> is <symbol>NULL</symbol>
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-copytupledesc">
 <refmeta>
  <refentrytitle>SPI_copytupledesc</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_copytupledesc</refname>
  <refpurpose>make a copy of a row descriptor in the upper executor context</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_copytupledesc</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
TupleDesc SPI_copytupledesc(TupleDesc <parameter>tupdesc</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_copytupledesc</function> makes a copy of a row
   descriptor in the upper executor context.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>TupleDesc <parameter>tupdesc</parameter></literal></term>
    <listitem>
     <para>
      row descriptor to be copied
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   the copied row descriptor; <symbol>NULL</symbol> only if
   <parameter>tupdesc</parameter> is <symbol>NULL</symbol>
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-copytupleintoslot">
 <refmeta>
  <refentrytitle>SPI_copytupleintoslot</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_copytupleintoslot</refname>
  <refpurpose>make a copy of a row and descriptor in the upper executor context</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_copytupleintoslot</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
TupleTableSlot * SPI_copytupleintoslot(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>