Home • Explore • Blog • CI
☰



postgresql
38th chunk of `doc/src/sgml/spi.sgml`
978be48fde964016e94ef9151c68e1da03beb12ff4d88fae0000000100000fa1
 <refname>SPI_getvalue</refname>
  <refpurpose>return the string value of the specified column</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
char * SPI_getvalue(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_getvalue</function> returns the string representation
   of the value of the specified column.
  </para>

  <para>
   The result is returned in memory allocated using
   <function>palloc</function>.  (You can use
   <function>pfree</function> to release the memory when you don't
   need it anymore.)
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

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

   <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>
   Column value, or <symbol>NULL</symbol> if the column is null,
   <parameter>colnumber</parameter> is out of range
   (<varname>SPI_result</varname> is set to
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol>), or no output function is
   available (<varname>SPI_result</varname> is set to
   <symbol>SPI_ERROR_NOOUTFUNC</symbol>).
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-getbinval">
 <indexterm><primary>SPI_getbinval</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_getbinval</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_getbinval</refname>
  <refpurpose>return the binary value of the specified column</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
Datum SPI_getbinval(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>,
                    bool * <parameter>isnull</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_getbinval</function> returns the value of the
   specified column in the internal form (as type <type>Datum</type>).
  </para>

  <para>
   This function does not allocate new space for the datum.  In the
   case of a pass-by-reference data type, the return value will be a
   pointer into the passed row.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

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

   <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>

   <varlistentry>
    <term><literal>bool * <parameter>isnull</parameter></literal></term>
    <listitem>
     <para>
      flag for a null value in the column
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The binary value of the column is returned.  The variable pointed
   to by <parameter>isnull</parameter> is set to true if the column is
   null, else to false.
  </para>

  <para>
Title: SPI_getvalue and SPI_getbinval Functions
Summary
This section details the `SPI_getvalue` and `SPI_getbinval` functions. `SPI_getvalue` returns the string representation of a specified column, allocating memory using `palloc` which must be freed with `pfree`. It returns NULL if the column is null, out of range, or if no output function is available. `SPI_getbinval` returns the binary value of a specified column as a `Datum`. It does not allocate new space, and the return value might be a pointer into the passed row for pass-by-reference types. A boolean pointer is used to indicate whether the column is null.