granicus.if.org Git - postgresql/blob - doc/src/sgml/spi.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.33 2004/03/17 01:05:10 momjian Exp $
   3 -->
   4
   5 <chapter id="spi">
   6  <title>Server Programming Interface</title>
   7
   8  <indexterm zone="spi">
   9   <primary>SPI</primary>
  10  </indexterm>
  11
  12  <para>
  13   The <firstterm>Server Programming Interface</firstterm>
  14   (<acronym>SPI</acronym>) gives writers of user-defined
  15   <acronym>C</acronym> functions the ability to run
  16   <acronym>SQL</acronym> commands inside their functions.
  17   <acronym>SPI</acronym> is a set of
  18   interface functions to simplify access to the parser, planner,
  19   optimizer, and executor. <acronym>SPI</acronym> also does some
  20   memory management.
  21  </para>
  22
  23  <note>
  24   <para>
  25    The available procedural languages provide various means to
  26    execute SQL commands from procedures.  Some of these are based on or
  27    modelled after SPI, so this documentation might be of use for users
  28    of those languages as well.
  29   </para>
  30  </note>
  31
  32  <para>
  33   To avoid misunderstanding we'll use the term <quote>function</quote>
  34   when we speak of <acronym>SPI</acronym> interface functions and
  35   <quote>procedure</quote> for a user-defined C-function that is
  36   using <acronym>SPI</acronym>.
  37  </para>
  38
  39  <para>
  40   Note that if during the execution of a procedure the transaction is
  41   aborted because of an error in a command, then control will not be
  42   returned to your procedure.  Rather, all work will be rolled back
  43   and the server will wait for the next command from the client.  A
  44   related restriction is the inability to execute
  45   <command>BEGIN</command>, <command>COMMIT</command>, and
  46   <command>ROLLBACK</command> (transaction control statements) inside
  47   a procedure.  Both of these restrictions will probably be changed in
  48   the future.
  49  </para>
  50
  51  <para>
  52   <acronym>SPI</acronym> functions return a nonnegative result on
  53   success (either via a returned integer value or in the global
  54   variable <varname>SPI_result</varname>, as described below).  On
  55   error, a negative result or <symbol>NULL</symbol> will be returned.
  56  </para>
  57
  58  <para>
  59   Source code files that use SPI must include the header file
  60   <filename>executor/spi.h</filename>.
  61  </para>
  62
  63
  64 <sect1 id="spi-interface">
  65  <title>Interface Functions</title>
  66
  67  <refentry id="spi-spi-connect">
  68   <refmeta>
  69    <refentrytitle>SPI_connect</refentrytitle>
  70   </refmeta>
  71
  72   <refnamediv>
  73    <refname>SPI_connect</refname>
  74    <refpurpose>connect a procedure to the SPI manager</refpurpose>
  75  </refnamediv>
  76
  77  <indexterm><primary>SPI_connect</primary></indexterm>
  78
  79  <refsynopsisdiv>
  80 <synopsis>
  81 int SPI_connect(void)
  82 </synopsis>
  83  </refsynopsisdiv>
  84
  85  <refsect1>
  86   <title>Description</title>
  87
  88   <para>
  89    <function>SPI_connect</function> opens a connection from a
  90    procedure invocation to the SPI manager.  You must call this
  91    function if you want to execute commands through SPI.  Some utility
  92    SPI functions may be called from unconnected procedures.
  93   </para>
  94
  95   <para>
  96    If your procedure is already connected,
  97    <function>SPI_connect</function> will return the error code
  98    <returnvalue>SPI_ERROR_CONNECT</returnvalue>.  This could happen if
  99    a procedure that has called <function>SPI_connect</function>
 100    directly calls another procedure that calls
 101    <function>SPI_connect</function>.  While recursive calls to the
 102    <acronym>SPI</acronym> manager are permitted when an SQL command
 103    called through SPI invokes another function that uses
 104    <acronym>SPI</acronym>, directly nested calls to
 105    <function>SPI_connect</function> and
 106    <function>SPI_finish</function> are forbidden.
 107   </para>
 108  </refsect1>
 109
 110  <refsect1>
 111   <title>Return Value</title>
 112
 113   <variablelist>
 114    <varlistentry>
 115     <term><symbol>SPI_OK_CONNECT</symbol></term>
 116     <listitem>
 117      <para>
 118       on success
 119      </para>
 120     </listitem>
 121    </varlistentry>
 122
 123    <varlistentry>
 124     <term><symbol>SPI_ERROR_CONNECT</symbol></term>
 125     <listitem>
 126      <para>
 127       on error
 128      </para>
 129     </listitem>
 130    </varlistentry>
 131   </variablelist>
 132  </refsect1>
 133 </refentry>
 134
 135 <!-- *********************************************** -->
 136
 137 <refentry id="spi-spi-finish">
 138  <refmeta>
 139   <refentrytitle>SPI_finish</refentrytitle>
 140  </refmeta>
 141
 142  <refnamediv>
 143   <refname>SPI_finish</refname>
 144   <refpurpose>disconnect a procedure from the SPI manager</refpurpose>
 145  </refnamediv>
 146
 147  <indexterm><primary>SPI_finish</primary></indexterm>
 148
 149  <refsynopsisdiv>
 150 <synopsis>
 151 int SPI_finish(void)
 152 </synopsis>
 153  </refsynopsisdiv>
 154
 155  <refsect1>
 156   <title>Description</title>
 157
 158   <para>
 159    <function>SPI_finish</function> closes an existing connection to
 160    the SPI manager.  You must call this function after completing the
 161    SPI operations needed during your procedure's current invocation.
 162    You do not need to worry about making this happen, however, if you
 163    abort the transaction via <literal>elog(ERROR)</literal>.  In that
 164    case SPI will clean itself up automatically.
 165   </para>
 166
 167   <para>
 168    If <function>SPI_finish</function> is called without having a valid
 169    connection, it will return <symbol>SPI_ERROR_UNCONNECTED</symbol>.
 170    There is no fundamental problem with this; it means that the SPI
 171    manager has nothing to do.
 172   </para>
 173  </refsect1>
 174
 175  <refsect1>
 176   <title>Return Value</title>
 177
 178   <variablelist>
 179    <varlistentry>
 180     <term><symbol>SPI_OK_FINISH</symbol></term>
 181     <listitem>
 182      <para>
 183       if properly disconnected
 184      </para>
 185     </listitem>
 186    </varlistentry>
 187
 188    <varlistentry>
 189     <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
 190     <listitem>
 191      <para>
 192       if called from an unconnected procedure
 193      </para>
 194     </listitem>
 195    </varlistentry>
 196   </variablelist>
 197  </refsect1>
 198 </refentry>
 199
 200 <!-- *********************************************** -->
 201
 202 <refentry id="spi-spi-push">
 203  <refmeta>
 204   <refentrytitle>SPI_push</refentrytitle>
 205  </refmeta>
 206
 207  <refnamediv>
 208   <refname>SPI_push</refname>
 209   <refpurpose>pushes SPI stack to allow recursive SPI calls</refpurpose>
 210  </refnamediv>
 211
 212  <indexterm><primary>SPI_push</primary></indexterm>
 213
 214  <refsynopsisdiv>
 215 <synopsis>
 216 void SPI_push(void)
 217 </synopsis>
 218  </refsynopsisdiv>
 219
 220  <refsect1>
 221   <title>Description</title>
 222
 223   <para>
 224    <function>SPI_push</function> pushes a new environment on to the
 225    SPI call stack, allowing recursive calls to use a new environment.
 226   </para>
 227  </refsect1>
 228
 229 </refentry>
 230
 231 <!-- *********************************************** -->
 232
 233 <refentry id="spi-spi-pop">
 234  <refmeta>
 235   <refentrytitle>SPI_pop</refentrytitle>
 236  </refmeta>
 237
 238  <refnamediv>
 239   <refname>SPI_pop</refname>
 240   <refpurpose>pops SPI stack to allow recursive SPI calls</refpurpose>
 241  </refnamediv>
 242
 243  <indexterm><primary>SPI_pop</primary></indexterm>
 244
 245  <refsynopsisdiv>
 246 <synopsis>
 247 void SPI_pop(void)
 248 </synopsis>
 249  </refsynopsisdiv>
 250
 251  <refsect1>
 252   <title>Description</title>
 253
 254   <para>
 255    <function>SPI_pop</function> pops the previous environment from the
 256    SPI call stack.  For use when returning from recursive SPI calls.
 257   </para>
 258  </refsect1>
 259
 260 </refentry>
 261
 262 <!-- *********************************************** -->
 263
 264 <refentry id="spi-spi-exec">
 265  <refmeta>
 266   <refentrytitle>SPI_exec</refentrytitle>
 267  </refmeta>
 268
 269  <refnamediv>
 270   <refname>SPI_exec</refname>
 271   <refpurpose>execute a command</refpurpose>
 272  </refnamediv>
 273
 274  <indexterm><primary>SPI_exec</primary></indexterm>
 275
 276  <refsynopsisdiv>
 277 <synopsis>
 278 int SPI_exec(const char * <parameter>command</parameter>, int <parameter>count</parameter>)
 279 </synopsis>
 280  </refsynopsisdiv>
 281
 282  <refsect1>
 283   <title>Description</title>
 284
 285   <para>
 286    <function>SPI_exec</function> executes the specified SQL command
 287    for <parameter>count</parameter> rows.
 288   </para>
 289
 290   <para>
 291    This function should only be called from a connected procedure.  If
 292    <parameter>count</parameter> is zero then it executes the command
 293    for all rows that it applies to.  If <parameter>count</parameter>
 294    is greater than 0, then the number of rows for which the command
 295    will be executed is restricted (much like a
 296    <literal>LIMIT</literal> clause). For example,
 297 <programlisting>
 298 SPI_exec("INSERT INTO tab SELECT * FROM tab", 5);
 299 </programlisting>
 300    will allow at most 5 rows to be inserted into the table.
 301   </para>
 302
 303   <para>
 304    You may pass multiple commands in one string, and the command may
 305    be rewritten by rules. <function>SPI_exec</function> returns the
 306    result for the command executed last.
 307   </para>
 308
 309   <para>
 310    The actual number of rows for which the (last) command was executed
 311    is returned in the global variable <varname>SPI_processed</varname>
 312    (unless the return value of the function is
 313    <symbol>SPI_OK_UTILITY</symbol>).  If the return value of the
 314    function is <symbol>SPI_OK_SELECT</symbol> then you may the use
 315    global pointer <literal>SPITupleTable *SPI_tuptable</literal> to
 316    access the result rows.
 317   </para>
 318
 319   <para>
 320    The structure <structname>SPITupleTable</structname> is defined
 321    thus:
 322 <programlisting>
 323 typedef struct
 324 {
 325     MemoryContext tuptabcxt;    /* memory context of result table */
 326     uint32      alloced;        /* number of alloced vals */
 327     uint32      free;           /* number of free vals */
 328     TupleDesc   tupdesc;        /* row descriptor */
 329     HeapTuple  *vals;           /* rows */
 330 } SPITupleTable;
 331 </programlisting>
 332    <structfield>vals</> is an array of pointers to rows.  (The number
 333    of valid entries is given by <varname>SPI_processed</varname>).
 334    <structfield>tupdesc</> is a row descriptor which you may pass to
 335    SPI functions dealing with rows.  <structfield>tuptabcxt</>,
 336    <structfield>alloced</>, and <structfield>free</> are internal
 337    fields not intended for use by SPI callers.
 338   </para>
 339
 340   <para>
 341    <function>SPI_finish</function> frees all
 342    <structname>SPITupleTable</>s allocated during the current
 343    procedure.  You can free a particular result table earlier, if you
 344    are done with it, by calling <function>SPI_freetuptable</function>.
 345   </para>
 346  </refsect1>
 347
 348  <refsect1>
 349   <title>Arguments</title>
 350
 351   <variablelist>
 352    <varlistentry>
 353     <term><literal>const char * <parameter>command</parameter></literal></term>
 354     <listitem>
 355      <para>
 356       string containing command to execute
 357      </para>
 358     </listitem>
 359    </varlistentry>
 360
 361    <varlistentry>
 362     <term><literal>int <parameter>count</parameter></literal></term>
 363     <listitem>
 364      <para>
 365       maximum number of rows to process or return
 366      </para>
 367     </listitem>
 368    </varlistentry>
 369   </variablelist>
 370  </refsect1>
 371
 372  <refsect1>
 373   <title>Return Value</title>
 374
 375   <para>
 376    If the execution of the command was successful then one of the
 377    following (nonnegative) values will be returned:
 378
 379    <variablelist>
 380     <varlistentry>
 381      <term><symbol>SPI_OK_SELECT</symbol></term>
 382      <listitem>
 383       <para>
 384        if a <command>SELECT</command> (but not <command>SELECT
 385        INTO</>) was executed
 386       </para>
 387      </listitem>
 388     </varlistentry>
 389
 390     <varlistentry>
 391      <term><symbol>SPI_OK_SELINTO</symbol></term>
 392      <listitem>
 393       <para>
 394        if a <command>SELECT INTO</command> was executed
 395       </para>
 396      </listitem>
 397     </varlistentry>
 398
 399     <varlistentry>
 400      <term><symbol>SPI_OK_DELETE</symbol></term>
 401      <listitem>
 402       <para>
 403        if a <command>DELETE</command> was executed
 404       </para>
 405      </listitem>
 406     </varlistentry>
 407
 408     <varlistentry>
 409      <term><symbol>SPI_OK_INSERT</symbol></term>
 410      <listitem>
 411       <para>
 412        if an <command>INSERT</command> was executed
 413       </para>
 414      </listitem>
 415     </varlistentry>
 416
 417     <varlistentry>
 418      <term><symbol>SPI_OK_UPDATE</symbol></term>
 419      <listitem>
 420       <para>
 421        if an <command>UPDATE</command> was executed
 422       </para>
 423      </listitem>
 424     </varlistentry>
 425
 426     <varlistentry>
 427      <term><symbol>SPI_OK_UTILITY</symbol></term>
 428      <listitem>
 429       <para>
 430        if a utility command (e.g., <command>CREATE TABLE</command>)
 431        was executed
 432       </para>
 433      </listitem>
 434     </varlistentry>
 435    </variablelist>
 436   </para>
 437
 438   <para>
 439    On error, one of the following negative values is returned:
 440
 441    <variablelist>
 442     <varlistentry>
 443      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
 444      <listitem>
 445       <para>
 446        if <parameter>command</parameter> is <symbol>NULL</symbol> or
 447        <parameter>count</parameter> is less than 0
 448       </para>
 449      </listitem>
 450     </varlistentry>
 451
 452     <varlistentry>
 453      <term><symbol>SPI_ERROR_COPY</symbol></term>
 454      <listitem>
 455       <para>
 456        if <command>COPY TO stdout</> or <command>COPY FROM stdin</>
 457        was attempted
 458       </para>
 459      </listitem>
 460     </varlistentry>
 461
 462     <varlistentry>
 463      <term><symbol>SPI_ERROR_CURSOR</symbol></term>
 464      <listitem>
 465       <para>
 466        if <command>DECLARE</>, <command>CLOSE</>, or <command>FETCH</>
 467        was attempted
 468       </para>
 469      </listitem>
 470     </varlistentry>
 471
 472     <varlistentry>
 473      <term><symbol>SPI_ERROR_TRANSACTION</symbol></term>
 474      <listitem>
 475       <para>
 476        if <command>BEGIN</>, <command>COMMIT</>, or
 477        <command>ROLLBACK</> was attempted
 478       </para>
 479      </listitem>
 480     </varlistentry>
 481
 482     <varlistentry>
 483      <term><symbol>SPI_ERROR_OPUNKNOWN</symbol></term>
 484      <listitem>
 485       <para>
 486        if the command type is unknown (shouldn't happen)
 487       </para>
 488      </listitem>
 489     </varlistentry>
 490
 491     <varlistentry>
 492      <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
 493      <listitem>
 494       <para>
 495        if called from an unconnected procedure
 496       </para>
 497      </listitem>
 498     </varlistentry>
 499    </variablelist>
 500   </para>
 501  </refsect1>
 502
 503  <refsect1>
 504   <title>Notes</title>
 505
 506   <para>
 507    The functions <function>SPI_exec</function>,
 508    <function>SPI_execp</function>, and
 509    <function>SPI_prepare</function> change both
 510    <varname>SPI_processed</varname> and
 511    <varname>SPI_tuptable</varname> (just the pointer, not the contents
 512    of the structure).  Save these two global variables into local
 513    procedure variables if you need to access the result of
 514    <function>SPI_exec</function> or <function>SPI_execp</function>
 515    across later calls.
 516   </para>
 517  </refsect1>
 518 </refentry>
 519
 520 <!-- *********************************************** -->
 521
 522 <refentry id="spi-spi-prepare">
 523  <refmeta>
 524   <refentrytitle>SPI_prepare</refentrytitle>
 525  </refmeta>
 526
 527  <refnamediv>
 528   <refname>SPI_prepare</refname>
 529   <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
 530  </refnamediv>
 531
 532  <indexterm><primary>SPI_prepare</primary></indexterm>
 533
 534  <refsynopsisdiv>
 535 <synopsis>
 536 void * SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
 537 </synopsis>
 538  </refsynopsisdiv>
 539
 540  <refsect1>
 541   <title>Description</title>
 542
 543   <para>
 544    <function>SPI_prepare</function> creates and returns an execution
 545    plan for the specified command but doesn't execute the command.
 546    This function should only be called from a connected procedure.
 547   </para>
 548
 549   <para>
 550    When the same or a similar command is to be executed repeatedly, it
 551    may be advantageous to perform the planning only once.
 552    <function>SPI_prepare</function> converts a command string into an
 553    execution plan that can be executed repeatedly using
 554    <function>SPI_execp</function>.
 555   </para>
 556
 557   <para>
 558    A prepared command can be generalized by writing parameters
 559    (<literal>$1</>, <literal>$2</>, etc.) in place of what would be
 560    constants in a normal command.  The actual values of the parameters
 561    are then specified when <function>SPI_execp</function> is called.
 562    This allows the prepared command to be used over a wider range of
 563    situations than would be possible without parameters.
 564   </para>
 565
 566   <para>
 567    The plan returned by <function>SPI_prepare</function> can be used
 568    only in the current invocation of the procedure since
 569    <function>SPI_finish</function> frees memory allocated for a plan.
 570    But a plan can be saved for longer using the function
 571    <function>SPI_saveplan</function>.
 572   </para>
 573  </refsect1>
 574
 575  <refsect1>
 576   <title>Arguments</title>
 577
 578   <variablelist>
 579    <varlistentry>
 580     <term><literal>const char * <parameter>command</parameter></literal></term>
 581     <listitem>
 582      <para>
 583       command string
 584      </para>
 585     </listitem>
 586    </varlistentry>
 587
 588    <varlistentry>
 589     <term><literal>int <parameter>nargs</parameter></literal></term>
 590     <listitem>
 591      <para>
 592       number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
 593      </para>
 594     </listitem>
 595    </varlistentry>
 596
 597    <varlistentry>
 598     <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
 599     <listitem>
 600      <para>
 601       pointer to an array containing the <acronym>OID</acronym>s of
 602       the data types of the parameters
 603      </para>
 604     </listitem>
 605    </varlistentry>
 606   </variablelist>
 607  </refsect1>
 608
 609  <refsect1>
 610   <title>Return Value</title>
 611
 612   <para>
 613    <function>SPI_prepare</function> returns non-null pointer to an
 614    execution plan.  On error, <symbol>NULL</symbol> will be returned.
 615    In both cases, <varname>SPI_result</varname> will be set analogous
 616    to the value returned by <function>SPI_exec</function>, except that
 617    it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if
 618    <parameter>command</parameter> is <symbol>NULL</symbol>, or if
 619    <parameter>nargs</> is less than 0, or if <parameter>nargs</> is
 620    greater than 0 and <parameter>argtypes</> is <symbol>NULL</symbol>.
 621   </para>
 622  </refsect1>
 623
 624  <refsect1>
 625   <title>Notes</title>
 626
 627   <para>
 628    There is a disadvantage to using parameters: since the planner does
 629    not know the values that will be supplied for the parameters, it
 630    may make worse planning choices than it would make for a normal
 631    command with all constants visible.
 632   </para>
 633  </refsect1>
 634 </refentry>
 635
 636 <!-- *********************************************** -->
 637
 638 <refentry id="spi-spi-getargcount">
 639  <refmeta>
 640   <refentrytitle>SPI_getargcount</refentrytitle>
 641  </refmeta>
 642
 643  <refnamediv>
 644   <refname>SPI_getargcount</refname>
 645   <refpurpose>returns the number of arguments needed when executing a plan
 646   prepared by <function>SPI_prepare</function></refpurpose>
 647  </refnamediv>
 648
 649  <indexterm><primary>SPI_getargcount</primary></indexterm>
 650
 651  <refsynopsisdiv>
 652 <synopsis>
 653 int SPI_getargcount(void * <parameter>plan</parameter>)
 654 </synopsis>
 655  </refsynopsisdiv>
 656
 657  <refsect1>
 658   <title>Description</title>
 659
 660   <para>
 661    <function>SPI_getargcount</function> returns the number of arguments needed
 662    when executing a plan prepared by <function>SPI_prepare</function>.
 663   </para>
 664  </refsect1>
 665
 666  <refsect1>
 667   <title>Arguments</title>
 668
 669   <variablelist>
 670    <varlistentry>
 671     <term><literal>void * <parameter>plan</parameter></literal></term>
 672     <listitem>
 673      <para>
 674       execution plan (returned by <function>SPI_prepare</function>)
 675      </para>
 676     </listitem>
 677    </varlistentry>
 678   </variablelist>
 679  </refsect1>
 680
 681  <refsect1>
 682   <title>Return Value</title>
 683   <para>
 684     The expected argument count for the <parameter>plan</parameter> or
 685     <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan
 686     </parameter> is <symbol>NULL</symbol>
 687   </para>
 688  </refsect1>
 689 </refentry>
 690
 691 <!-- *********************************************** -->
 692
 693 <refentry id="spi-spi-getargtypeid">
 694  <refmeta>
 695   <refentrytitle>SPI_getargtypeid</refentrytitle>
 696  </refmeta>
 697
 698  <refnamediv>
 699   <refname>SPI_getargtypeid</refname>
 700   <refpurpose>returns the expected typeid for the specified argument when
 701   executing a plan prepared by <function>SPI_prepare</function></refpurpose>
 702  </refnamediv>
 703
 704  <indexterm><primary>SPI_getargtypeid</primary></indexterm>
 705
 706  <refsynopsisdiv>
 707 <synopsis>
 708 Oid SPI_getargtypeid(void * <parameter>plan</parameter>, int <parameter>argIndex</parameter>)
 709 </synopsis>
 710  </refsynopsisdiv>
 711
 712  <refsect1>
 713   <title>Description</title>
 714
 715   <para>
 716    <function>SPI_getargtypeid</function> returns the Oid representing the type
 717    id for argument at <parameter>argIndex</parameter> in a plan prepared by
 718    <function>SPI_prepare</function>. First argument is at index zero.
 719   </para>
 720  </refsect1>
 721
 722  <refsect1>
 723   <title>Arguments</title>
 724
 725   <variablelist>
 726    <varlistentry>
 727     <term><literal>void * <parameter>plan</parameter></literal></term>
 728     <listitem>
 729      <para>
 730       execution plan (returned by <function>SPI_prepare</function>)
 731      </para>
 732     </listitem>
 733    </varlistentry>
 734
 735    <varlistentry>
 736     <term><literal>int <parameter>argIndex</parameter></literal></term>
 737     <listitem>
 738      <para>
 739       zero based index of the argument
 740      </para>
 741     </listitem>
 742    </varlistentry>
 743   </variablelist>
 744  </refsect1>
 745
 746  <refsect1>
 747   <title>Return Value</title>
 748   <para>
 749     The type id of the argument at the given index or <symbol>
 750     SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan</parameter> is
 751     <symbol>NULL</symbol> or <parameter>argIndex</parameter> is less than 0 or
 752     not less than the number of arguments declared for the <parameter>plan
 753     </parameter>
 754   </para>
 755  </refsect1>
 756 </refentry>
 757
 758 <!-- *********************************************** -->
 759
 760 <refentry id="spi-spi-is-cursor-plan">
 761  <refmeta>
 762   <refentrytitle>SPI_is_cursor_plan</refentrytitle>
 763  </refmeta>
 764
 765  <refnamediv>
 766   <refname>SPI_is_cursor_plan</refname>
 767   <refpurpose>returns <symbol>true</symbol> if a plan
 768   prepared by <function>SPI_prepare</function> can be passed
 769   as an argument to <function>SPI_cursor_open</function></refpurpose>
 770  </refnamediv>
 771
 772  <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>
 773
 774  <refsynopsisdiv>
 775 <synopsis>
 776 bool SPI_is_cursor_plan(void * <parameter>plan</parameter>)
 777 </synopsis>
 778  </refsynopsisdiv>
 779
 780  <refsect1>
 781   <title>Description</title>
 782
 783   <para>
 784    <function>SPI_is_cursor_plan</function> returns <symbol>true</symbol>
 785    if a plan prepared by <function>SPI_prepare</function> can be passed
 786    as an argument to <function>SPI_cursor_open</function> and <symbol>
 787    false</symbol> if that is not the case. The criteria is that the
 788    <parameter>plan</parameter> represents one single command and that this
 789    command is a <command>SELECT</command> without an <command>INTO</command>
 790    clause.
 791   </para>
 792  </refsect1>
 793
 794  <refsect1>
 795   <title>Arguments</title>
 796
 797   <variablelist>
 798    <varlistentry>
 799     <term><literal>void * <parameter>plan</parameter></literal></term>
 800     <listitem>
 801      <para>
 802       execution plan (returned by <function>SPI_prepare</function>)
 803      </para>
 804     </listitem>
 805    </varlistentry>
 806   </variablelist>
 807  </refsect1>
 808
 809  <refsect1>
 810   <title>Return Value</title>
 811   <para>
 812     <symbol>true</symbol> or <symbol>false</symbol> to indicate if the
 813     <parameter>plan</parameter> can produce a cursor or not, or
 814     <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan</parameter>
 815     is <symbol>NULL</symbol>
 816   </para>
 817  </refsect1>
 818 </refentry>
 819
 820 <!-- *********************************************** -->
 821
 822 <refentry id="spi-spi-execp">
 823  <refmeta>
 824   <refentrytitle>SPI_execp</refentrytitle>
 825  </refmeta>
 826
 827  <refnamediv>
 828   <refname>SPI_execp</refname>
 829   <refpurpose>executes a plan prepared by <function>SPI_prepare</function></refpurpose>
 830  </refnamediv>
 831
 832  <indexterm><primary>SPI_execp</primary></indexterm>
 833
 834  <refsynopsisdiv>
 835 <synopsis>
 836 int SPI_execp(void * <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, int <parameter>count</parameter>)
 837 </synopsis>
 838  </refsynopsisdiv>
 839
 840  <refsect1>
 841   <title>Description</title>
 842
 843   <para>
 844    <function>SPI_execp</function> executes a plan prepared by
 845    <function>SPI_prepare</function>.  <parameter>tcount</parameter>
 846    has the same interpretation as in <function>SPI_exec</function>.
 847   </para>
 848  </refsect1>
 849
 850  <refsect1>
 851   <title>Arguments</title>
 852
 853   <variablelist>
 854    <varlistentry>
 855     <term><literal>void * <parameter>plan</parameter></literal></term>
 856     <listitem>
 857      <para>
 858       execution plan (returned by <function>SPI_prepare</function>)
 859      </para>
 860     </listitem>
 861    </varlistentry>
 862
 863    <varlistentry>
 864     <term><literal>Datum *<parameter>values</parameter></literal></term>
 865     <listitem>
 866      <para>
 867       actual parameter values
 868      </para>
 869     </listitem>
 870    </varlistentry>
 871
 872    <varlistentry>
 873     <term><literal>const char * <parameter>nulls</parameter></literal></term>
 874     <listitem>
 875      <para>
 876       An array describing which parameters are null.
 877       <literal>n</literal> indicates a null value (entry in
 878       <parameter>values</> will be ignored); a space indicates a
 879       nonnull value (entry in <parameter>values</> is valid).
 880      </para>
 881
 882      <para>
 883       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
 884       <function>SPI_execp</function> assumes that no parameters are
 885       null.
 886      </para>
 887     </listitem>
 888    </varlistentry>
 889
 890    <varlistentry>
 891     <term><literal>int <parameter>count</parameter></literal></term>
 892     <listitem>
 893      <para>
 894       number of row for which plan is to be executed
 895      </para>
 896     </listitem>
 897    </varlistentry>
 898   </variablelist>
 899  </refsect1>
 900
 901  <refsect1>
 902   <title>Return Value</title>
 903
 904   <para>
 905    The return value is the same as for <function>SPI_exec</function>
 906    or one of the following:
 907
 908    <variablelist>
 909     <varlistentry>
 910      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
 911      <listitem>
 912       <para>
 913        if <parameter>plan</parameter> is <symbol>NULL</symbol> or
 914        <parameter>count</parameter> is less than 0
 915       </para>
 916      </listitem>
 917     </varlistentry>
 918
 919     <varlistentry>
 920      <term><symbol>SPI_ERROR_PARAM</symbol></term>
 921      <listitem>
 922       <para>
 923        if <parameter>values</parameter> is <symbol>NULL</symbol> and
 924        <parameter>plan</parameter> was prepared with some parameters
 925       </para>
 926      </listitem>
 927     </varlistentry>
 928    </variablelist>
 929   </para>
 930
 931   <para>
 932    <varname>SPI_processed</varname> and
 933    <varname>SPI_tuptable</varname> are set as in
 934    <function>SPI_exec</function> if successful.
 935   </para>
 936  </refsect1>
 937
 938  <refsect1>
 939   <title>Notes</title>
 940
 941   <para>
 942    If one of the objects (a table, function, etc.) referenced by the
 943    prepared plan is dropped during the session then the result of
 944    <function>SPI_execp</function> for this plan will be unpredictable.
 945   </para>
 946  </refsect1>
 947 </refentry>
 948
 949 <!-- *********************************************** -->
 950
 951 <refentry id="spi-spi-cursor-open">
 952  <refmeta>
 953   <refentrytitle>SPI_cursor_open</refentrytitle>
 954  </refmeta>
 955
 956  <refnamediv>
 957   <refname>SPI_cursor_open</refname>
 958   <refpurpose>set up a cursor using a plan created with <function>SPI_prepare</function></refpurpose>
 959  </refnamediv>
 960
 961  <indexterm><primary>SPI_cursor_open</primary></indexterm>
 962
 963  <refsynopsisdiv>
 964 <synopsis>
 965 Portal SPI_cursor_open(const char * <parameter>name</parameter>, void * <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>)
 966 </synopsis>
 967  </refsynopsisdiv>
 968
 969  <refsect1>
 970   <title>Description</title>
 971
 972   <para>
 973    <function>SPI_cursor_open</function> sets up a cursor (internally,
 974    a portal) that will execute a plan prepared by
 975    <function>SPI_prepare</function>.
 976   </para>
 977
 978   <para>
 979    Using a cursor instead of executing the plan directly has two
 980    benefits.  First, the result rows can be retrieved a few at a time,
 981    avoiding memory overrun for queries that return many rows.  Second,
 982    a portal can outlive the current procedure (it can, in fact, live
 983    to the end of the current transaction).  Returning the portal name
 984    to the procedure's caller provides a way of returning a row set as
 985    result.
 986   </para>
 987  </refsect1>
 988
 989  <refsect1>
 990   <title>Arguments</title>
 991
 992   <variablelist>
 993    <varlistentry>
 994     <term><literal>const char * <parameter>name</parameter></literal></term>
 995     <listitem>
 996      <para>
 997       name for portal, or <symbol>NULL</symbol> to let the system
 998       select a name
 999      </para>
1000     </listitem>
1001    </varlistentry>
1002
1003    <varlistentry>
1004     <term><literal>void * <parameter>plan</parameter></literal></term>
1005     <listitem>
1006      <para>
1007       execution plan (returned by <function>SPI_prepare</function>)
1008      </para>
1009     </listitem>
1010    </varlistentry>
1011
1012    <varlistentry>
1013     <term><literal>Datum * <parameter>values</parameter></literal></term>
1014     <listitem>
1015      <para>
1016       actual parameter values
1017      </para>
1018     </listitem>
1019    </varlistentry>
1020
1021    <varlistentry>
1022     <term><literal>const char *<parameter>nulls</parameter></literal></term>
1023     <listitem>
1024      <para>
1025       An array describing which parameters are null values.
1026       <literal>n</literal> indicates a null value (entry in
1027       <parameter>values</> will be ignored); a space indicates a
1028       nonnull value (entry in <parameter>values</> is valid).  If
1029       <parameter>nulls</parameter> is <symbol>NULL</> then
1030       <function>SPI_cursor_open</function> assumes that no parameters
1031       are null.
1032      </para>
1033     </listitem>
1034    </varlistentry>
1035   </variablelist>
1036  </refsect1>
1037
1038  <refsect1>
1039   <title>Return Value</title>
1040
1041   <para>
1042    pointer to portal containing the cursor, or <symbol>NULL</symbol>
1043    on error
1044   </para>
1045  </refsect1>
1046 </refentry>
1047
1048 <!-- *********************************************** -->
1049
1050 <refentry id="spi-spi-cursor-find">
1051  <refmeta>
1052   <refentrytitle>SPI_cursor_find</refentrytitle>
1053  </refmeta>
1054
1055  <refnamediv>
1056   <refname>SPI_cursor_find</refname>
1057   <refpurpose>find an existing cursor by name</refpurpose>
1058  </refnamediv>
1059
1060  <indexterm><primary>SPI_cursor_find</primary></indexterm>
1061
1062  <refsynopsisdiv>
1063 <synopsis>
1064 Portal SPI_cursor_find(const char * <parameter>name</parameter>)
1065 </synopsis>
1066  </refsynopsisdiv>
1067
1068  <refsect1>
1069   <title>Description</title>
1070
1071   <para>
1072    <function>SPI_cursor_find</function> finds an existing portal by
1073    name.  This is primarily useful to resolve a cursor name returned
1074    as text by some other function.
1075   </para>
1076  </refsect1>
1077
1078  <refsect1>
1079   <title>Arguments</title>
1080
1081   <variablelist>
1082    <varlistentry>
1083     <term><literal>const char * <parameter>name</parameter></literal></term>
1084     <listitem>
1085      <para>
1086       name of the portal
1087      </para>
1088     </listitem>
1089    </varlistentry>
1090   </variablelist>
1091  </refsect1>
1092
1093  <refsect1>
1094   <title>Return Value</title>
1095
1096   <para>
1097    pointer to the portal with the specified name, or
1098    <symbol>NULL</symbol> if none was found
1099   </para>
1100  </refsect1>
1101 </refentry>
1102
1103 <!-- *********************************************** -->
1104
1105 <refentry id="spi-spi-cursor-fetch">
1106  <refmeta>
1107   <refentrytitle>SPI_cursor_fetch</refentrytitle>
1108  </refmeta>
1109
1110  <refnamediv>
1111   <refname>SPI_cursor_fetch</refname>
1112   <refpurpose>fetch some rows from a cursor</refpurpose>
1113  </refnamediv>
1114
1115  <indexterm><primary>SPI_cursor_fetch</primary></indexterm>
1116
1117  <refsynopsisdiv>
1118 <synopsis>
1119 void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, int <parameter>count</parameter>)
1120 </synopsis>
1121  </refsynopsisdiv>
1122
1123  <refsect1>
1124   <title>Description</title>
1125
1126   <para>
1127    <function>SPI_cursor_fetch</function> fetches some rows from a
1128    cursor.  This is equivalent to the SQL command <command>FETCH</>.
1129   </para>
1130  </refsect1>
1131
1132  <refsect1>
1133   <title>Arguments</title>
1134
1135   <variablelist>
1136    <varlistentry>
1137     <term><literal>Portal <parameter>portal</parameter></literal></term>
1138     <listitem>
1139      <para>
1140       portal containing the cursor
1141      </para>
1142     </listitem>
1143    </varlistentry>
1144
1145    <varlistentry>
1146     <term><literal>bool <parameter>forward</parameter></literal></term>
1147     <listitem>
1148      <para>
1149       true for fetch forward, false for fetch backward
1150      </para>
1151     </listitem>
1152    </varlistentry>
1153
1154    <varlistentry>
1155     <term><literal>int <parameter>count</parameter></literal></term>
1156     <listitem>
1157      <para>
1158       maximum number of rows to fetch
1159      </para>
1160     </listitem>
1161    </varlistentry>
1162   </variablelist>
1163  </refsect1>
1164
1165  <refsect1>
1166   <title>Return Value</title>
1167
1168   <para>
1169    <varname>SPI_processed</varname> and
1170    <varname>SPI_tuptable</varname> are set as in
1171    <function>SPI_exec</function> if successful.
1172   </para>
1173  </refsect1>
1174 </refentry>
1175
1176 <!-- *********************************************** -->
1177
1178 <refentry id="spi-spi-cursor-move">
1179  <refmeta>
1180   <refentrytitle>SPI_cursor_move</refentrytitle>
1181  </refmeta>
1182
1183  <refnamediv>
1184   <refname>SPI_cursor_move</refname>
1185   <refpurpose>move a cursor</refpurpose>
1186  </refnamediv>
1187
1188  <indexterm><primary>SPI_cursor_move</primary></indexterm>
1189
1190  <refsynopsisdiv>
1191 <synopsis>
1192 void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, int <parameter>count</parameter>)
1193 </synopsis>
1194  </refsynopsisdiv>
1195
1196  <refsect1>
1197   <title>Description</title>
1198
1199   <para>
1200    <function>SPI_cursor_move</function> skips over some number of rows
1201    in a cursor.  This is equivalent to the SQL command
1202    <command>MOVE</>.
1203   </para>
1204  </refsect1>
1205
1206  <refsect1>
1207   <title>Arguments</title>
1208
1209   <variablelist>
1210    <varlistentry>
1211     <term><literal>Portal <parameter>portal</parameter></literal></term>
1212     <listitem>
1213      <para>
1214       portal containing the cursor
1215      </para>
1216     </listitem>
1217    </varlistentry>
1218
1219    <varlistentry>
1220     <term><literal>bool <parameter>forward</parameter></literal></term>
1221     <listitem>
1222      <para>
1223       true for move forward, false for move backward
1224      </para>
1225     </listitem>
1226    </varlistentry>
1227
1228    <varlistentry>
1229     <term><literal>int <parameter>count</parameter></literal></term>
1230     <listitem>
1231      <para>
1232       maximum number of rows to move
1233      </para>
1234     </listitem>
1235    </varlistentry>
1236   </variablelist>
1237  </refsect1>
1238 </refentry>
1239
1240 <!-- *********************************************** -->
1241
1242 <refentry id="spi-spi-cursor-close">
1243  <refmeta>
1244   <refentrytitle>SPI_cursor_close</refentrytitle>
1245  </refmeta>
1246
1247  <refnamediv>
1248   <refname>SPI_cursor_close</refname>
1249   <refpurpose>close a cursor</refpurpose>
1250  </refnamediv>
1251
1252  <indexterm><primary>SPI_cursor_close</primary></indexterm>
1253
1254  <refsynopsisdiv>
1255 <synopsis>
1256 void SPI_cursor_close(Portal <parameter>portal</parameter>)
1257 </synopsis>
1258  </refsynopsisdiv>
1259
1260  <refsect1>
1261   <title>Description</title>
1262
1263   <para>
1264    <function>SPI_cursor_close</function> closes a previously created
1265    cursor and releases its portal storage.
1266   </para>
1267
1268   <para>
1269    All open cursors are closed automatically at the end of a
1270    transaction.  <function>SPI_cursor_close</function> need only be
1271    invoked if it is desirable to release resources sooner.
1272   </para>
1273  </refsect1>
1274
1275  <refsect1>
1276   <title>Arguments</title>
1277
1278   <variablelist>
1279    <varlistentry>
1280     <term><literal>Portal <parameter>portal</parameter></literal></term>
1281     <listitem>
1282      <para>
1283       portal containing the cursor
1284      </para>
1285     </listitem>
1286    </varlistentry>
1287   </variablelist>
1288  </refsect1>
1289 </refentry>
1290
1291 <!-- *********************************************** -->
1292
1293 <refentry id="spi-spi-saveplan">
1294  <refmeta>
1295   <refentrytitle>SPI_saveplan</refentrytitle>
1296  </refmeta>
1297
1298  <refnamediv>
1299   <refname>SPI_saveplan</refname>
1300   <refpurpose>save a plan</refpurpose>
1301  </refnamediv>
1302
1303  <indexterm><primary>SPI_saveplan</primary></indexterm>
1304
1305  <refsynopsisdiv>
1306 <synopsis>
1307 void * SPI_saveplan(void * <parameter>plan</parameter>)
1308 </synopsis>
1309  </refsynopsisdiv>
1310
1311  <refsect1>
1312   <title>Description</title>
1313
1314   <para>
1315    <function>SPI_saveplan</function> saves a passed plan (prepared by
1316    <function>SPI_prepare</function>) in memory protected from freeing
1317    by <function>SPI_finish</function> and by the transaction manager
1318    and returns a pointer to the saved plan.  This gives you the
1319    ability to reuse prepared plans in the subsequent invocations of
1320    your procedure in the current session.  You may save the pointer
1321    returned in a local variable.  Always check if this pointer is
1322    <symbol>NULL</symbol> or not either when preparing a plan or using
1323    an already prepared plan in <function>SPI_execp</function>.
1324   </para>
1325  </refsect1>
1326
1327  <refsect1>
1328   <title>Arguments</title>
1329
1330   <variablelist>
1331    <varlistentry>
1332     <term><literal>void * <parameter>plan</parameter></literal></term>
1333     <listitem>
1334      <para>
1335       the plan to be saved
1336      </para>
1337     </listitem>
1338    </varlistentry>
1339   </variablelist>
1340  </refsect1>
1341
1342  <refsect1>
1343   <title>Return Value</title>
1344
1345   <para>
1346    Pointer to the saved plan; <symbol>NULL</symbol> if unsuccessful.
1347    On error, <varname>SPI_result</varname> is set thus:
1348
1349    <variablelist>
1350     <varlistentry>
1351      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
1352      <listitem>
1353       <para>
1354        if <parameter>plan</parameter> is <symbol>NULL</symbol>
1355       </para>
1356      </listitem>
1357     </varlistentry>
1358
1359     <varlistentry>
1360      <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
1361      <listitem>
1362       <para>
1363        if called from an unconnected procedure
1364       </para>
1365      </listitem>
1366     </varlistentry>
1367    </variablelist>
1368   </para>
1369  </refsect1>
1370
1371  <refsect1>
1372   <title>Notes</title>
1373
1374   <para>
1375    If one of the objects (a table, function, etc.) referenced by the
1376    prepared plan is dropped during the session then the results of
1377    <function>SPI_execp</function> for this plan will be unpredictable.
1378   </para>
1379  </refsect1>
1380 </refentry>
1381
1382 </sect1>
1383
1384 <sect1 id="spi-interface-support">
1385  <title>Interface Support Functions</title>
1386
1387  <para>
1388   The functions described here provide an interface for extracting
1389   information from result sets returned by <function>SPI_exec</> and
1390   other SPI functions.
1391  </para>
1392
1393  <para>
1394   All functions described in this section may be used by both
1395   connected and unconnected procedures.
1396  </para>
1397
1398 <!-- *********************************************** -->
1399
1400 <refentry id="spi-spi-fname">
1401  <refmeta>
1402   <refentrytitle>SPI_fname</refentrytitle>
1403  </refmeta>
1404
1405  <refnamediv>
1406   <refname>SPI_fname</refname>
1407   <refpurpose>determine the column name for the specified column number</refpurpose>
1408  </refnamediv>
1409
1410  <indexterm><primary>SPI_fname</primary></indexterm>
1411
1412  <refsynopsisdiv>
1413 <synopsis>
1414 char * SPI_fname(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
1415 </synopsis>
1416  </refsynopsisdiv>
1417
1418  <refsect1>
1419   <title>Description</title>
1420
1421   <para>
1422    <function>SPI_fname</function> returns the column name of the
1423    specified column.  (You can use <function>pfree</function> to
1424    release the copy of the name when you don't need it anymore.)
1425   </para>
1426  </refsect1>
1427
1428  <refsect1>
1429   <title>Arguments</title>
1430
1431   <variablelist>
1432    <varlistentry>
1433     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1434     <listitem>
1435      <para>
1436       input row description
1437      </para>
1438     </listitem>
1439    </varlistentry>
1440
1441    <varlistentry>
1442     <term><literal>int <parameter>colnumber</parameter></literal></term>
1443     <listitem>
1444      <para>
1445       column number (count starts at 1)
1446      </para>
1447     </listitem>
1448    </varlistentry>
1449   </variablelist>
1450  </refsect1>
1451
1452  <refsect1>
1453   <title>Return Value</title>
1454
1455   <para>
1456    The column name; <symbol>NULL</symbol> if
1457    <parameter>colnumber</parameter> is out of range.
1458    <varname>SPI_result</varname> set to
1459    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
1460   </para>
1461  </refsect1>
1462 </refentry>
1463
1464 <!-- *********************************************** -->
1465
1466 <refentry id="spi-spi-fnumber">
1467  <refmeta>
1468   <refentrytitle>SPI_fnumber</refentrytitle>
1469  </refmeta>
1470
1471  <refnamediv>
1472   <refname>SPI_fnumber</refname>
1473   <refpurpose>determine the column number for the specified column name</refpurpose>
1474  </refnamediv>
1475
1476  <indexterm><primary>SPI_fnumber</primary></indexterm>
1477
1478  <refsynopsisdiv>
1479 <synopsis>
1480 int SPI_fnumber(TupleDesc <parameter>rowdesc</parameter>, const char * <parameter>colname</parameter>)
1481 </synopsis>
1482  </refsynopsisdiv>
1483
1484  <refsect1>
1485   <title>Description</title>
1486
1487   <para>
1488    <function>SPI_fnumber</function> returns the column number for the
1489    column with the specified name.
1490   </para>
1491
1492   <para>
1493    If <parameter>colname</parameter> refers to a system column (e.g.,
1494    <literal>oid</>) then the appropriate negative column number will
1495    be returned.  The caller should be careful to test the return value
1496    for exact equality to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> to
1497    detect an error; testing the result for less than or equal to 0 is
1498    not correct unless system columns should be rejected.
1499   </para>
1500  </refsect1>
1501
1502  <refsect1>
1503   <title>Arguments</title>
1504
1505   <variablelist>
1506    <varlistentry>
1507     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1508     <listitem>
1509      <para>
1510       input row description
1511      </para>
1512     </listitem>
1513    </varlistentry>
1514
1515    <varlistentry>
1516     <term><literal>const char * <parameter>colname</parameter></literal></term>
1517     <listitem>
1518      <para>
1519       column name
1520      </para>
1521     </listitem>
1522    </varlistentry>
1523   </variablelist>
1524  </refsect1>
1525
1526  <refsect1>
1527   <title>Return Value</title>
1528
1529   <para>
1530    Column number (count starts at 1), or
1531    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> if the named column was not
1532    found.
1533   </para>
1534  </refsect1>
1535 </refentry>
1536
1537 <!-- *********************************************** -->
1538
1539 <refentry id="spi-spi-getvalue">
1540  <refmeta>
1541   <refentrytitle>SPI_getvalue</refentrytitle>
1542  </refmeta>
1543
1544  <refnamediv>
1545   <refname>SPI_getvalue</refname>
1546   <refpurpose>return the string value of the specified column</refpurpose>
1547  </refnamediv>
1548
1549  <indexterm><primary>SPI_getvalue</primary></indexterm>
1550
1551  <refsynopsisdiv>
1552 <synopsis>
1553 char * SPI_getvalue(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
1554 </synopsis>
1555  </refsynopsisdiv>
1556
1557  <refsect1>
1558   <title>Description</title>
1559
1560   <para>
1561    <function>SPI_getvalue</function> returns the string representation
1562    of the value of the specified column.
1563   </para>
1564
1565   <para>
1566    The result is returned in memory allocated using
1567    <function>palloc</function>.  (You can use
1568    <function>pfree</function> to release the memory when you don't
1569    need it anymore.)
1570   </para>
1571  </refsect1>
1572
1573  <refsect1>
1574   <title>Arguments</title>
1575
1576   <variablelist>
1577    <varlistentry>
1578     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
1579     <listitem>
1580      <para>
1581       input row to be examined
1582      </para>
1583     </listitem>
1584    </varlistentry>
1585
1586    <varlistentry>
1587     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1588     <listitem>
1589      <para>
1590       input row description
1591      </para>
1592     </listitem>
1593    </varlistentry>
1594
1595    <varlistentry>
1596     <term><literal>int <parameter>colnumber</parameter></literal></term>
1597     <listitem>
1598      <para>
1599       column number (count starts at 1)
1600      </para>
1601     </listitem>
1602    </varlistentry>
1603   </variablelist>
1604  </refsect1>
1605
1606  <refsect1>
1607   <title>Return Value</title>
1608
1609   <para>
1610    Column value, or <symbol>NULL</symbol> if the column is null,
1611    <parameter>colnumber</parameter> is out of range
1612    (<varname>SPI_result</varname> is set to
1613    <symbol>SPI_ERROR_NOATTRIBUTE</symbol>), or no no output function
1614    available (<varname>SPI_result</varname> is set to
1615    <symbol>SPI_ERROR_NOOUTFUNC</symbol>).
1616   </para>
1617  </refsect1>
1618 </refentry>
1619
1620 <!-- *********************************************** -->
1621
1622 <refentry id="spi-spi-getbinval">
1623  <refmeta>
1624   <refentrytitle>SPI_getbinval</refentrytitle>
1625  </refmeta>
1626
1627  <refnamediv>
1628   <refname>SPI_getbinval</refname>
1629   <refpurpose>return the binary value of the specified column</refpurpose>
1630  </refnamediv>
1631
1632  <indexterm><primary>SPI_getbinval</primary></indexterm>
1633
1634  <refsynopsisdiv>
1635 <synopsis>
1636 Datum SPI_getbinval(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>, bool * <parameter>isnull</parameter>)
1637 </synopsis>
1638  </refsynopsisdiv>
1639
1640  <refsect1>
1641   <title>Description</title>
1642
1643   <para>
1644    <function>SPI_getbinval</function> returns the value of the
1645    specified column in the internal form (as type <type>Datum</type>).
1646   </para>
1647
1648   <para>
1649    This function does not allocate new space for the datum.  In the
1650    case of a pass-by-reference data type, the return value will be a
1651    pointer into the passed row.
1652   </para>
1653  </refsect1>
1654
1655  <refsect1>
1656   <title>Arguments</title>
1657
1658   <variablelist>
1659    <varlistentry>
1660     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
1661     <listitem>
1662      <para>
1663       input row to be examined
1664      </para>
1665     </listitem>
1666    </varlistentry>
1667
1668    <varlistentry>
1669     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1670     <listitem>
1671      <para>
1672       input row description
1673      </para>
1674     </listitem>
1675    </varlistentry>
1676
1677    <varlistentry>
1678     <term><literal>int <parameter>rownumber</parameter></literal></term>
1679     <listitem>
1680      <para>
1681       column number (count starts at 1)
1682      </para>
1683     </listitem>
1684    </varlistentry>
1685
1686    <varlistentry>
1687     <term><literal>bool * <parameter>isnull</parameter></literal></term>
1688     <listitem>
1689      <para>
1690       flag for a null value in the column
1691      </para>
1692     </listitem>
1693    </varlistentry>
1694   </variablelist>
1695  </refsect1>
1696
1697  <refsect1>
1698   <title>Return Value</title>
1699
1700   <para>
1701    The binary value of the column is returned.  The variable pointed
1702    to by <parameter>isnull</parameter> is set to true if the column is
1703    null, else to false.
1704   </para>
1705
1706   <para>
1707    <varname>SPI_result</varname> is set to
1708    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
1709   </para>
1710  </refsect1>
1711 </refentry>
1712
1713 <!-- *********************************************** -->
1714
1715 <refentry id="spi-spi-gettype">
1716  <refmeta>
1717   <refentrytitle>SPI_gettype</refentrytitle>
1718  </refmeta>
1719
1720  <refnamediv>
1721   <refname>SPI_gettype</refname>
1722   <refpurpose>return the data type name of the specified column</refpurpose>
1723  </refnamediv>
1724
1725  <indexterm><primary>SPI_gettype</primary></indexterm>
1726
1727  <refsynopsisdiv>
1728 <synopsis>
1729 char * SPI_gettype(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
1730 </synopsis>
1731  </refsynopsisdiv>
1732
1733  <refsect1>
1734   <title>Description</title>
1735
1736   <para>
1737    <function>SPI_gettype</function> returns the data type name of the
1738    specified column.  (You can use <function>pfree</function> to
1739    release the copy of the name when you don't need it anymore.)
1740   </para>
1741  </refsect1>
1742
1743  <refsect1>
1744   <title>Arguments</title>
1745
1746   <variablelist>
1747    <varlistentry>
1748     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1749     <listitem>
1750      <para>
1751       input row description
1752      </para>
1753     </listitem>
1754    </varlistentry>
1755
1756    <varlistentry>
1757     <term><literal>int <parameter>colnumber</parameter></literal></term>
1758     <listitem>
1759      <para>
1760       column number (count starts at 1)
1761      </para>
1762     </listitem>
1763    </varlistentry>
1764   </variablelist>
1765  </refsect1>
1766
1767  <refsect1>
1768   <title>Return Value</title>
1769
1770   <para>
1771    The data type name of the specified column, or
1772    <symbol>NULL</symbol> on error.  <varname>SPI_result</varname> is
1773    set to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
1774   </para>
1775  </refsect1>
1776 </refentry>
1777
1778 <!-- *********************************************** -->
1779
1780 <refentry id="spi-spi-gettypeid">
1781  <refmeta>
1782   <refentrytitle>SPI_gettypeid</refentrytitle>
1783  </refmeta>
1784
1785  <refnamediv>
1786   <refname>SPI_gettypeid</refname>
1787   <refpurpose>return the data type <acronym>OID</acronym> of the specified column</refpurpose>
1788  </refnamediv>
1789
1790  <indexterm><primary>SPI_gettypeid</primary></indexterm>
1791
1792  <refsynopsisdiv>
1793 <synopsis>
1794 Oid SPI_gettypeid(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
1795 </synopsis>
1796  </refsynopsisdiv>
1797
1798  <refsect1>
1799   <title>Description</title>
1800
1801   <para>
1802    <function>SPI_gettypeid</function> returns the
1803    <acronym>OID</acronym> of the data type of the specified column.
1804   </para>
1805  </refsect1>
1806
1807  <refsect1>
1808   <title>Arguments</title>
1809
1810   <variablelist>
1811    <varlistentry>
1812     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1813     <listitem>
1814      <para>
1815       input row description
1816      </para>
1817     </listitem>
1818    </varlistentry>
1819
1820    <varlistentry>
1821     <term><literal>int <parameter>colnumber</parameter></literal></term>
1822     <listitem>
1823      <para>
1824       column number (count starts at 1)
1825      </para>
1826     </listitem>
1827    </varlistentry>
1828   </variablelist>
1829  </refsect1>
1830
1831  <refsect1>
1832   <title>Return Value</title>
1833
1834   <para>
1835    The <acronym>OID</acronym> of the data type of the specified column
1836    or <symbol>InvalidOid</symbol> on error.  On error,
1837    <varname>SPI_result</varname> is set to
1838    <symbol>SPI_ERROR_NOATTRIBUTE</symbol>.
1839   </para>
1840  </refsect1>
1841 </refentry>
1842
1843 <!-- *********************************************** -->
1844
1845 <refentry id="spi-spi-getrelname">
1846  <refmeta>
1847   <refentrytitle>SPI_getrelname</refentrytitle>
1848  </refmeta>
1849
1850  <refnamediv>
1851   <refname>SPI_getrelname</refname>
1852   <refpurpose>return the name of the specified relation</refpurpose>
1853  </refnamediv>
1854
1855  <indexterm><primary>SPI_getrelname</primary></indexterm>
1856
1857  <refsynopsisdiv>
1858 <synopsis>
1859 char * SPI_getrelname(Relation <parameter>rel</parameter>)
1860 </synopsis>
1861  </refsynopsisdiv>
1862
1863  <refsect1>
1864   <title>Description</title>
1865
1866   <para>
1867    <function>SPI_getrelname</function> returns the name of the
1868    specified relation.  (You can use <function>pfree</function> to
1869    release the copy of the name when you don't need it anymore.)
1870   </para>
1871  </refsect1>
1872
1873  <refsect1>
1874   <title>Arguments</title>
1875
1876   <variablelist>
1877    <varlistentry>
1878     <term><literal>Relation <parameter>rel</parameter></literal></term>
1879     <listitem>
1880      <para>
1881       input relation
1882      </para>
1883     </listitem>
1884    </varlistentry>
1885   </variablelist>
1886  </refsect1>
1887
1888  <refsect1>
1889   <title>Return Value</title>
1890
1891   <para>
1892    The name of the specified relation.
1893   </para>
1894  </refsect1>
1895 </refentry>
1896
1897  </sect1>
1898
1899  <sect1 id="spi-memory">
1900   <title>Memory Management</title>
1901
1902   <para>
1903    <productname>PostgreSQL</productname> allocates memory within
1904    <firstterm>memory contexts</firstterm><indexterm><primary>memory
1905    context</primary><secondary>in SPI</secondary></indexterm>, which provide a convenient method of
1906    managing allocations made in many different places that need to
1907    live for differing amounts of time.  Destroying a context releases
1908    all the memory that was allocated in it.  Thus, it is not necessary
1909    to keep track of individual objects to avoid memory leaks; instead
1910    only a relatively small number of contexts have to be managed.
1911    <function>palloc</function> and related functions allocate memory
1912    from the <quote>current</> context.
1913   </para>
1914
1915   <para>
1916    <function>SPI_connect</function> creates a new memory context and
1917    makes it current.  <function>SPI_finish</function> restores the
1918    previous current memory context and destroys the context created by
1919    <function>SPI_connect</function>.  These actions ensure that
1920    transient memory allocations made inside your procedure are
1921    reclaimed at procedure exit, avoiding memory leakage.
1922   </para>
1923
1924   <para>
1925    However, if your procedure needs to return an object in allocated
1926    memory (such as a value of a pass-by-reference data type), you
1927    cannot allocate that memory using <function>palloc</function>, at
1928    least not while you are connected to SPI.  If you try, the object
1929    will be deallocated by <function>SPI_finish</function>, and your
1930    procedure will not work reliably.  To solve this problem, use
1931    <function>SPI_palloc</function> to allocate memory for your return
1932    object.  <function>SPI_palloc</function> allocates memory in the
1933    <quote>upper executor context</quote>, that is, the memory context
1934    that was current when <function>SPI_connect</function> was called,
1935    which is precisely the right context for return a value from your
1936    procedure.
1937   </para>
1938
1939   <para>
1940    If <function>SPI_palloc</function> is called while the procedure is
1941    not connected to SPI, then it acts the same as a normal
1942    <function>palloc</function>.  Before a procedure connects to the
1943    SPI manager, the current memory context is the upper executor
1944    context, so all allocations made by the procedure via
1945    <function>palloc</function> or by SPI utility functions are made in
1946    this context.
1947   </para>
1948
1949   <para>
1950    When <function>SPI_connect</function> is called, the private
1951    context of the procedure, which is created by
1952    <function>SPI_connect</function>, is made the current context.  All
1953    allocations made by <function>palloc</function>,
1954    <function>repalloc</function>, or SPI utility functions (except for
1955    <function>SPI_copytuple</function>,
1956    <function>SPI_copytupledesc</function>,
1957    <function>SPI_copytupleintoslot</function>,
1958    <function>SPI_modifytuple</function>, and
1959    <function>SPI_palloc</function>) are made in this context.  When a
1960    procedure disconnects from the SPI manager (via
1961    <function>SPI_finish</function>) the current context is restored to
1962    the upper executor context, and all allocations made in the
1963    procedure memory context are freed and cannot be used any more.
1964   </para>
1965
1966   <para>
1967    All functions described in this section may be used by both
1968    connected and unconnected procedures.  In an unconnected procedure,
1969    they act the same as the underlying ordinary server functions
1970    (<function>palloc</>, etc.).
1971   </para>
1972
1973 <!-- *********************************************** -->
1974
1975 <refentry id="spi-spi-palloc">
1976  <refmeta>
1977   <refentrytitle>SPI_palloc</refentrytitle>
1978  </refmeta>
1979
1980  <refnamediv>
1981   <refname>SPI_palloc</refname>
1982   <refpurpose>allocate memory in the upper executor context</refpurpose>
1983  </refnamediv>
1984
1985  <indexterm><primary>SPI_palloc</primary></indexterm>
1986
1987  <refsynopsisdiv>
1988 <synopsis>
1989 void * SPI_palloc(Size <parameter>size</parameter>)
1990 </synopsis>
1991  </refsynopsisdiv>
1992
1993  <refsect1>
1994   <title>Description</title>
1995
1996   <para>
1997    <function>SPI_palloc</function> allocates memory in the upper
1998    executor context.
1999   </para>
2000  </refsect1>
2001
2002  <refsect1>
2003   <title>Arguments</title>
2004
2005   <variablelist>
2006    <varlistentry>
2007     <term><literal>Size <parameter>size</parameter></literal></term>
2008     <listitem>
2009      <para>
2010       size in bytes of storage to allocate
2011      </para>
2012     </listitem>
2013    </varlistentry>
2014   </variablelist>
2015  </refsect1>
2016
2017  <refsect1>
2018   <title>Return Value</title>
2019
2020   <para>
2021    pointer to new storage space of the specified size
2022   </para>
2023  </refsect1>
2024 </refentry>
2025
2026 <!-- *********************************************** -->
2027
2028 <refentry id="spi-realloc">
2029  <refmeta>
2030   <refentrytitle>SPI_repalloc</refentrytitle>
2031  </refmeta>
2032
2033  <refnamediv>
2034   <refname>SPI_repalloc</refname>
2035   <refpurpose>reallocate memory in the upper executor context</refpurpose>
2036  </refnamediv>
2037
2038  <indexterm><primary>SPI_repalloc</primary></indexterm>
2039
2040  <refsynopsisdiv>
2041 <synopsis>
2042 void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)
2043 </synopsis>
2044  </refsynopsisdiv>
2045
2046  <refsect1>
2047   <title>Description</title>
2048
2049   <para>
2050    <function>SPI_repalloc</function> changes the size of a memory
2051    segment previously allocated using <function>SPI_palloc</function>.
2052   </para>
2053
2054   <para>
2055    This function is no longer different from plain
2056    <function>repalloc</function>.  It's kept just for backward
2057    compatibility of existing code.
2058   </para>
2059  </refsect1>
2060
2061  <refsect1>
2062   <title>Arguments</title>
2063
2064   <variablelist>
2065    <varlistentry>
2066     <term><literal>void * <parameter>pointer</parameter></literal></term>
2067     <listitem>
2068      <para>
2069       pointer to existing storage to change
2070      </para>
2071     </listitem>
2072    </varlistentry>
2073
2074    <varlistentry>
2075     <term><literal>Size <parameter>size</parameter></literal></term>
2076     <listitem>
2077      <para>
2078       size in bytes of storage to allocate
2079      </para>
2080     </listitem>
2081    </varlistentry>
2082   </variablelist>
2083  </refsect1>
2084
2085  <refsect1>
2086   <title>Return Value</title>
2087
2088   <para>
2089    pointer to new storage space of specified size with the contents
2090    copied from the existing area
2091   </para>
2092  </refsect1>
2093 </refentry>
2094
2095 <!-- *********************************************** -->
2096
2097 <refentry id="spi-spi-pfree">
2098  <refmeta>
2099   <refentrytitle>SPI_pfree</refentrytitle>
2100  </refmeta>
2101
2102  <refnamediv>
2103   <refname>SPI_pfree</refname>
2104   <refpurpose>free memory in the upper executor context</refpurpose>
2105  </refnamediv>
2106
2107  <indexterm><primary>SPI_pfree</primary></indexterm>
2108
2109  <refsynopsisdiv>
2110 <synopsis>
2111 void SPI_pfree(void * <parameter>pointer</parameter>)
2112 </synopsis>
2113  </refsynopsisdiv>
2114
2115  <refsect1>
2116   <title>Description</title>
2117
2118   <para>
2119    <function>SPI_pfree</function> frees memory previously allocated
2120    using <function>SPI_palloc</function> or
2121    <function>SPI_repalloc</function>.
2122   </para>
2123
2124   <para>
2125    This function is no longer different from plain
2126    <function>pfree</function>.  It's kept just for backward
2127    compatibility of existing code.
2128   </para>
2129  </refsect1>
2130
2131  <refsect1>
2132   <title>Arguments</title>
2133
2134   <variablelist>
2135    <varlistentry>
2136     <term><literal>void * <parameter>pointer</parameter></literal></term>
2137     <listitem>
2138      <para>
2139       pointer to existing storage to free
2140      </para>
2141     </listitem>
2142    </varlistentry>
2143   </variablelist>
2144  </refsect1>
2145 </refentry>
2146
2147 <!-- *********************************************** -->
2148
2149 <refentry id="spi-spi-copytuple">
2150  <refmeta>
2151   <refentrytitle>SPI_copytuple</refentrytitle>
2152  </refmeta>
2153
2154  <refnamediv>
2155   <refname>SPI_copytuple</refname>
2156   <refpurpose>make a copy of a row in the upper executor context</refpurpose>
2157  </refnamediv>
2158
2159  <indexterm><primary>SPI_copytuple</primary></indexterm>
2160
2161  <refsynopsisdiv>
2162 <synopsis>
2163 HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>)
2164 </synopsis>
2165  </refsynopsisdiv>
2166
2167  <refsect1>
2168   <title>Description</title>
2169
2170   <para>
2171    <function>SPI_copytuple</function> makes a copy of a row in the
2172    upper executor context.
2173   </para>
2174  </refsect1>
2175
2176  <refsect1>
2177   <title>Arguments</title>
2178
2179   <variablelist>
2180    <varlistentry>
2181     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2182     <listitem>
2183      <para>
2184       row to be copied
2185      </para>
2186     </listitem>
2187    </varlistentry>
2188   </variablelist>
2189  </refsect1>
2190
2191  <refsect1>
2192   <title>Return Value</title>
2193
2194   <para>
2195    the copied row; <symbol>NULL</symbol> only if
2196    <parameter>tuple</parameter> is <symbol>NULL</symbol>
2197   </para>
2198  </refsect1>
2199 </refentry>
2200
2201 <!-- *********************************************** -->
2202
2203 <refentry id="spi-spi-copytupledesc">
2204  <refmeta>
2205   <refentrytitle>SPI_copytupledesc</refentrytitle>
2206  </refmeta>
2207
2208  <refnamediv>
2209   <refname>SPI_copytupledesc</refname>
2210   <refpurpose>make a copy of a row descriptor in the upper executor context</refpurpose>
2211  </refnamediv>
2212
2213  <indexterm><primary>SPI_copytupledesc</primary></indexterm>
2214
2215  <refsynopsisdiv>
2216 <synopsis>
2217 TupleDesc SPI_copytupledesc(TupleDesc <parameter>tupdesc</parameter>)
2218 </synopsis>
2219  </refsynopsisdiv>
2220
2221  <refsect1>
2222   <title>Description</title>
2223
2224   <para>
2225    <function>SPI_copytupledesc</function> makes a copy of a row
2226    descriptor in the upper executor context.
2227   </para>
2228  </refsect1>
2229
2230  <refsect1>
2231   <title>Arguments</title>
2232
2233   <variablelist>
2234    <varlistentry>
2235     <term><literal>TupleDesc <parameter>tupdesc</parameter></literal></term>
2236     <listitem>
2237      <para>
2238       row descriptor to be copied
2239      </para>
2240     </listitem>
2241    </varlistentry>
2242   </variablelist>
2243  </refsect1>
2244
2245  <refsect1>
2246   <title>Return Value</title>
2247
2248   <para>
2249    the copied row descriptor; <symbol>NULL</symbol> only if
2250    <parameter>tupdesc</parameter> is <symbol>NULL</symbol>
2251   </para>
2252  </refsect1>
2253 </refentry>
2254
2255 <!-- *********************************************** -->
2256
2257 <refentry id="spi-spi-copytupleintoslot">
2258  <refmeta>
2259   <refentrytitle>SPI_copytupleintoslot</refentrytitle>
2260  </refmeta>
2261
2262  <refnamediv>
2263   <refname>SPI_copytupleintoslot</refname>
2264   <refpurpose>make a copy of a row and descriptor in the upper executor context</refpurpose>
2265  </refnamediv>
2266
2267  <indexterm><primary>SPI_copytupleintoslot</primary></indexterm>
2268
2269  <refsynopsisdiv>
2270 <synopsis>
2271 TupleTableSlot * SPI_copytupleintoslot(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)
2272 </synopsis>
2273  </refsynopsisdiv>
2274
2275  <refsect1>
2276   <title>Description</title>
2277
2278   <para>
2279    <function>SPI_copytupleintoslot</function> makes a copy of a row in
2280    the upper executor context, returning it in the form of a filled-in
2281    <type>TupleTableSlot</type> structure.
2282   </para>
2283  </refsect1>
2284
2285  <refsect1>
2286   <title>Arguments</title>
2287
2288   <variablelist>
2289    <varlistentry>
2290     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2291     <listitem>
2292      <para>
2293       row to be copied
2294      </para>
2295     </listitem>
2296    </varlistentry>
2297
2298    <varlistentry>
2299     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2300     <listitem>
2301      <para>
2302       row descriptor to be copied
2303      </para>
2304     </listitem>
2305    </varlistentry>
2306   </variablelist>
2307  </refsect1>
2308
2309  <refsect1>
2310   <title>Return Value</title>
2311
2312   <para>
2313    <type>TupleTableSlot</type> containing the copied row and
2314    descriptor; <symbol>NULL</symbol> only if
2315    <parameter>row</parameter> or <parameter>rowdesc</parameter> are
2316    <symbol>NULL</symbol>
2317   </para>
2318  </refsect1>
2319 </refentry>
2320
2321 <!-- *********************************************** -->
2322
2323 <refentry id="spi-spi-modifytuple">
2324  <refmeta>
2325   <refentrytitle>SPI_modifytuple</refentrytitle>
2326  </refmeta>
2327
2328  <refnamediv>
2329   <refname>SPI_modifytuple</refname>
2330   <refpurpose>create a row by replacing selected fields of a given row</refpurpose>
2331  </refnamediv>
2332
2333  <indexterm><primary>SPI_modifytuple</primary></indexterm>
2334
2335  <refsynopsisdiv>
2336 <synopsis>
2337 HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parameter>row</parameter>, <parameter>ncols</parameter>, <parameter>colnum</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>)
2338 </synopsis>
2339  </refsynopsisdiv>
2340
2341  <refsect1>
2342   <title>Description</title>
2343
2344   <para>
2345    <function>SPI_modifytuple</function> creates a new row by
2346    substituting new values for selected columns, copying the original
2347    row's columns at other positions.  The input row is not modified.
2348   </para>
2349  </refsect1>
2350
2351  <refsect1>
2352   <title>Arguments</title>
2353
2354   <variablelist>
2355    <varlistentry>
2356     <term><literal>Relation <parameter>rel</parameter></literal></term>
2357     <listitem>
2358      <para>
2359       Used only as the source of the row descriptor for the row.
2360       (Passing a relation rather than a row descriptor is a
2361       misfeature.)
2362      </para>
2363     </listitem>
2364    </varlistentry>
2365
2366    <varlistentry>
2367     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2368     <listitem>
2369      <para>
2370       row to be modified
2371      </para>
2372     </listitem>
2373    </varlistentry>
2374
2375    <varlistentry>
2376     <term><literal>int <parameter>ncols</parameter></literal></term>
2377     <listitem>
2378      <para>
2379       number of column numbers in the array
2380       <parameter>colnum</parameter>
2381      </para>
2382     </listitem>
2383    </varlistentry>
2384
2385    <varlistentry>
2386     <term><literal>int * <parameter>colnum</parameter></literal></term>
2387     <listitem>
2388      <para>
2389       array of the numbers of the columns that are to be changed
2390       (count starts at 1)
2391      </para>
2392     </listitem>
2393    </varlistentry>
2394
2395    <varlistentry>
2396     <term><literal>Datum * <parameter>values</parameter></literal></term>
2397     <listitem>
2398      <para>
2399       new values for the specified columns
2400      </para>
2401     </listitem>
2402    </varlistentry>
2403
2404    <varlistentry>
2405     <term><literal>const char * <parameter>Nulls</parameter></literal></term>
2406     <listitem>
2407      <para>
2408       which new values are null, if any (see <function>SPI_execp</function> for the format)
2409      </para>
2410     </listitem>
2411    </varlistentry>
2412   </variablelist>
2413  </refsect1>
2414
2415  <refsect1>
2416   <title>Return Value</title>
2417
2418   <para>
2419    new row with modifications, allocated in the upper executor
2420    context; <symbol>NULL</symbol> only if <parameter>row</parameter>
2421    is <symbol>NULL</symbol>
2422   </para>
2423
2424   <para>
2425    On error, <varname>SPI_result</varname> is set as follows:
2426    <variablelist>
2427     <varlistentry>
2428      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
2429      <listitem>
2430       <para>
2431        if <parameter>rel</> is <symbol>NULL</>, or if
2432        <parameter>row</> is <symbol>NULL</>, or if <parameter>ncols</>
2433        is less than or equal to 0, or if <parameter>colnum</> is
2434        <symbol>NULL</>, or if <parameter>values</> is <symbol>NULL</>.
2435       </para>
2436      </listitem>
2437     </varlistentry>
2438
2439     <varlistentry>
2440      <term><symbol>SPI_ERROR_NOATTRIBUTE</symbol></term>
2441      <listitem>
2442       <para>
2443        if <parameter>colnum</> contains an invalid column number (less
2444        than or equal to 0 or greater than the number of column in
2445        <parameter>row</>)
2446       </para>
2447      </listitem>
2448     </varlistentry>
2449    </variablelist>
2450   </para>
2451  </refsect1>
2452 </refentry>
2453
2454 <!-- *********************************************** -->
2455
2456 <refentry id="spi-spi-freetuple">
2457  <refmeta>
2458   <refentrytitle>SPI_freetuple</refentrytitle>
2459  </refmeta>
2460
2461  <refnamediv>
2462   <refname>SPI_freetuple</refname>
2463   <refpurpose>frees a row allocated in the upper executor context</refpurpose>
2464  </refnamediv>
2465
2466  <indexterm><primary>SPI_freetuple</primary></indexterm>
2467
2468  <refsynopsisdiv>
2469 <synopsis>
2470 void SPI_freetuple(HeapTuple <parameter>row</parameter>)
2471 </synopsis>
2472  </refsynopsisdiv>
2473
2474  <refsect1>
2475   <title>Description</title>
2476
2477   <para>
2478    <function>SPI_freetuple</function> frees a row previously allocated
2479    in the upper executor context.
2480   </para>
2481
2482   <para>
2483    This function is no longer different from plain
2484    <function>heap_freetuple</function>.  It's kept just for backward
2485    compatibility of existing code.
2486   </para>
2487  </refsect1>
2488
2489  <refsect1>
2490   <title>Arguments</title>
2491
2492   <variablelist>
2493    <varlistentry>
2494     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2495     <listitem>
2496      <para>
2497       row to free
2498      </para>
2499     </listitem>
2500    </varlistentry>
2501   </variablelist>
2502  </refsect1>
2503 </refentry>
2504
2505 <!-- *********************************************** -->
2506
2507 <refentry id="spi-spi-freetupletable">
2508  <refmeta>
2509   <refentrytitle>SPI_freetuptable</refentrytitle>
2510  </refmeta>
2511
2512  <refnamediv>
2513   <refname>SPI_freetuptable</refname>
2514   <refpurpose>free a row set created by <function>SPI_exec</> or a similar function</refpurpose>
2515  </refnamediv>
2516
2517  <indexterm><primary>SPI_freetuptable</primary></indexterm>
2518
2519  <refsynopsisdiv>
2520 <synopsis>
2521 void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)
2522 </synopsis>
2523  </refsynopsisdiv>
2524
2525  <refsect1>
2526   <title>Description</title>
2527
2528   <para>
2529    <function>SPI_freetuptable</function> frees a row set created by a
2530    prior SPI command execution function, such as
2531    <function>SPI_exec</>.  Therefore, this function is usually called
2532    with the global variable <varname>SPI_tupletable</varname> as
2533    argument.
2534   </para>
2535
2536   <para>
2537    This function is useful if a SPI procedure needs to execute
2538    multiple commands and does not want to keep the results of earlier
2539    commands around until it ends.  Note that any unfreed row sets will
2540    be freed anyway at <function>SPI_finish</>.
2541   </para>
2542  </refsect1>
2543
2544  <refsect1>
2545   <title>Arguments</title>
2546
2547   <variablelist>
2548    <varlistentry>
2549     <term><literal>SPITupleTable * <parameter>tuptable</parameter></literal></term>
2550     <listitem>
2551      <para>
2552       pointer to row set to free
2553      </para>
2554     </listitem>
2555    </varlistentry>
2556   </variablelist>
2557  </refsect1>
2558 </refentry>
2559
2560 <!-- *********************************************** -->
2561
2562 <refentry id="spi-spi-freeplan">
2563  <refmeta>
2564   <refentrytitle>SPI_freeplan</refentrytitle>
2565  </refmeta>
2566
2567  <refnamediv>
2568   <refname>SPI_freeplan</refname>
2569   <refpurpose>free a previously saved plan</refpurpose>
2570  </refnamediv>
2571
2572  <indexterm><primary>SPI_freeplan</primary></indexterm>
2573
2574  <refsynopsisdiv>
2575 <synopsis>
2576 int SPI_freeplan(void *<parameter>plan</parameter>)
2577 </synopsis>
2578  </refsynopsisdiv>
2579
2580  <refsect1>
2581   <title>Description</title>
2582
2583   <para>
2584    <function>SPI_freeplan</function> releases a command execution plan
2585    previously returned by <function>SPI_prepare</function> or saved by
2586    <function>SPI_saveplan</function>.
2587   </para>
2588  </refsect1>
2589
2590  <refsect1>
2591   <title>Arguments</title>
2592
2593   <variablelist>
2594    <varlistentry>
2595     <term><literal>void * <parameter>plan</parameter></literal></term>
2596     <listitem>
2597      <para>
2598       pointer to plan to free
2599      </para>
2600     </listitem>
2601    </varlistentry>
2602   </variablelist>
2603  </refsect1>
2604
2605  <refsect1>
2606   <title>Return Value</title>
2607
2608   <para>
2609    <symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>plan</parameter>
2610    is <symbol>NULL</symbol>.
2611   </para>
2612  </refsect1>
2613 </refentry>
2614
2615  </sect1>
2616
2617  <sect1 id="spi-visibility">
2618   <title>Visibility of Data Changes</title>
2619
2620   <para>
2621    The following two rules govern the visibility of data changes in
2622    functions that use SPI (or any other C function):
2623
2624    <itemizedlist>
2625     <listitem>
2626      <para>
2627       During the execution of an SQL command, any data changes made by
2628       the command (or by function called by the command, including
2629       trigger functions) are invisible to the command.  For
2630       example, in command
2631 <programlisting>
2632 INSERT INTO a SELECT * FROM a;
2633 </programlisting>
2634       the inserted rows are invisible to the <command>SELECT</command>
2635       part.
2636      </para>
2637     </listitem>
2638
2639     <listitem>
2640      <para>
2641       Changes made by a command C are visible to all commands that are
2642       started after C, no matter whether they are started inside C
2643       (during the execution of C) or after C is done.
2644      </para>
2645     </listitem>
2646    </itemizedlist>
2647   </para>
2648
2649   <para>
2650    The next section contains an example that illustrates the
2651    application of these rules.
2652   </para>
2653  </sect1>
2654
2655  <sect1 id="spi-examples">
2656   <title>Examples</title>
2657
2658   <para>
2659    This section contains a very simple example of SPI usage. The
2660    procedure <function>execq</function> takes an SQL command as its
2661    first argument and a row count as its second, executes the command
2662    using <function>SPI_exec</function> and returns the number of rows
2663    that were processed by the command.  You can find more complex
2664    examples for SPI in the source tree in
2665    <filename>src/test/regress/regress.c</filename> and in
2666    <filename>contrib/spi</filename>.
2667   </para>
2668
2669 <programlisting>
2670 #include "executor/spi.h"
2671
2672 int execq(text *sql, int cnt);
2673
2674 int
2675 execq(text *sql, int cnt)
2676 {
2677     char *command;
2678     int ret;
2679     int proc;
2680
2681     /* Convert given text object to a C string */
2682     command = DatumGetCString(DirectFunctionCall1(textout,
2683                                                   PointerGetDatum(sql)));
2684
2685     SPI_connect();
2686
2687     ret = SPI_exec(command, cnt);
2688
2689     proc = SPI_processed;
2690     /*
2691      * If this is a SELECT and some rows were fetched,
2692      * then the rows are printed via elog(INFO).
2693      */
2694     if (ret == SPI_OK_SELECT && SPI_processed > 0)
2695     {
2696         TupleDesc tupdesc = SPI_tuptable->tupdesc;
2697         SPITupleTable *tuptable = SPI_tuptable;
2698         char buf[8192];
2699         int i, j;
2700
2701         for (j = 0; j < proc; j++)
2702         {
2703             HeapTuple tuple = tuptable->vals[j];
2704
2705             for (i = 1, buf[0] = 0; i <= tupdesc->natts; i++)
2706                 snprintf(buf + strlen (buf), sizeof(buf) - strlen(buf), " %s%s",
2707                         SPI_getvalue(tuple, tupdesc, i),
2708                         (i == tupdesc->natts) ? " " : " |");
2709             elog (INFO, "EXECQ: %s", buf);
2710         }
2711     }
2712
2713     SPI_finish();
2714     pfree(command);
2715
2716     return (proc);
2717 }
2718 </programlisting>
2719
2720   <para>
2721    (This function uses call convention version 0, to make the example
2722    easier to understand.  In real applications you should user the new
2723    version 1 interface.)
2724   </para>
2725
2726   <para>
2727    This is how you declare the function after having compiled it into
2728    a shared library:
2729
2730 <programlisting>
2731 CREATE FUNCTION execq(text, integer) RETURNS integer
2732     AS '<replaceable>filename</replaceable>'
2733     LANGUAGE C;
2734 </programlisting>
2735   </para>
2736
2737   <para>
2738    Here is a sample session:
2739
2740 <programlisting>
2741 => SELECT execq('CREATE TABLE a (x integer)', 0);
2742  execq
2743 -------
2744      0
2745 (1 row)
2746
2747 => INSERT INTO a VALUES (execq('INSERT INTO a VALUES (0)', 0));
2748 INSERT 167631 1
2749 => SELECT execq('SELECT * FROM a', 0);
2750 INFO:  EXECQ:  0    -- inserted by execq
2751 INFO:  EXECQ:  1    -- returned by execq and inserted by upper INSERT
2752
2753  execq
2754 -------
2755      2
2756 (1 row)
2757
2758 => SELECT execq('INSERT INTO a SELECT x + 2 FROM a', 1);
2759  execq
2760 -------
2761      1
2762 (1 row)
2763
2764 => SELECT execq('SELECT * FROM a', 10);
2765 INFO:  EXECQ:  0
2766 INFO:  EXECQ:  1
2767 INFO:  EXECQ:  2    -- 0 + 2, only one row inserted - as specified
2768
2769  execq
2770 -------
2771      3              -- 10 is the max value only, 3 is the real number of rows
2772 (1 row)
2773
2774 => DELETE FROM a;
2775 DELETE 3
2776 => INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
2777 INSERT 167712 1
2778 => SELECT * FROM a;
2779  x
2780 ---
2781  1                  -- no rows in a (0) + 1
2782 (1 row)
2783
2784 => INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
2785 INFO:  EXECQ:  0
2786 INSERT 167713 1
2787 => SELECT * FROM a;
2788  x
2789 ---
2790  1
2791  2                  -- there was one row in a + 1
2792 (2 rows)
2793
2794 -- This demonstrates the data changes visibility rule:
2795
2796 => INSERT INTO a SELECT execq('SELECT * FROM a', 0) * x FROM a;
2797 INFO:  EXECQ:  1
2798 INFO:  EXECQ:  2
2799 INFO:  EXECQ:  1
2800 INFO:  EXECQ:  2
2801 INFO:  EXECQ:  2
2802 INSERT 0 2
2803 => SELECT * FROM a;
2804  x
2805 ---
2806  1
2807  2
2808  2                  -- 2 rows * 1 (x in first row)
2809  6                  -- 3 rows (2 + 1 just inserted) * 2 (x in second row)
2810 (4 rows)               ^^^^^^
2811                        rows visible to execq() in different invocations
2812 </programlisting>
2813   </para>
2814  </sect1>
2815 </chapter>