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

   1 <!-- $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.62 2008/04/01 03:09:30 tgl Exp $ -->
   2
   3 <chapter id="spi">
   4  <title>Server Programming Interface</title>
   5
   6  <indexterm zone="spi">
   7   <primary>SPI</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <firstterm>Server Programming Interface</firstterm>
  12   (<acronym>SPI</acronym>) gives writers of user-defined
  13   <acronym>C</acronym> functions the ability to run
  14   <acronym>SQL</acronym> commands inside their functions.
  15   <acronym>SPI</acronym> is a set of
  16   interface functions to simplify access to the parser, planner,
  17   and executor. <acronym>SPI</acronym> also does some
  18   memory management.
  19  </para>
  20
  21  <note>
  22   <para>
  23    The available procedural languages provide various means to
  24    execute SQL commands from procedures.  Most of these facilities are
  25    based on SPI, so this documentation might be of use for users
  26    of those languages as well.
  27   </para>
  28  </note>
  29
  30  <para>
  31   To avoid misunderstanding we'll use the term <quote>function</quote>
  32   when we speak of <acronym>SPI</acronym> interface functions and
  33   <quote>procedure</quote> for a user-defined C-function that is
  34   using <acronym>SPI</acronym>.
  35  </para>
  36
  37  <para>
  38   Note that if a command invoked via SPI fails, then control will not be
  39   returned to your procedure.  Rather, the
  40   transaction or subtransaction in which your procedure executes will be
  41   rolled back.  (This might seem surprising given that the SPI functions mostly
  42   have documented error-return conventions.  Those conventions only apply
  43   for errors detected within the SPI functions themselves, however.)
  44   It is possible to recover control after an error by establishing your own
  45   subtransaction surrounding SPI calls that might fail.  This is not currently
  46   documented because the mechanisms required are still in flux.
  47  </para>
  48
  49  <para>
  50   <acronym>SPI</acronym> functions return a nonnegative result on
  51   success (either via a returned integer value or in the global
  52   variable <varname>SPI_result</varname>, as described below).  On
  53   error, a negative result or <symbol>NULL</symbol> will be returned.
  54  </para>
  55
  56  <para>
  57   Source code files that use SPI must include the header file
  58   <filename>executor/spi.h</filename>.
  59  </para>
  60
  61
  62 <sect1 id="spi-interface">
  63  <title>Interface Functions</title>
  64
  65  <refentry id="spi-spi-connect">
  66   <refmeta>
  67    <refentrytitle>SPI_connect</refentrytitle>
  68   </refmeta>
  69
  70   <refnamediv>
  71    <refname>SPI_connect</refname>
  72    <refpurpose>connect a procedure to the SPI manager</refpurpose>
  73  </refnamediv>
  74
  75  <indexterm><primary>SPI_connect</primary></indexterm>
  76
  77  <refsynopsisdiv>
  78 <synopsis>
  79 int SPI_connect(void)
  80 </synopsis>
  81  </refsynopsisdiv>
  82
  83  <refsect1>
  84   <title>Description</title>
  85
  86   <para>
  87    <function>SPI_connect</function> opens a connection from a
  88    procedure invocation to the SPI manager.  You must call this
  89    function if you want to execute commands through SPI.  Some utility
  90    SPI functions can be called from unconnected procedures.
  91   </para>
  92
  93   <para>
  94    If your procedure is already connected,
  95    <function>SPI_connect</function> will return the error code
  96    <returnvalue>SPI_ERROR_CONNECT</returnvalue>.  This could happen if
  97    a procedure that has called <function>SPI_connect</function>
  98    directly calls another procedure that calls
  99    <function>SPI_connect</function>.  While recursive calls to the
 100    <acronym>SPI</acronym> manager are permitted when an SQL command
 101    called through SPI invokes another function that uses
 102    <acronym>SPI</acronym>, directly nested calls to
 103    <function>SPI_connect</function> and
 104    <function>SPI_finish</function> are forbidden.
 105    (But see <function>SPI_push</function> and <function>SPI_pop</function>.)
 106   </para>
 107  </refsect1>
 108
 109  <refsect1>
 110   <title>Return Value</title>
 111
 112   <variablelist>
 113    <varlistentry>
 114     <term><symbol>SPI_OK_CONNECT</symbol></term>
 115     <listitem>
 116      <para>
 117       on success
 118      </para>
 119     </listitem>
 120    </varlistentry>
 121
 122    <varlistentry>
 123     <term><symbol>SPI_ERROR_CONNECT</symbol></term>
 124     <listitem>
 125      <para>
 126       on error
 127      </para>
 128     </listitem>
 129    </varlistentry>
 130   </variablelist>
 131  </refsect1>
 132 </refentry>
 133
 134 <!-- *********************************************** -->
 135
 136 <refentry id="spi-spi-finish">
 137  <refmeta>
 138   <refentrytitle>SPI_finish</refentrytitle>
 139  </refmeta>
 140
 141  <refnamediv>
 142   <refname>SPI_finish</refname>
 143   <refpurpose>disconnect a procedure from the SPI manager</refpurpose>
 144  </refnamediv>
 145
 146  <indexterm><primary>SPI_finish</primary></indexterm>
 147
 148  <refsynopsisdiv>
 149 <synopsis>
 150 int SPI_finish(void)
 151 </synopsis>
 152  </refsynopsisdiv>
 153
 154  <refsect1>
 155   <title>Description</title>
 156
 157   <para>
 158    <function>SPI_finish</function> closes an existing connection to
 159    the SPI manager.  You must call this function after completing the
 160    SPI operations needed during your procedure's current invocation.
 161    You do not need to worry about making this happen, however, if you
 162    abort the transaction via <literal>elog(ERROR)</literal>.  In that
 163    case SPI will clean itself up automatically.
 164   </para>
 165
 166   <para>
 167    If <function>SPI_finish</function> is called without having a valid
 168    connection, it will return <symbol>SPI_ERROR_UNCONNECTED</symbol>.
 169    There is no fundamental problem with this; it means that the SPI
 170    manager has nothing to do.
 171   </para>
 172  </refsect1>
 173
 174  <refsect1>
 175   <title>Return Value</title>
 176
 177   <variablelist>
 178    <varlistentry>
 179     <term><symbol>SPI_OK_FINISH</symbol></term>
 180     <listitem>
 181      <para>
 182       if properly disconnected
 183      </para>
 184     </listitem>
 185    </varlistentry>
 186
 187    <varlistentry>
 188     <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
 189     <listitem>
 190      <para>
 191       if called from an unconnected procedure
 192      </para>
 193     </listitem>
 194    </varlistentry>
 195   </variablelist>
 196  </refsect1>
 197 </refentry>
 198
 199 <!-- *********************************************** -->
 200
 201 <refentry id="spi-spi-push">
 202  <refmeta>
 203   <refentrytitle>SPI_push</refentrytitle>
 204  </refmeta>
 205
 206  <refnamediv>
 207   <refname>SPI_push</refname>
 208   <refpurpose>push SPI stack to allow recursive SPI usage</refpurpose>
 209  </refnamediv>
 210
 211  <indexterm><primary>SPI_push</primary></indexterm>
 212
 213  <refsynopsisdiv>
 214 <synopsis>
 215 void SPI_push(void)
 216 </synopsis>
 217  </refsynopsisdiv>
 218
 219  <refsect1>
 220   <title>Description</title>
 221
 222   <para>
 223    <function>SPI_push</function> should be called before executing another
 224    procedure that might itself wish to use SPI.
 225    After <function>SPI_push</function>, SPI is no longer in a
 226    <quote>connected</> state, and SPI function calls will be rejected unless
 227    a fresh <function>SPI_connect</function> is done.  This ensures a clean
 228    separation between your procedure's SPI state and that of another procedure
 229    you call.  After the other procedure returns, call
 230    <function>SPI_pop</function> to restore access to your own SPI state.
 231   </para>
 232
 233   <para>
 234    Note that <function>SPI_execute</function> and related functions
 235    automatically do the equivalent of <function>SPI_push</function> before
 236    passing control back to the SQL execution engine, so it is not necessary
 237    for you to worry about this when using those functions.
 238    Only when you are directly calling arbitrary code that might contain
 239    <function>SPI_connect</function> calls do you need to issue
 240    <function>SPI_push</function> and <function>SPI_pop</function>.
 241   </para>
 242  </refsect1>
 243
 244 </refentry>
 245
 246 <!-- *********************************************** -->
 247
 248 <refentry id="spi-spi-pop">
 249  <refmeta>
 250   <refentrytitle>SPI_pop</refentrytitle>
 251  </refmeta>
 252
 253  <refnamediv>
 254   <refname>SPI_pop</refname>
 255   <refpurpose>pop SPI stack to return from recursive SPI usage</refpurpose>
 256  </refnamediv>
 257
 258  <indexterm><primary>SPI_pop</primary></indexterm>
 259
 260  <refsynopsisdiv>
 261 <synopsis>
 262 void SPI_pop(void)
 263 </synopsis>
 264  </refsynopsisdiv>
 265
 266  <refsect1>
 267   <title>Description</title>
 268
 269   <para>
 270    <function>SPI_pop</function> pops the previous environment from the
 271    SPI call stack.  See <function>SPI_push</function>.
 272   </para>
 273  </refsect1>
 274
 275 </refentry>
 276
 277 <!-- *********************************************** -->
 278
 279 <refentry id="spi-spi-execute">
 280  <refmeta>
 281   <refentrytitle>SPI_execute</refentrytitle>
 282  </refmeta>
 283
 284  <refnamediv>
 285   <refname>SPI_execute</refname>
 286   <refpurpose>execute a command</refpurpose>
 287  </refnamediv>
 288
 289  <indexterm><primary>SPI_execute</primary></indexterm>
 290
 291  <refsynopsisdiv>
 292 <synopsis>
 293 int SPI_execute(const char * <parameter>command</parameter>, bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
 294 </synopsis>
 295  </refsynopsisdiv>
 296
 297  <refsect1>
 298   <title>Description</title>
 299
 300   <para>
 301    <function>SPI_execute</function> executes the specified SQL command
 302    for <parameter>count</parameter> rows.  If <parameter>read_only</parameter>
 303    is <literal>true</>, the command must be read-only, and execution overhead
 304    is somewhat reduced.
 305   </para>
 306
 307   <para>
 308    This function can only be called from a connected procedure.
 309   </para>
 310
 311   <para>
 312    If <parameter>count</parameter> is zero then the command is executed
 313    for all rows that it applies to.  If <parameter>count</parameter>
 314    is greater than 0, then the number of rows for which the command
 315    will be executed is restricted (much like a
 316    <literal>LIMIT</literal> clause). For example:
 317 <programlisting>
 318 SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
 319 </programlisting>
 320    will allow at most 5 rows to be inserted into the table.
 321   </para>
 322
 323   <para>
 324    You can pass multiple commands in one string, but later commands cannot
 325    depend on the creation of objects earlier in the string, because the
 326    whole string will be parsed and planned before execution begins.
 327    <function>SPI_execute</function> returns the
 328    result for the command executed last.  The <parameter>count</parameter>
 329    limit applies to each command separately, but it is not applied to
 330    hidden commands generated by rules.
 331   </para>
 332
 333   <para>
 334    When <parameter>read_only</parameter> is <literal>false</>,
 335    <function>SPI_execute</function> increments the command
 336    counter and computes a new <firstterm>snapshot</> before executing each
 337    command in the string.  The snapshot does not actually change if the
 338    current transaction isolation level is <literal>SERIALIZABLE</>, but in
 339    <literal>READ COMMITTED</> mode the snapshot update allows each command to
 340    see the results of newly committed transactions from other sessions.
 341    This is essential for consistent behavior when the commands are modifying
 342    the database.
 343   </para>
 344
 345   <para>
 346    When <parameter>read_only</parameter> is <literal>true</>,
 347    <function>SPI_execute</function> does not update either the snapshot
 348    or the command counter, and it allows only plain <command>SELECT</>
 349    commands to appear in the command string.  The commands are executed
 350    using the snapshot previously established for the surrounding query.
 351    This execution mode is somewhat faster than the read/write mode due
 352    to eliminating per-command overhead.  It also allows genuinely
 353    <firstterm>stable</> functions to be built: since successive executions
 354    will all use the same snapshot, there will be no change in the results.
 355   </para>
 356
 357   <para>
 358    It is generally unwise to mix read-only and read-write commands within
 359    a single function using SPI; that could result in very confusing behavior,
 360    since the read-only queries would not see the results of any database
 361    updates done by the read-write queries.
 362   </para>
 363
 364   <para>
 365    The actual number of rows for which the (last) command was executed
 366    is returned in the global variable <varname>SPI_processed</varname>.
 367    If the return value of the function is <symbol>SPI_OK_SELECT</symbol>,
 368    <symbol>SPI_OK_INSERT_RETURNING</symbol>,
 369    <symbol>SPI_OK_DELETE_RETURNING</symbol>, or
 370    <symbol>SPI_OK_UPDATE_RETURNING</symbol>,
 371    then you can use the
 372    global pointer <literal>SPITupleTable *SPI_tuptable</literal> to
 373    access the result rows.  Some utility commands (such as
 374    <command>EXPLAIN</>) also return row sets, and <literal>SPI_tuptable</>
 375    will contain the result in these cases too.
 376   </para>
 377
 378   <para>
 379    The structure <structname>SPITupleTable</structname> is defined
 380    thus:
 381 <programlisting>
 382 typedef struct
 383 {
 384     MemoryContext tuptabcxt;    /* memory context of result table */
 385     uint32      alloced;        /* number of alloced vals */
 386     uint32      free;           /* number of free vals */
 387     TupleDesc   tupdesc;        /* row descriptor */
 388     HeapTuple  *vals;           /* rows */
 389 } SPITupleTable;
 390 </programlisting>
 391    <structfield>vals</> is an array of pointers to rows.  (The number
 392    of valid entries is given by <varname>SPI_processed</varname>.)
 393    <structfield>tupdesc</> is a row descriptor which you can pass to
 394    SPI functions dealing with rows.  <structfield>tuptabcxt</>,
 395    <structfield>alloced</>, and <structfield>free</> are internal
 396    fields not intended for use by SPI callers.
 397   </para>
 398
 399   <para>
 400    <function>SPI_finish</function> frees all
 401    <structname>SPITupleTable</>s allocated during the current
 402    procedure.  You can free a particular result table earlier, if you
 403    are done with it, by calling <function>SPI_freetuptable</function>.
 404   </para>
 405  </refsect1>
 406
 407  <refsect1>
 408   <title>Arguments</title>
 409
 410   <variablelist>
 411    <varlistentry>
 412     <term><literal>const char * <parameter>command</parameter></literal></term>
 413     <listitem>
 414      <para>
 415       string containing command to execute
 416      </para>
 417     </listitem>
 418    </varlistentry>
 419
 420    <varlistentry>
 421     <term><literal>bool <parameter>read_only</parameter></literal></term>
 422     <listitem>
 423      <para>
 424       <literal>true</> for read-only execution
 425      </para>
 426     </listitem>
 427    </varlistentry>
 428
 429    <varlistentry>
 430     <term><literal>long <parameter>count</parameter></literal></term>
 431     <listitem>
 432      <para>
 433       maximum number of rows to process or return
 434      </para>
 435     </listitem>
 436    </varlistentry>
 437   </variablelist>
 438  </refsect1>
 439
 440  <refsect1>
 441   <title>Return Value</title>
 442
 443   <para>
 444    If the execution of the command was successful then one of the
 445    following (nonnegative) values will be returned:
 446
 447    <variablelist>
 448     <varlistentry>
 449      <term><symbol>SPI_OK_SELECT</symbol></term>
 450      <listitem>
 451       <para>
 452        if a <command>SELECT</command> (but not <command>SELECT
 453        INTO</>) was executed
 454       </para>
 455      </listitem>
 456     </varlistentry>
 457
 458     <varlistentry>
 459      <term><symbol>SPI_OK_SELINTO</symbol></term>
 460      <listitem>
 461       <para>
 462        if a <command>SELECT INTO</command> was executed
 463       </para>
 464      </listitem>
 465     </varlistentry>
 466
 467     <varlistentry>
 468      <term><symbol>SPI_OK_INSERT</symbol></term>
 469      <listitem>
 470       <para>
 471        if an <command>INSERT</command> was executed
 472       </para>
 473      </listitem>
 474     </varlistentry>
 475
 476     <varlistentry>
 477      <term><symbol>SPI_OK_DELETE</symbol></term>
 478      <listitem>
 479       <para>
 480        if a <command>DELETE</command> was executed
 481       </para>
 482      </listitem>
 483     </varlistentry>
 484
 485     <varlistentry>
 486      <term><symbol>SPI_OK_UPDATE</symbol></term>
 487      <listitem>
 488       <para>
 489        if an <command>UPDATE</command> was executed
 490       </para>
 491      </listitem>
 492     </varlistentry>
 493
 494     <varlistentry>
 495      <term><symbol>SPI_OK_INSERT_RETURNING</symbol></term>
 496      <listitem>
 497       <para>
 498        if an <command>INSERT RETURNING</command> was executed
 499       </para>
 500      </listitem>
 501     </varlistentry>
 502
 503     <varlistentry>
 504      <term><symbol>SPI_OK_DELETE_RETURNING</symbol></term>
 505      <listitem>
 506       <para>
 507        if a <command>DELETE RETURNING</command> was executed
 508       </para>
 509      </listitem>
 510     </varlistentry>
 511
 512     <varlistentry>
 513      <term><symbol>SPI_OK_UPDATE_RETURNING</symbol></term>
 514      <listitem>
 515       <para>
 516        if an <command>UPDATE RETURNING</command> was executed
 517       </para>
 518      </listitem>
 519     </varlistentry>
 520
 521     <varlistentry>
 522      <term><symbol>SPI_OK_UTILITY</symbol></term>
 523      <listitem>
 524       <para>
 525        if a utility command (e.g., <command>CREATE TABLE</command>)
 526        was executed
 527       </para>
 528      </listitem>
 529     </varlistentry>
 530    </variablelist>
 531   </para>
 532
 533   <para>
 534    On error, one of the following negative values is returned:
 535
 536    <variablelist>
 537     <varlistentry>
 538      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
 539      <listitem>
 540       <para>
 541        if <parameter>command</parameter> is <symbol>NULL</symbol> or
 542        <parameter>count</parameter> is less than 0
 543       </para>
 544      </listitem>
 545     </varlistentry>
 546
 547     <varlistentry>
 548      <term><symbol>SPI_ERROR_COPY</symbol></term>
 549      <listitem>
 550       <para>
 551        if <command>COPY TO stdout</> or <command>COPY FROM stdin</>
 552        was attempted
 553       </para>
 554      </listitem>
 555     </varlistentry>
 556
 557     <varlistentry>
 558      <term><symbol>SPI_ERROR_TRANSACTION</symbol></term>
 559      <listitem>
 560       <para>
 561        if a transaction manipulation command was attempted
 562        (<command>BEGIN</>,
 563        <command>COMMIT</>,
 564        <command>ROLLBACK</>,
 565        <command>SAVEPOINT</>,
 566        <command>PREPARE TRANSACTION</>,
 567        <command>COMMIT PREPARED</>,
 568        <command>ROLLBACK PREPARED</>,
 569        or any variant thereof)
 570       </para>
 571      </listitem>
 572     </varlistentry>
 573
 574     <varlistentry>
 575      <term><symbol>SPI_ERROR_OPUNKNOWN</symbol></term>
 576      <listitem>
 577       <para>
 578        if the command type is unknown (shouldn't happen)
 579       </para>
 580      </listitem>
 581     </varlistentry>
 582
 583     <varlistentry>
 584      <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
 585      <listitem>
 586       <para>
 587        if called from an unconnected procedure
 588       </para>
 589      </listitem>
 590     </varlistentry>
 591    </variablelist>
 592   </para>
 593  </refsect1>
 594
 595  <refsect1>
 596   <title>Notes</title>
 597
 598   <para>
 599    The functions <function>SPI_execute</function>,
 600    <function>SPI_exec</function>,
 601    <function>SPI_execute_plan</function>, and
 602    <function>SPI_execp</function> change both
 603    <varname>SPI_processed</varname> and
 604    <varname>SPI_tuptable</varname> (just the pointer, not the contents
 605    of the structure).  Save these two global variables into local
 606    procedure variables if you need to access the result table of
 607    <function>SPI_execute</function> or a related function
 608    across later calls.
 609   </para>
 610  </refsect1>
 611 </refentry>
 612
 613 <!-- *********************************************** -->
 614
 615 <refentry id="spi-spi-exec">
 616  <refmeta>
 617   <refentrytitle>SPI_exec</refentrytitle>
 618  </refmeta>
 619
 620  <refnamediv>
 621   <refname>SPI_exec</refname>
 622   <refpurpose>execute a read/write command</refpurpose>
 623  </refnamediv>
 624
 625  <indexterm><primary>SPI_exec</primary></indexterm>
 626
 627  <refsynopsisdiv>
 628 <synopsis>
 629 int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count</parameter>)
 630 </synopsis>
 631  </refsynopsisdiv>
 632
 633  <refsect1>
 634   <title>Description</title>
 635
 636   <para>
 637    <function>SPI_exec</function> is the same as
 638    <function>SPI_execute</function>, with the latter's
 639    <parameter>read_only</parameter> parameter always taken as
 640    <literal>false</>.
 641   </para>
 642  </refsect1>
 643
 644  <refsect1>
 645   <title>Arguments</title>
 646
 647   <variablelist>
 648    <varlistentry>
 649     <term><literal>const char * <parameter>command</parameter></literal></term>
 650     <listitem>
 651      <para>
 652       string containing command to execute
 653      </para>
 654     </listitem>
 655    </varlistentry>
 656
 657    <varlistentry>
 658     <term><literal>long <parameter>count</parameter></literal></term>
 659     <listitem>
 660      <para>
 661       maximum number of rows to process or return
 662      </para>
 663     </listitem>
 664    </varlistentry>
 665   </variablelist>
 666  </refsect1>
 667
 668  <refsect1>
 669   <title>Return Value</title>
 670
 671   <para>
 672    See <function>SPI_execute</function>.
 673   </para>
 674  </refsect1>
 675 </refentry>
 676
 677 <!-- *********************************************** -->
 678
 679 <refentry id="spi-spi-execute-with-args">
 680  <refmeta>
 681   <refentrytitle>SPI_execute_with_args</refentrytitle>
 682  </refmeta>
 683
 684  <refnamediv>
 685   <refname>SPI_execute_with_args</refname>
 686   <refpurpose>execute a command with out-of-line parameters</refpurpose>
 687  </refnamediv>
 688
 689  <indexterm><primary>SPI_execute_with_args</primary></indexterm>
 690
 691  <refsynopsisdiv>
 692 <synopsis>
 693 int SPI_execute_with_args(const char *<parameter>command</parameter>,
 694                           int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
 695                           Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
 696                           bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
 697 </synopsis>
 698  </refsynopsisdiv>
 699
 700  <refsect1>
 701   <title>Description</title>
 702
 703   <para>
 704    <function>SPI_execute_with_args</function> executes a command that might
 705    include references to externally supplied parameters.  The command text
 706    refers to a parameter as <literal>$<replaceable>n</></literal>, and
 707    the call specifies data types and values for each such symbol.
 708    <parameter>read_only</parameter> and <parameter>count</parameter> have
 709    the same interpretation as in <function>SPI_execute</function>.
 710   </para>
 711
 712   <para>
 713    The main advantage of this routine compared to
 714    <function>SPI_execute</function> is that data values can be inserted
 715    into the command without tedious quoting/escaping, and thus with much
 716    less risk of SQL-injection attacks.
 717   </para>
 718
 719   <para>
 720    Similar results can be achieved with <function>SPI_prepare</> followed by
 721    <function>SPI_execute_plan</function>; however, when using this function
 722    the query plan is customized to the specific parameter values provided.
 723    For one-time query execution, this function should be preferred.
 724    If the same command is to be executed with many different parameters,
 725    either method might be faster, depending on the cost of re-planning
 726    versus the benefit of custom plans.
 727   </para>
 728  </refsect1>
 729
 730  <refsect1>
 731   <title>Arguments</title>
 732
 733   <variablelist>
 734    <varlistentry>
 735     <term><literal>const char * <parameter>command</parameter></literal></term>
 736     <listitem>
 737      <para>
 738       command string
 739      </para>
 740     </listitem>
 741    </varlistentry>
 742
 743    <varlistentry>
 744     <term><literal>int <parameter>nargs</parameter></literal></term>
 745     <listitem>
 746      <para>
 747       number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
 748      </para>
 749     </listitem>
 750    </varlistentry>
 751
 752    <varlistentry>
 753     <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
 754     <listitem>
 755      <para>
 756       an array containing the <acronym>OID</acronym>s of
 757       the data types of the parameters
 758      </para>
 759     </listitem>
 760    </varlistentry>
 761
 762    <varlistentry>
 763     <term><literal>Datum * <parameter>values</parameter></literal></term>
 764     <listitem>
 765      <para>
 766       an array of actual parameter values
 767      </para>
 768     </listitem>
 769    </varlistentry>
 770
 771    <varlistentry>
 772     <term><literal>const char * <parameter>nulls</parameter></literal></term>
 773     <listitem>
 774      <para>
 775       an array describing which parameters are null
 776      </para>
 777
 778      <para>
 779       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
 780       <function>SPI_execute_with_args</function> assumes that no parameters are
 781       null.
 782      </para>
 783     </listitem>
 784    </varlistentry>
 785
 786    <varlistentry>
 787     <term><literal>bool <parameter>read_only</parameter></literal></term>
 788     <listitem>
 789      <para>
 790       <literal>true</> for read-only execution
 791      </para>
 792     </listitem>
 793    </varlistentry>
 794
 795    <varlistentry>
 796     <term><literal>long <parameter>count</parameter></literal></term>
 797     <listitem>
 798      <para>
 799       maximum number of rows to process or return
 800      </para>
 801     </listitem>
 802    </varlistentry>
 803   </variablelist>
 804  </refsect1>
 805
 806  <refsect1>
 807   <title>Return Value</title>
 808
 809   <para>
 810    The return value is the same as for <function>SPI_execute</function>.
 811   </para>
 812
 813   <para>
 814    <varname>SPI_processed</varname> and
 815    <varname>SPI_tuptable</varname> are set as in
 816    <function>SPI_execute</function> if successful.
 817   </para>
 818  </refsect1>
 819 </refentry>
 820
 821 <!-- *********************************************** -->
 822
 823 <refentry id="spi-spi-prepare">
 824  <refmeta>
 825   <refentrytitle>SPI_prepare</refentrytitle>
 826  </refmeta>
 827
 828  <refnamediv>
 829   <refname>SPI_prepare</refname>
 830   <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
 831  </refnamediv>
 832
 833  <indexterm><primary>SPI_prepare</primary></indexterm>
 834
 835  <refsynopsisdiv>
 836 <synopsis>
 837 SPIPlanPtr SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
 838 </synopsis>
 839  </refsynopsisdiv>
 840
 841  <refsect1>
 842   <title>Description</title>
 843
 844   <para>
 845    <function>SPI_prepare</function> creates and returns an execution
 846    plan for the specified command but doesn't execute the command.
 847    This function should only be called from a connected procedure.
 848   </para>
 849
 850   <para>
 851    When the same or a similar command is to be executed repeatedly, it
 852    might be advantageous to perform the planning only once.
 853    <function>SPI_prepare</function> converts a command string into an
 854    execution plan that can be executed repeatedly using
 855    <function>SPI_execute_plan</function>.
 856   </para>
 857
 858   <para>
 859    A prepared command can be generalized by writing parameters
 860    (<literal>$1</>, <literal>$2</>, etc.) in place of what would be
 861    constants in a normal command.  The actual values of the parameters
 862    are then specified when <function>SPI_execute_plan</function> is called.
 863    This allows the prepared command to be used over a wider range of
 864    situations than would be possible without parameters.
 865   </para>
 866
 867   <para>
 868    The plan returned by <function>SPI_prepare</function> can be used
 869    only in the current invocation of the procedure, since
 870    <function>SPI_finish</function> frees memory allocated for a plan.
 871    But a plan can be saved for longer using the function
 872    <function>SPI_saveplan</function>.
 873   </para>
 874  </refsect1>
 875
 876  <refsect1>
 877   <title>Arguments</title>
 878
 879   <variablelist>
 880    <varlistentry>
 881     <term><literal>const char * <parameter>command</parameter></literal></term>
 882     <listitem>
 883      <para>
 884       command string
 885      </para>
 886     </listitem>
 887    </varlistentry>
 888
 889    <varlistentry>
 890     <term><literal>int <parameter>nargs</parameter></literal></term>
 891     <listitem>
 892      <para>
 893       number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
 894      </para>
 895     </listitem>
 896    </varlistentry>
 897
 898    <varlistentry>
 899     <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
 900     <listitem>
 901      <para>
 902       pointer to an array containing the <acronym>OID</acronym>s of
 903       the data types of the parameters
 904      </para>
 905     </listitem>
 906    </varlistentry>
 907   </variablelist>
 908  </refsect1>
 909
 910  <refsect1>
 911   <title>Return Value</title>
 912
 913   <para>
 914    <function>SPI_prepare</function> returns a non-null pointer to an
 915    execution plan.  On error, <symbol>NULL</symbol> will be returned,
 916    and <varname>SPI_result</varname> will be set to one of the same
 917    error codes used by <function>SPI_execute</function>, except that
 918    it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if
 919    <parameter>command</parameter> is <symbol>NULL</symbol>, or if
 920    <parameter>nargs</> is less than 0, or if <parameter>nargs</> is
 921    greater than 0 and <parameter>argtypes</> is <symbol>NULL</symbol>.
 922   </para>
 923  </refsect1>
 924
 925  <refsect1>
 926   <title>Notes</title>
 927
 928   <para>
 929    <type>SPIPlanPtr</> is declared as a pointer to an opaque struct type in
 930    <filename>spi.h</>.  It is unwise to try to access its contents
 931    directly, as that makes your code much more likely to break in
 932    future revisions of <productname>PostgreSQL</productname>.
 933   </para>
 934
 935   <para>
 936    There is a disadvantage to using parameters: since the planner does
 937    not know the values that will be supplied for the parameters, it
 938    might make worse planning choices than it would make for a normal
 939    command with all constants visible.
 940   </para>
 941  </refsect1>
 942 </refentry>
 943
 944 <!-- *********************************************** -->
 945
 946 <refentry id="spi-spi-prepare-cursor">
 947  <refmeta>
 948   <refentrytitle>SPI_prepare_cursor</refentrytitle>
 949  </refmeta>
 950
 951  <refnamediv>
 952   <refname>SPI_prepare_cursor</refname>
 953   <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
 954  </refnamediv>
 955
 956  <indexterm><primary>SPI_prepare_cursor</primary></indexterm>
 957
 958  <refsynopsisdiv>
 959 <synopsis>
 960 SPIPlanPtr SPI_prepare_cursor(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>, int <parameter>cursorOptions</parameter>)
 961 </synopsis>
 962  </refsynopsisdiv>
 963
 964  <refsect1>
 965   <title>Description</title>
 966
 967   <para>
 968    <function>SPI_prepare_cursor</function> is identical to
 969    <function>SPI_prepare</function>, except that it also allows specification
 970    of the planner's <quote>cursor options</> parameter.  This is a bitmask
 971    having the values shown in <filename>nodes/parsenodes.h</filename>
 972    for the <structfield>options</> field of <structname>DeclareCursorStmt</>.
 973    <function>SPI_prepare</function> always takes these options as zero.
 974   </para>
 975  </refsect1>
 976
 977  <refsect1>
 978   <title>Arguments</title>
 979
 980   <variablelist>
 981    <varlistentry>
 982     <term><literal>const char * <parameter>command</parameter></literal></term>
 983     <listitem>
 984      <para>
 985       command string
 986      </para>
 987     </listitem>
 988    </varlistentry>
 989
 990    <varlistentry>
 991     <term><literal>int <parameter>nargs</parameter></literal></term>
 992     <listitem>
 993      <para>
 994       number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
 995      </para>
 996     </listitem>
 997    </varlistentry>
 998
 999    <varlistentry>
1000     <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
1001     <listitem>
1002      <para>
1003       pointer to an array containing the <acronym>OID</acronym>s of
1004       the data types of the parameters
1005      </para>
1006     </listitem>
1007    </varlistentry>
1008
1009    <varlistentry>
1010     <term><literal>int <parameter>cursorOptions</parameter></literal></term>
1011     <listitem>
1012      <para>
1013       integer bitmask of cursor options; zero produces default behavior
1014      </para>
1015     </listitem>
1016    </varlistentry>
1017   </variablelist>
1018  </refsect1>
1019
1020  <refsect1>
1021   <title>Return Value</title>
1022
1023   <para>
1024    <function>SPI_prepare_cursor</function> has the same return conventions as
1025    <function>SPI_prepare</function>.
1026   </para>
1027  </refsect1>
1028
1029  <refsect1>
1030   <title>Notes</title>
1031
1032   <para>
1033    Useful bits to set in <parameter>cursorOptions</> include
1034    <symbol>CURSOR_OPT_SCROLL</symbol>,
1035    <symbol>CURSOR_OPT_NO_SCROLL</symbol>, and
1036    <symbol>CURSOR_OPT_FAST_PLAN</symbol>.  Note in particular that
1037    <symbol>CURSOR_OPT_HOLD</symbol> is ignored.
1038   </para>
1039  </refsect1>
1040 </refentry>
1041
1042 <!-- *********************************************** -->
1043
1044 <refentry id="spi-spi-getargcount">
1045  <refmeta>
1046   <refentrytitle>SPI_getargcount</refentrytitle>
1047  </refmeta>
1048
1049  <refnamediv>
1050   <refname>SPI_getargcount</refname>
1051   <refpurpose>return the number of arguments needed by a plan
1052   prepared by <function>SPI_prepare</function></refpurpose>
1053  </refnamediv>
1054
1055  <indexterm><primary>SPI_getargcount</primary></indexterm>
1056
1057  <refsynopsisdiv>
1058 <synopsis>
1059 int SPI_getargcount(SPIPlanPtr <parameter>plan</parameter>)
1060 </synopsis>
1061  </refsynopsisdiv>
1062
1063  <refsect1>
1064   <title>Description</title>
1065
1066   <para>
1067    <function>SPI_getargcount</function> returns the number of arguments needed
1068    to execute a plan prepared by <function>SPI_prepare</function>.
1069   </para>
1070  </refsect1>
1071
1072  <refsect1>
1073   <title>Arguments</title>
1074
1075   <variablelist>
1076    <varlistentry>
1077     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1078     <listitem>
1079      <para>
1080       execution plan (returned by <function>SPI_prepare</function>)
1081      </para>
1082     </listitem>
1083    </varlistentry>
1084   </variablelist>
1085  </refsect1>
1086
1087  <refsect1>
1088   <title>Return Value</title>
1089   <para>
1090     The count of expected arguments for the <parameter>plan</parameter>.
1091     If the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1092     <varname>SPI_result</varname> is set to <symbol>SPI_ERROR_ARGUMENT</symbol>
1093     and <literal>-1</literal> is returned.
1094   </para>
1095  </refsect1>
1096 </refentry>
1097
1098 <!-- *********************************************** -->
1099
1100 <refentry id="spi-spi-getargtypeid">
1101  <refmeta>
1102   <refentrytitle>SPI_getargtypeid</refentrytitle>
1103  </refmeta>
1104
1105  <refnamediv>
1106   <refname>SPI_getargtypeid</refname>
1107   <refpurpose>return the data type OID for an argument of
1108   a plan prepared by <function>SPI_prepare</function></refpurpose>
1109  </refnamediv>
1110
1111  <indexterm><primary>SPI_getargtypeid</primary></indexterm>
1112
1113  <refsynopsisdiv>
1114 <synopsis>
1115 Oid SPI_getargtypeid(SPIPlanPtr <parameter>plan</parameter>, int <parameter>argIndex</parameter>)
1116 </synopsis>
1117  </refsynopsisdiv>
1118
1119  <refsect1>
1120   <title>Description</title>
1121
1122   <para>
1123    <function>SPI_getargtypeid</function> returns the OID representing the type
1124    id for the <parameter>argIndex</parameter>'th argument of a plan prepared by
1125    <function>SPI_prepare</function>. First argument is at index zero.
1126   </para>
1127  </refsect1>
1128
1129  <refsect1>
1130   <title>Arguments</title>
1131
1132   <variablelist>
1133    <varlistentry>
1134     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1135     <listitem>
1136      <para>
1137       execution plan (returned by <function>SPI_prepare</function>)
1138      </para>
1139     </listitem>
1140    </varlistentry>
1141
1142    <varlistentry>
1143     <term><literal>int <parameter>argIndex</parameter></literal></term>
1144     <listitem>
1145      <para>
1146       zero based index of the argument
1147      </para>
1148     </listitem>
1149    </varlistentry>
1150   </variablelist>
1151  </refsect1>
1152
1153  <refsect1>
1154   <title>Return Value</title>
1155   <para>
1156     The type id of the argument at the given index.
1157     If the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1158     or <parameter>argIndex</parameter> is less than 0 or
1159     not less than the number of arguments declared for the
1160     <parameter>plan</parameter>,
1161     <varname>SPI_result</varname> is set to <symbol>SPI_ERROR_ARGUMENT</symbol>
1162     and <symbol>InvalidOid</symbol> is returned.
1163   </para>
1164  </refsect1>
1165 </refentry>
1166
1167 <!-- *********************************************** -->
1168
1169 <refentry id="spi-spi-is-cursor-plan">
1170  <refmeta>
1171   <refentrytitle>SPI_is_cursor_plan</refentrytitle>
1172  </refmeta>
1173
1174  <refnamediv>
1175   <refname>SPI_is_cursor_plan</refname>
1176   <refpurpose>return <symbol>true</symbol> if a plan
1177   prepared by <function>SPI_prepare</function> can be used with
1178   <function>SPI_cursor_open</function></refpurpose>
1179  </refnamediv>
1180
1181  <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>
1182
1183  <refsynopsisdiv>
1184 <synopsis>
1185 bool SPI_is_cursor_plan(SPIPlanPtr <parameter>plan</parameter>)
1186 </synopsis>
1187  </refsynopsisdiv>
1188
1189  <refsect1>
1190   <title>Description</title>
1191
1192   <para>
1193    <function>SPI_is_cursor_plan</function> returns <symbol>true</symbol>
1194    if a plan prepared by <function>SPI_prepare</function> can be passed
1195    as an argument to <function>SPI_cursor_open</function>, or
1196    <symbol>false</symbol> if that is not the case. The criteria are that the
1197    <parameter>plan</parameter> represents one single command and that this
1198    command returns tuples to the caller; for example, <command>SELECT</>
1199    is allowed unless it contains an <literal>INTO</> clause, and
1200    <command>UPDATE</> is allowed only if it contains a <literal>RETURNING</>
1201    clause.
1202   </para>
1203  </refsect1>
1204
1205  <refsect1>
1206   <title>Arguments</title>
1207
1208   <variablelist>
1209    <varlistentry>
1210     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1211     <listitem>
1212      <para>
1213       execution plan (returned by <function>SPI_prepare</function>)
1214      </para>
1215     </listitem>
1216    </varlistentry>
1217   </variablelist>
1218  </refsect1>
1219
1220  <refsect1>
1221   <title>Return Value</title>
1222   <para>
1223     <symbol>true</symbol> or <symbol>false</symbol> to indicate if the
1224     <parameter>plan</parameter> can produce a cursor or not, with
1225     <varname>SPI_result</varname> set to zero.
1226     If it is not possible to determine the answer (for example,
1227     if the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1228     or if called when not connected to SPI), then
1229     <varname>SPI_result</varname> is set to a suitable error code
1230     and <symbol>false</symbol> is returned.
1231   </para>
1232  </refsect1>
1233 </refentry>
1234
1235 <!-- *********************************************** -->
1236
1237 <refentry id="spi-spi-execute-plan">
1238  <refmeta>
1239   <refentrytitle>SPI_execute_plan</refentrytitle>
1240  </refmeta>
1241
1242  <refnamediv>
1243   <refname>SPI_execute_plan</refname>
1244   <refpurpose>execute a plan prepared by <function>SPI_prepare</function></refpurpose>
1245  </refnamediv>
1246
1247  <indexterm><primary>SPI_execute_plan</primary></indexterm>
1248
1249  <refsynopsisdiv>
1250 <synopsis>
1251 int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
1252                      bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
1253 </synopsis>
1254  </refsynopsisdiv>
1255
1256  <refsect1>
1257   <title>Description</title>
1258
1259   <para>
1260    <function>SPI_execute_plan</function> executes a plan prepared by
1261    <function>SPI_prepare</function>.  <parameter>read_only</parameter> and
1262    <parameter>count</parameter> have the same interpretation as in
1263    <function>SPI_execute</function>.
1264   </para>
1265  </refsect1>
1266
1267  <refsect1>
1268   <title>Arguments</title>
1269
1270   <variablelist>
1271    <varlistentry>
1272     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1273     <listitem>
1274      <para>
1275       execution plan (returned by <function>SPI_prepare</function>)
1276      </para>
1277     </listitem>
1278    </varlistentry>
1279
1280    <varlistentry>
1281     <term><literal>Datum * <parameter>values</parameter></literal></term>
1282     <listitem>
1283      <para>
1284       An array of actual parameter values.  Must have same length as the
1285       plan's number of arguments.
1286      </para>
1287     </listitem>
1288    </varlistentry>
1289
1290    <varlistentry>
1291     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1292     <listitem>
1293      <para>
1294       An array describing which parameters are null.  Must have same length as
1295       the plan's number of arguments.
1296       <literal>n</literal> indicates a null value (entry in
1297       <parameter>values</> will be ignored); a space indicates a
1298       nonnull value (entry in <parameter>values</> is valid).
1299      </para>
1300
1301      <para>
1302       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1303       <function>SPI_execute_plan</function> assumes that no parameters are
1304       null.
1305      </para>
1306     </listitem>
1307    </varlistentry>
1308
1309    <varlistentry>
1310     <term><literal>bool <parameter>read_only</parameter></literal></term>
1311     <listitem>
1312      <para>
1313       <literal>true</> for read-only execution
1314      </para>
1315     </listitem>
1316    </varlistentry>
1317
1318    <varlistentry>
1319     <term><literal>long <parameter>count</parameter></literal></term>
1320     <listitem>
1321      <para>
1322       maximum number of rows to process or return
1323      </para>
1324     </listitem>
1325    </varlistentry>
1326   </variablelist>
1327  </refsect1>
1328
1329  <refsect1>
1330   <title>Return Value</title>
1331
1332   <para>
1333    The return value is the same as for <function>SPI_execute</function>,
1334    with the following additional possible error (negative) results:
1335
1336    <variablelist>
1337     <varlistentry>
1338      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
1339      <listitem>
1340       <para>
1341        if <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1342        or <parameter>count</parameter> is less than 0
1343       </para>
1344      </listitem>
1345     </varlistentry>
1346
1347     <varlistentry>
1348      <term><symbol>SPI_ERROR_PARAM</symbol></term>
1349      <listitem>
1350       <para>
1351        if <parameter>values</parameter> is <symbol>NULL</symbol> and
1352        <parameter>plan</parameter> was prepared with some parameters
1353       </para>
1354      </listitem>
1355     </varlistentry>
1356    </variablelist>
1357   </para>
1358
1359   <para>
1360    <varname>SPI_processed</varname> and
1361    <varname>SPI_tuptable</varname> are set as in
1362    <function>SPI_execute</function> if successful.
1363   </para>
1364  </refsect1>
1365
1366  <refsect1>
1367   <title>Notes</title>
1368
1369   <para>
1370    If one of the objects (a table, function, etc.) referenced by the
1371    prepared plan is dropped during the session then the result of
1372    <function>SPI_execute_plan</function> for this plan will be unpredictable.
1373   </para>
1374  </refsect1>
1375 </refentry>
1376
1377 <!-- *********************************************** -->
1378
1379 <refentry id="spi-spi-execp">
1380  <refmeta>
1381   <refentrytitle>SPI_execp</refentrytitle>
1382  </refmeta>
1383
1384  <refnamediv>
1385   <refname>SPI_execp</refname>
1386   <refpurpose>execute a plan in read/write mode</refpurpose>
1387  </refnamediv>
1388
1389  <indexterm><primary>SPI_execp</primary></indexterm>
1390
1391  <refsynopsisdiv>
1392 <synopsis>
1393 int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, long <parameter>count</parameter>)
1394 </synopsis>
1395  </refsynopsisdiv>
1396
1397  <refsect1>
1398   <title>Description</title>
1399
1400   <para>
1401    <function>SPI_execp</function> is the same as
1402    <function>SPI_execute_plan</function>, with the latter's
1403    <parameter>read_only</parameter> parameter always taken as
1404    <literal>false</>.
1405   </para>
1406  </refsect1>
1407
1408  <refsect1>
1409   <title>Arguments</title>
1410
1411   <variablelist>
1412    <varlistentry>
1413     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1414     <listitem>
1415      <para>
1416       execution plan (returned by <function>SPI_prepare</function>)
1417      </para>
1418     </listitem>
1419    </varlistentry>
1420
1421    <varlistentry>
1422     <term><literal>Datum * <parameter>values</parameter></literal></term>
1423     <listitem>
1424      <para>
1425       An array of actual parameter values.  Must have same length as the
1426       plan's number of arguments.
1427      </para>
1428     </listitem>
1429    </varlistentry>
1430
1431    <varlistentry>
1432     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1433     <listitem>
1434      <para>
1435       An array describing which parameters are null.  Must have same length as
1436       the plan's number of arguments.
1437       <literal>n</literal> indicates a null value (entry in
1438       <parameter>values</> will be ignored); a space indicates a
1439       nonnull value (entry in <parameter>values</> is valid).
1440      </para>
1441
1442      <para>
1443       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1444       <function>SPI_execp</function> assumes that no parameters are
1445       null.
1446      </para>
1447     </listitem>
1448    </varlistentry>
1449
1450    <varlistentry>
1451     <term><literal>long <parameter>count</parameter></literal></term>
1452     <listitem>
1453      <para>
1454       maximum number of rows to process or return
1455      </para>
1456     </listitem>
1457    </varlistentry>
1458   </variablelist>
1459  </refsect1>
1460
1461  <refsect1>
1462   <title>Return Value</title>
1463
1464   <para>
1465    See <function>SPI_execute_plan</function>.
1466   </para>
1467
1468   <para>
1469    <varname>SPI_processed</varname> and
1470    <varname>SPI_tuptable</varname> are set as in
1471    <function>SPI_execute</function> if successful.
1472   </para>
1473  </refsect1>
1474 </refentry>
1475
1476 <!-- *********************************************** -->
1477
1478 <refentry id="spi-spi-cursor-open">
1479  <refmeta>
1480   <refentrytitle>SPI_cursor_open</refentrytitle>
1481  </refmeta>
1482
1483  <refnamediv>
1484   <refname>SPI_cursor_open</refname>
1485   <refpurpose>set up a cursor using a plan created with <function>SPI_prepare</function></refpurpose>
1486  </refnamediv>
1487
1488  <indexterm><primary>SPI_cursor_open</primary></indexterm>
1489
1490  <refsynopsisdiv>
1491 <synopsis>
1492 Portal SPI_cursor_open(const char * <parameter>name</parameter>, SPIPlanPtr <parameter>plan</parameter>,
1493                        Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
1494                        bool <parameter>read_only</parameter>)
1495 </synopsis>
1496  </refsynopsisdiv>
1497
1498  <refsect1>
1499   <title>Description</title>
1500
1501   <para>
1502    <function>SPI_cursor_open</function> sets up a cursor (internally,
1503    a portal) that will execute a plan prepared by
1504    <function>SPI_prepare</function>.  The parameters have the same
1505    meanings as the corresponding parameters to
1506    <function>SPI_execute_plan</function>.
1507   </para>
1508
1509   <para>
1510    Using a cursor instead of executing the plan directly has two
1511    benefits.  First, the result rows can be retrieved a few at a time,
1512    avoiding memory overrun for queries that return many rows.  Second,
1513    a portal can outlive the current procedure (it can, in fact, live
1514    to the end of the current transaction).  Returning the portal name
1515    to the procedure's caller provides a way of returning a row set as
1516    result.
1517   </para>
1518
1519   <para>
1520    The passed-in data will be copied into the cursor's portal, so it
1521    can be freed while the cursor still exists.
1522   </para>
1523  </refsect1>
1524
1525  <refsect1>
1526   <title>Arguments</title>
1527
1528   <variablelist>
1529    <varlistentry>
1530     <term><literal>const char * <parameter>name</parameter></literal></term>
1531     <listitem>
1532      <para>
1533       name for portal, or <symbol>NULL</symbol> to let the system
1534       select a name
1535      </para>
1536     </listitem>
1537    </varlistentry>
1538
1539    <varlistentry>
1540     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1541     <listitem>
1542      <para>
1543       execution plan (returned by <function>SPI_prepare</function>)
1544      </para>
1545     </listitem>
1546    </varlistentry>
1547
1548    <varlistentry>
1549     <term><literal>Datum * <parameter>values</parameter></literal></term>
1550     <listitem>
1551      <para>
1552       An array of actual parameter values.  Must have same length as the
1553       plan's number of arguments.
1554      </para>
1555     </listitem>
1556    </varlistentry>
1557
1558    <varlistentry>
1559     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1560     <listitem>
1561      <para>
1562       An array describing which parameters are null.  Must have same length as
1563       the plan's number of arguments.
1564       <literal>n</literal> indicates a null value (entry in
1565       <parameter>values</> will be ignored); a space indicates a
1566       nonnull value (entry in <parameter>values</> is valid).
1567      </para>
1568
1569      <para>
1570       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1571       <function>SPI_cursor_open</function> assumes that no parameters are
1572       null.
1573      </para>
1574     </listitem>
1575    </varlistentry>
1576
1577    <varlistentry>
1578     <term><literal>bool <parameter>read_only</parameter></literal></term>
1579     <listitem>
1580      <para>
1581       <literal>true</> for read-only execution
1582      </para>
1583     </listitem>
1584    </varlistentry>
1585   </variablelist>
1586  </refsect1>
1587
1588  <refsect1>
1589   <title>Return Value</title>
1590
1591   <para>
1592    Pointer to portal containing the cursor.  Note there is no error
1593    return convention; any error will be reported via <function>elog</>.
1594   </para>
1595  </refsect1>
1596 </refentry>
1597
1598 <!-- *********************************************** -->
1599
1600 <refentry id="spi-spi-cursor-open-with-args">
1601  <refmeta>
1602   <refentrytitle>SPI_cursor_open_with_args</refentrytitle>
1603  </refmeta>
1604
1605  <refnamediv>
1606   <refname>SPI_cursor_open_with_args</refname>
1607   <refpurpose>set up a cursor using a query and parameters</refpurpose>
1608  </refnamediv>
1609
1610  <indexterm><primary>SPI_cursor_open_with_args</primary></indexterm>
1611
1612  <refsynopsisdiv>
1613 <synopsis>
1614 Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
1615                                  const char *<parameter>command</parameter>,
1616                                  int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
1617                                  Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
1618                                  bool <parameter>read_only</parameter>, int <parameter>cursorOptions</parameter>)
1619 </synopsis>
1620  </refsynopsisdiv>
1621
1622  <refsect1>
1623   <title>Description</title>
1624
1625   <para>
1626    <function>SPI_cursor_open_with_args</function> sets up a cursor
1627    (internally, a portal) that will execute the specified query.
1628    Most of the parameters have the same meanings as the corresponding
1629    parameters to <function>SPI_prepare_cursor</function>
1630    and <function>SPI_cursor_open</function>.
1631   </para>
1632
1633   <para>
1634    For one-time query execution, this function should be preferred
1635    over <function>SPI_prepare_cursor</function> followed by
1636    <function>SPI_cursor_open</function>.
1637    If the same command is to be executed with many different parameters,
1638    either method might be faster, depending on the cost of re-planning
1639    versus the benefit of custom plans.
1640   </para>
1641
1642   <para>
1643    The passed-in data will be copied into the cursor's portal, so it
1644    can be freed while the cursor still exists.
1645   </para>
1646  </refsect1>
1647
1648  <refsect1>
1649   <title>Arguments</title>
1650
1651   <variablelist>
1652    <varlistentry>
1653     <term><literal>const char * <parameter>name</parameter></literal></term>
1654     <listitem>
1655      <para>
1656       name for portal, or <symbol>NULL</symbol> to let the system
1657       select a name
1658      </para>
1659     </listitem>
1660    </varlistentry>
1661
1662    <varlistentry>
1663     <term><literal>const char * <parameter>command</parameter></literal></term>
1664     <listitem>
1665      <para>
1666       command string
1667      </para>
1668     </listitem>
1669    </varlistentry>
1670
1671    <varlistentry>
1672     <term><literal>int <parameter>nargs</parameter></literal></term>
1673     <listitem>
1674      <para>
1675       number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
1676      </para>
1677     </listitem>
1678    </varlistentry>
1679
1680    <varlistentry>
1681     <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
1682     <listitem>
1683      <para>
1684       an array containing the <acronym>OID</acronym>s of
1685       the data types of the parameters
1686      </para>
1687     </listitem>
1688    </varlistentry>
1689
1690    <varlistentry>
1691     <term><literal>Datum * <parameter>values</parameter></literal></term>
1692     <listitem>
1693      <para>
1694       an array of actual parameter values
1695      </para>
1696     </listitem>
1697    </varlistentry>
1698
1699    <varlistentry>
1700     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1701     <listitem>
1702      <para>
1703       an array describing which parameters are null
1704      </para>
1705
1706      <para>
1707       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1708       <function>SPI_cursor_open_with_args</function> assumes that no
1709       parameters are null.
1710      </para>
1711     </listitem>
1712    </varlistentry>
1713
1714    <varlistentry>
1715     <term><literal>bool <parameter>read_only</parameter></literal></term>
1716     <listitem>
1717      <para>
1718       <literal>true</> for read-only execution
1719      </para>
1720     </listitem>
1721    </varlistentry>
1722
1723    <varlistentry>
1724     <term><literal>int <parameter>cursorOptions</parameter></literal></term>
1725     <listitem>
1726      <para>
1727       integer bitmask of cursor options; zero produces default behavior
1728      </para>
1729     </listitem>
1730    </varlistentry>
1731   </variablelist>
1732  </refsect1>
1733
1734  <refsect1>
1735   <title>Return Value</title>
1736
1737   <para>
1738    Pointer to portal containing the cursor.  Note there is no error
1739    return convention; any error will be reported via <function>elog</>.
1740   </para>
1741  </refsect1>
1742 </refentry>
1743
1744 <!-- *********************************************** -->
1745
1746 <refentry id="spi-spi-cursor-find">
1747  <refmeta>
1748   <refentrytitle>SPI_cursor_find</refentrytitle>
1749  </refmeta>
1750
1751  <refnamediv>
1752   <refname>SPI_cursor_find</refname>
1753   <refpurpose>find an existing cursor by name</refpurpose>
1754  </refnamediv>
1755
1756  <indexterm><primary>SPI_cursor_find</primary></indexterm>
1757
1758  <refsynopsisdiv>
1759 <synopsis>
1760 Portal SPI_cursor_find(const char * <parameter>name</parameter>)
1761 </synopsis>
1762  </refsynopsisdiv>
1763
1764  <refsect1>
1765   <title>Description</title>
1766
1767   <para>
1768    <function>SPI_cursor_find</function> finds an existing portal by
1769    name.  This is primarily useful to resolve a cursor name returned
1770    as text by some other function.
1771   </para>
1772  </refsect1>
1773
1774  <refsect1>
1775   <title>Arguments</title>
1776
1777   <variablelist>
1778    <varlistentry>
1779     <term><literal>const char * <parameter>name</parameter></literal></term>
1780     <listitem>
1781      <para>
1782       name of the portal
1783      </para>
1784     </listitem>
1785    </varlistentry>
1786   </variablelist>
1787  </refsect1>
1788
1789  <refsect1>
1790   <title>Return Value</title>
1791
1792   <para>
1793    pointer to the portal with the specified name, or
1794    <symbol>NULL</symbol> if none was found
1795   </para>
1796  </refsect1>
1797 </refentry>
1798
1799 <!-- *********************************************** -->
1800
1801 <refentry id="spi-spi-cursor-fetch">
1802  <refmeta>
1803   <refentrytitle>SPI_cursor_fetch</refentrytitle>
1804  </refmeta>
1805
1806  <refnamediv>
1807   <refname>SPI_cursor_fetch</refname>
1808   <refpurpose>fetch some rows from a cursor</refpurpose>
1809  </refnamediv>
1810
1811  <indexterm><primary>SPI_cursor_fetch</primary></indexterm>
1812
1813  <refsynopsisdiv>
1814 <synopsis>
1815 void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
1816 </synopsis>
1817  </refsynopsisdiv>
1818
1819  <refsect1>
1820   <title>Description</title>
1821
1822   <para>
1823    <function>SPI_cursor_fetch</function> fetches some rows from a
1824    cursor.  This is equivalent to a subset of the SQL command
1825    <command>FETCH</> (see <function>SPI_scroll_cursor_fetch</function>
1826    for more functionality).
1827   </para>
1828  </refsect1>
1829
1830  <refsect1>
1831   <title>Arguments</title>
1832
1833   <variablelist>
1834    <varlistentry>
1835     <term><literal>Portal <parameter>portal</parameter></literal></term>
1836     <listitem>
1837      <para>
1838       portal containing the cursor
1839      </para>
1840     </listitem>
1841    </varlistentry>
1842
1843    <varlistentry>
1844     <term><literal>bool <parameter>forward</parameter></literal></term>
1845     <listitem>
1846      <para>
1847       true for fetch forward, false for fetch backward
1848      </para>
1849     </listitem>
1850    </varlistentry>
1851
1852    <varlistentry>
1853     <term><literal>long <parameter>count</parameter></literal></term>
1854     <listitem>
1855      <para>
1856       maximum number of rows to fetch
1857      </para>
1858     </listitem>
1859    </varlistentry>
1860   </variablelist>
1861  </refsect1>
1862
1863  <refsect1>
1864   <title>Return Value</title>
1865
1866   <para>
1867    <varname>SPI_processed</varname> and
1868    <varname>SPI_tuptable</varname> are set as in
1869    <function>SPI_execute</function> if successful.
1870   </para>
1871  </refsect1>
1872
1873  <refsect1>
1874   <title>Notes</title>
1875
1876   <para>
1877    Fetching backward may fail if the cursor's plan was not created
1878    with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1879   </para>
1880  </refsect1>
1881 </refentry>
1882
1883 <!-- *********************************************** -->
1884
1885 <refentry id="spi-spi-cursor-move">
1886  <refmeta>
1887   <refentrytitle>SPI_cursor_move</refentrytitle>
1888  </refmeta>
1889
1890  <refnamediv>
1891   <refname>SPI_cursor_move</refname>
1892   <refpurpose>move a cursor</refpurpose>
1893  </refnamediv>
1894
1895  <indexterm><primary>SPI_cursor_move</primary></indexterm>
1896
1897  <refsynopsisdiv>
1898 <synopsis>
1899 void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
1900 </synopsis>
1901  </refsynopsisdiv>
1902
1903  <refsect1>
1904   <title>Description</title>
1905
1906   <para>
1907    <function>SPI_cursor_move</function> skips over some number of rows
1908    in a cursor.  This is equivalent to a subset of the SQL command
1909    <command>MOVE</> (see <function>SPI_scroll_cursor_move</function>
1910    for more functionality).
1911   </para>
1912  </refsect1>
1913
1914  <refsect1>
1915   <title>Arguments</title>
1916
1917   <variablelist>
1918    <varlistentry>
1919     <term><literal>Portal <parameter>portal</parameter></literal></term>
1920     <listitem>
1921      <para>
1922       portal containing the cursor
1923      </para>
1924     </listitem>
1925    </varlistentry>
1926
1927    <varlistentry>
1928     <term><literal>bool <parameter>forward</parameter></literal></term>
1929     <listitem>
1930      <para>
1931       true for move forward, false for move backward
1932      </para>
1933     </listitem>
1934    </varlistentry>
1935
1936    <varlistentry>
1937     <term><literal>long <parameter>count</parameter></literal></term>
1938     <listitem>
1939      <para>
1940       maximum number of rows to move
1941      </para>
1942     </listitem>
1943    </varlistentry>
1944   </variablelist>
1945  </refsect1>
1946
1947  <refsect1>
1948   <title>Notes</title>
1949
1950   <para>
1951    Moving backward may fail if the cursor's plan was not created
1952    with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1953   </para>
1954  </refsect1>
1955 </refentry>
1956
1957 <!-- *********************************************** -->
1958
1959 <refentry id="spi-spi-scroll-cursor-fetch">
1960  <refmeta>
1961   <refentrytitle>SPI_scroll_cursor_fetch</refentrytitle>
1962  </refmeta>
1963
1964  <refnamediv>
1965   <refname>SPI_scroll_cursor_fetch</refname>
1966   <refpurpose>fetch some rows from a cursor</refpurpose>
1967  </refnamediv>
1968
1969  <indexterm><primary>SPI_scroll_cursor_fetch</primary></indexterm>
1970
1971  <refsynopsisdiv>
1972 <synopsis>
1973 void SPI_scroll_cursor_fetch(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
1974 </synopsis>
1975  </refsynopsisdiv>
1976
1977  <refsect1>
1978   <title>Description</title>
1979
1980   <para>
1981    <function>SPI_scroll_cursor_fetch</function> fetches some rows from a
1982    cursor.  This is equivalent to the SQL command <command>FETCH</>.
1983   </para>
1984  </refsect1>
1985
1986  <refsect1>
1987   <title>Arguments</title>
1988
1989   <variablelist>
1990    <varlistentry>
1991     <term><literal>Portal <parameter>portal</parameter></literal></term>
1992     <listitem>
1993      <para>
1994       portal containing the cursor
1995      </para>
1996     </listitem>
1997    </varlistentry>
1998
1999    <varlistentry>
2000     <term><literal>FetchDirection <parameter>direction</parameter></literal></term>
2001     <listitem>
2002      <para>
2003       one of <symbol>FETCH_FORWARD</symbol>,
2004       <symbol>FETCH_BACKWARD</symbol>,
2005       <symbol>FETCH_ABSOLUTE</symbol> or
2006       <symbol>FETCH_RELATIVE</symbol>
2007      </para>
2008     </listitem>
2009    </varlistentry>
2010
2011    <varlistentry>
2012     <term><literal>long <parameter>count</parameter></literal></term>
2013     <listitem>
2014      <para>
2015       number of rows to fetch for
2016       <symbol>FETCH_FORWARD</symbol> or
2017       <symbol>FETCH_BACKWARD</symbol>; absolute row number to fetch for
2018       <symbol>FETCH_ABSOLUTE</symbol>; or relative row number to fetch for
2019       <symbol>FETCH_RELATIVE</symbol>
2020      </para>
2021     </listitem>
2022    </varlistentry>
2023   </variablelist>
2024  </refsect1>
2025
2026  <refsect1>
2027   <title>Return Value</title>
2028
2029   <para>
2030    <varname>SPI_processed</varname> and
2031    <varname>SPI_tuptable</varname> are set as in
2032    <function>SPI_execute</function> if successful.
2033   </para>
2034  </refsect1>
2035
2036  <refsect1>
2037   <title>Notes</title>
2038
2039   <para>
2040    See the SQL <xref linkend="sql-fetch" endterm="sql-fetch-title"> command
2041    for details of the interpretation of the
2042    <parameter>direction</parameter> and
2043    <parameter>count</parameter> parameters.
2044   </para>
2045
2046   <para>
2047    Direction values other than <symbol>FETCH_FORWARD</symbol>
2048    may fail if the cursor's plan was not created
2049    with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
2050   </para>
2051  </refsect1>
2052 </refentry>
2053
2054 <!-- *********************************************** -->
2055
2056 <refentry id="spi-spi-scroll-cursor-move">
2057  <refmeta>
2058   <refentrytitle>SPI_scroll_cursor_move</refentrytitle>
2059  </refmeta>
2060
2061  <refnamediv>
2062   <refname>SPI_scroll_cursor_move</refname>
2063   <refpurpose>move a cursor</refpurpose>
2064  </refnamediv>
2065
2066  <indexterm><primary>SPI_scroll_cursor_move</primary></indexterm>
2067
2068  <refsynopsisdiv>
2069 <synopsis>
2070 void SPI_scroll_cursor_move(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
2071 </synopsis>
2072  </refsynopsisdiv>
2073
2074  <refsect1>
2075   <title>Description</title>
2076
2077   <para>
2078    <function>SPI_scroll_cursor_move</function> skips over some number of rows
2079    in a cursor.  This is equivalent to the SQL command
2080    <command>MOVE</>.
2081   </para>
2082  </refsect1>
2083
2084  <refsect1>
2085   <title>Arguments</title>
2086
2087   <variablelist>
2088    <varlistentry>
2089     <term><literal>Portal <parameter>portal</parameter></literal></term>
2090     <listitem>
2091      <para>
2092       portal containing the cursor
2093      </para>
2094     </listitem>
2095    </varlistentry>
2096
2097    <varlistentry>
2098     <term><literal>FetchDirection <parameter>direction</parameter></literal></term>
2099     <listitem>
2100      <para>
2101       one of <symbol>FETCH_FORWARD</symbol>,
2102       <symbol>FETCH_BACKWARD</symbol>,
2103       <symbol>FETCH_ABSOLUTE</symbol> or
2104       <symbol>FETCH_RELATIVE</symbol>
2105      </para>
2106     </listitem>
2107    </varlistentry>
2108
2109    <varlistentry>
2110     <term><literal>long <parameter>count</parameter></literal></term>
2111     <listitem>
2112      <para>
2113       number of rows to move for
2114       <symbol>FETCH_FORWARD</symbol> or
2115       <symbol>FETCH_BACKWARD</symbol>; absolute row number to move to for
2116       <symbol>FETCH_ABSOLUTE</symbol>; or relative row number to move to for
2117       <symbol>FETCH_RELATIVE</symbol>
2118      </para>
2119     </listitem>
2120    </varlistentry>
2121   </variablelist>
2122  </refsect1>
2123
2124  <refsect1>
2125   <title>Return Value</title>
2126
2127   <para>
2128    <varname>SPI_processed</varname> is set as in
2129    <function>SPI_execute</function> if successful.
2130    <varname>SPI_tuptable</varname> is set to <symbol>NULL</>, since
2131    no rows are returned by this function.
2132   </para>
2133  </refsect1>
2134
2135  <refsect1>
2136   <title>Notes</title>
2137
2138   <para>
2139    See the SQL <xref linkend="sql-fetch" endterm="sql-fetch-title"> command
2140    for details of the interpretation of the
2141    <parameter>direction</parameter> and
2142    <parameter>count</parameter> parameters.
2143   </para>
2144
2145   <para>
2146    Direction values other than <symbol>FETCH_FORWARD</symbol>
2147    may fail if the cursor's plan was not created
2148    with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
2149   </para>
2150  </refsect1>
2151 </refentry>
2152
2153 <!-- *********************************************** -->
2154
2155 <refentry id="spi-spi-cursor-close">
2156  <refmeta>
2157   <refentrytitle>SPI_cursor_close</refentrytitle>
2158  </refmeta>
2159
2160  <refnamediv>
2161   <refname>SPI_cursor_close</refname>
2162   <refpurpose>close a cursor</refpurpose>
2163  </refnamediv>
2164
2165  <indexterm><primary>SPI_cursor_close</primary></indexterm>
2166
2167  <refsynopsisdiv>
2168 <synopsis>
2169 void SPI_cursor_close(Portal <parameter>portal</parameter>)
2170 </synopsis>
2171  </refsynopsisdiv>
2172
2173  <refsect1>
2174   <title>Description</title>
2175
2176   <para>
2177    <function>SPI_cursor_close</function> closes a previously created
2178    cursor and releases its portal storage.
2179   </para>
2180
2181   <para>
2182    All open cursors are closed automatically at the end of a
2183    transaction.  <function>SPI_cursor_close</function> need only be
2184    invoked if it is desirable to release resources sooner.
2185   </para>
2186  </refsect1>
2187
2188  <refsect1>
2189   <title>Arguments</title>
2190
2191   <variablelist>
2192    <varlistentry>
2193     <term><literal>Portal <parameter>portal</parameter></literal></term>
2194     <listitem>
2195      <para>
2196       portal containing the cursor
2197      </para>
2198     </listitem>
2199    </varlistentry>
2200   </variablelist>
2201  </refsect1>
2202 </refentry>
2203
2204 <!-- *********************************************** -->
2205
2206 <refentry id="spi-spi-saveplan">
2207  <refmeta>
2208   <refentrytitle>SPI_saveplan</refentrytitle>
2209  </refmeta>
2210
2211  <refnamediv>
2212   <refname>SPI_saveplan</refname>
2213   <refpurpose>save a plan</refpurpose>
2214  </refnamediv>
2215
2216  <indexterm><primary>SPI_saveplan</primary></indexterm>
2217
2218  <refsynopsisdiv>
2219 <synopsis>
2220 SPIPlanPtr SPI_saveplan(SPIPlanPtr <parameter>plan</parameter>)
2221 </synopsis>
2222  </refsynopsisdiv>
2223
2224  <refsect1>
2225   <title>Description</title>
2226
2227   <para>
2228    <function>SPI_saveplan</function> saves a passed plan (prepared by
2229    <function>SPI_prepare</function>) in memory that will not be freed
2230    by <function>SPI_finish</function> nor by the transaction manager,
2231    and returns a pointer to the saved plan.  This gives you the
2232    ability to reuse prepared plans in the subsequent invocations of
2233    your procedure in the current session.
2234   </para>
2235  </refsect1>
2236
2237  <refsect1>
2238   <title>Arguments</title>
2239
2240   <variablelist>
2241    <varlistentry>
2242     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
2243     <listitem>
2244      <para>
2245       the plan to be saved
2246      </para>
2247     </listitem>
2248    </varlistentry>
2249   </variablelist>
2250  </refsect1>
2251
2252  <refsect1>
2253   <title>Return Value</title>
2254
2255   <para>
2256    Pointer to the saved plan; <symbol>NULL</symbol> if unsuccessful.
2257    On error, <varname>SPI_result</varname> is set thus:
2258
2259    <variablelist>
2260     <varlistentry>
2261      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
2262      <listitem>
2263       <para>
2264        if <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid
2265       </para>
2266      </listitem>
2267     </varlistentry>
2268
2269     <varlistentry>
2270      <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
2271      <listitem>
2272       <para>
2273        if called from an unconnected procedure
2274       </para>
2275      </listitem>
2276     </varlistentry>
2277    </variablelist>
2278   </para>
2279  </refsect1>
2280
2281  <refsect1>
2282   <title>Notes</title>
2283
2284   <para>
2285    The passed-in plan is not freed, so you might wish to do
2286    <function>SPI_freeplan</function> on it to avoid leaking memory
2287    until <function>SPI_finish</>.
2288   </para>
2289
2290   <para>
2291    If one of the objects (a table, function, etc.) referenced by the
2292    prepared plan is dropped or redefined, then future executions of
2293    <function>SPI_execute_plan</function> may fail or return different
2294    results than the plan initially indicates.
2295   </para>
2296  </refsect1>
2297 </refentry>
2298
2299 </sect1>
2300
2301 <sect1 id="spi-interface-support">
2302  <title>Interface Support Functions</title>
2303
2304  <para>
2305   The functions described here provide an interface for extracting
2306   information from result sets returned by <function>SPI_execute</> and
2307   other SPI functions.
2308  </para>
2309
2310  <para>
2311   All functions described in this section can be used by both
2312   connected and unconnected procedures.
2313  </para>
2314
2315 <!-- *********************************************** -->
2316
2317 <refentry id="spi-spi-fname">
2318  <refmeta>
2319   <refentrytitle>SPI_fname</refentrytitle>
2320  </refmeta>
2321
2322  <refnamediv>
2323   <refname>SPI_fname</refname>
2324   <refpurpose>determine the column name for the specified column number</refpurpose>
2325  </refnamediv>
2326
2327  <indexterm><primary>SPI_fname</primary></indexterm>
2328
2329  <refsynopsisdiv>
2330 <synopsis>
2331 char * SPI_fname(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2332 </synopsis>
2333  </refsynopsisdiv>
2334
2335  <refsect1>
2336   <title>Description</title>
2337
2338   <para>
2339    <function>SPI_fname</function> returns a copy of the column name of the
2340    specified column.  (You can use <function>pfree</function> to
2341    release the copy of the name when you don't need it anymore.)
2342   </para>
2343  </refsect1>
2344
2345  <refsect1>
2346   <title>Arguments</title>
2347
2348   <variablelist>
2349    <varlistentry>
2350     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2351     <listitem>
2352      <para>
2353       input row description
2354      </para>
2355     </listitem>
2356    </varlistentry>
2357
2358    <varlistentry>
2359     <term><literal>int <parameter>colnumber</parameter></literal></term>
2360     <listitem>
2361      <para>
2362       column number (count starts at 1)
2363      </para>
2364     </listitem>
2365    </varlistentry>
2366   </variablelist>
2367  </refsect1>
2368
2369  <refsect1>
2370   <title>Return Value</title>
2371
2372   <para>
2373    The column name; <symbol>NULL</symbol> if
2374    <parameter>colnumber</parameter> is out of range.
2375    <varname>SPI_result</varname> set to
2376    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2377   </para>
2378  </refsect1>
2379 </refentry>
2380
2381 <!-- *********************************************** -->
2382
2383 <refentry id="spi-spi-fnumber">
2384  <refmeta>
2385   <refentrytitle>SPI_fnumber</refentrytitle>
2386  </refmeta>
2387
2388  <refnamediv>
2389   <refname>SPI_fnumber</refname>
2390   <refpurpose>determine the column number for the specified column name</refpurpose>
2391  </refnamediv>
2392
2393  <indexterm><primary>SPI_fnumber</primary></indexterm>
2394
2395  <refsynopsisdiv>
2396 <synopsis>
2397 int SPI_fnumber(TupleDesc <parameter>rowdesc</parameter>, const char * <parameter>colname</parameter>)
2398 </synopsis>
2399  </refsynopsisdiv>
2400
2401  <refsect1>
2402   <title>Description</title>
2403
2404   <para>
2405    <function>SPI_fnumber</function> returns the column number for the
2406    column with the specified name.
2407   </para>
2408
2409   <para>
2410    If <parameter>colname</parameter> refers to a system column (e.g.,
2411    <literal>oid</>) then the appropriate negative column number will
2412    be returned.  The caller should be careful to test the return value
2413    for exact equality to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> to
2414    detect an error; testing the result for less than or equal to 0 is
2415    not correct unless system columns should be rejected.
2416   </para>
2417  </refsect1>
2418
2419  <refsect1>
2420   <title>Arguments</title>
2421
2422   <variablelist>
2423    <varlistentry>
2424     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2425     <listitem>
2426      <para>
2427       input row description
2428      </para>
2429     </listitem>
2430    </varlistentry>
2431
2432    <varlistentry>
2433     <term><literal>const char * <parameter>colname</parameter></literal></term>
2434     <listitem>
2435      <para>
2436       column name
2437      </para>
2438     </listitem>
2439    </varlistentry>
2440   </variablelist>
2441  </refsect1>
2442
2443  <refsect1>
2444   <title>Return Value</title>
2445
2446   <para>
2447    Column number (count starts at 1), or
2448    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> if the named column was not
2449    found.
2450   </para>
2451  </refsect1>
2452 </refentry>
2453
2454 <!-- *********************************************** -->
2455
2456 <refentry id="spi-spi-getvalue">
2457  <refmeta>
2458   <refentrytitle>SPI_getvalue</refentrytitle>
2459  </refmeta>
2460
2461  <refnamediv>
2462   <refname>SPI_getvalue</refname>
2463   <refpurpose>return the string value of the specified column</refpurpose>
2464  </refnamediv>
2465
2466  <indexterm><primary>SPI_getvalue</primary></indexterm>
2467
2468  <refsynopsisdiv>
2469 <synopsis>
2470 char * SPI_getvalue(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2471 </synopsis>
2472  </refsynopsisdiv>
2473
2474  <refsect1>
2475   <title>Description</title>
2476
2477   <para>
2478    <function>SPI_getvalue</function> returns the string representation
2479    of the value of the specified column.
2480   </para>
2481
2482   <para>
2483    The result is returned in memory allocated using
2484    <function>palloc</function>.  (You can use
2485    <function>pfree</function> to release the memory when you don't
2486    need it anymore.)
2487   </para>
2488  </refsect1>
2489
2490  <refsect1>
2491   <title>Arguments</title>
2492
2493   <variablelist>
2494    <varlistentry>
2495     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2496     <listitem>
2497      <para>
2498       input row to be examined
2499      </para>
2500     </listitem>
2501    </varlistentry>
2502
2503    <varlistentry>
2504     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2505     <listitem>
2506      <para>
2507       input row description
2508      </para>
2509     </listitem>
2510    </varlistentry>
2511
2512    <varlistentry>
2513     <term><literal>int <parameter>colnumber</parameter></literal></term>
2514     <listitem>
2515      <para>
2516       column number (count starts at 1)
2517      </para>
2518     </listitem>
2519    </varlistentry>
2520   </variablelist>
2521  </refsect1>
2522
2523  <refsect1>
2524   <title>Return Value</title>
2525
2526   <para>
2527    Column value, or <symbol>NULL</symbol> if the column is null,
2528    <parameter>colnumber</parameter> is out of range
2529    (<varname>SPI_result</varname> is set to
2530    <symbol>SPI_ERROR_NOATTRIBUTE</symbol>), or no output function is
2531    available (<varname>SPI_result</varname> is set to
2532    <symbol>SPI_ERROR_NOOUTFUNC</symbol>).
2533   </para>
2534  </refsect1>
2535 </refentry>
2536
2537 <!-- *********************************************** -->
2538
2539 <refentry id="spi-spi-getbinval">
2540  <refmeta>
2541   <refentrytitle>SPI_getbinval</refentrytitle>
2542  </refmeta>
2543
2544  <refnamediv>
2545   <refname>SPI_getbinval</refname>
2546   <refpurpose>return the binary value of the specified column</refpurpose>
2547  </refnamediv>
2548
2549  <indexterm><primary>SPI_getbinval</primary></indexterm>
2550
2551  <refsynopsisdiv>
2552 <synopsis>
2553 Datum SPI_getbinval(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>, bool * <parameter>isnull</parameter>)
2554 </synopsis>
2555  </refsynopsisdiv>
2556
2557  <refsect1>
2558   <title>Description</title>
2559
2560   <para>
2561    <function>SPI_getbinval</function> returns the value of the
2562    specified column in the internal form (as type <type>Datum</type>).
2563   </para>
2564
2565   <para>
2566    This function does not allocate new space for the datum.  In the
2567    case of a pass-by-reference data type, the return value will be a
2568    pointer into the passed row.
2569   </para>
2570  </refsect1>
2571
2572  <refsect1>
2573   <title>Arguments</title>
2574
2575   <variablelist>
2576    <varlistentry>
2577     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2578     <listitem>
2579      <para>
2580       input row to be examined
2581      </para>
2582     </listitem>
2583    </varlistentry>
2584
2585    <varlistentry>
2586     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2587     <listitem>
2588      <para>
2589       input row description
2590      </para>
2591     </listitem>
2592    </varlistentry>
2593
2594    <varlistentry>
2595     <term><literal>int <parameter>colnumber</parameter></literal></term>
2596     <listitem>
2597      <para>
2598       column number (count starts at 1)
2599      </para>
2600     </listitem>
2601    </varlistentry>
2602
2603    <varlistentry>
2604     <term><literal>bool * <parameter>isnull</parameter></literal></term>
2605     <listitem>
2606      <para>
2607       flag for a null value in the column
2608      </para>
2609     </listitem>
2610    </varlistentry>
2611   </variablelist>
2612  </refsect1>
2613
2614  <refsect1>
2615   <title>Return Value</title>
2616
2617   <para>
2618    The binary value of the column is returned.  The variable pointed
2619    to by <parameter>isnull</parameter> is set to true if the column is
2620    null, else to false.
2621   </para>
2622
2623   <para>
2624    <varname>SPI_result</varname> is set to
2625    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2626   </para>
2627  </refsect1>
2628 </refentry>
2629
2630 <!-- *********************************************** -->
2631
2632 <refentry id="spi-spi-gettype">
2633  <refmeta>
2634   <refentrytitle>SPI_gettype</refentrytitle>
2635  </refmeta>
2636
2637  <refnamediv>
2638   <refname>SPI_gettype</refname>
2639   <refpurpose>return the data type name of the specified column</refpurpose>
2640  </refnamediv>
2641
2642  <indexterm><primary>SPI_gettype</primary></indexterm>
2643
2644  <refsynopsisdiv>
2645 <synopsis>
2646 char * SPI_gettype(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2647 </synopsis>
2648  </refsynopsisdiv>
2649
2650  <refsect1>
2651   <title>Description</title>
2652
2653   <para>
2654    <function>SPI_gettype</function> returns a copy of the data type name of the
2655    specified column.  (You can use <function>pfree</function> to
2656    release the copy of the name when you don't need it anymore.)
2657   </para>
2658  </refsect1>
2659
2660  <refsect1>
2661   <title>Arguments</title>
2662
2663   <variablelist>
2664    <varlistentry>
2665     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2666     <listitem>
2667      <para>
2668       input row description
2669      </para>
2670     </listitem>
2671    </varlistentry>
2672
2673    <varlistentry>
2674     <term><literal>int <parameter>colnumber</parameter></literal></term>
2675     <listitem>
2676      <para>
2677       column number (count starts at 1)
2678      </para>
2679     </listitem>
2680    </varlistentry>
2681   </variablelist>
2682  </refsect1>
2683
2684  <refsect1>
2685   <title>Return Value</title>
2686
2687   <para>
2688    The data type name of the specified column, or
2689    <symbol>NULL</symbol> on error.  <varname>SPI_result</varname> is
2690    set to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2691   </para>
2692  </refsect1>
2693 </refentry>
2694
2695 <!-- *********************************************** -->
2696
2697 <refentry id="spi-spi-gettypeid">
2698  <refmeta>
2699   <refentrytitle>SPI_gettypeid</refentrytitle>
2700  </refmeta>
2701
2702  <refnamediv>
2703   <refname>SPI_gettypeid</refname>
2704   <refpurpose>return the data type <acronym>OID</acronym> of the specified column</refpurpose>
2705  </refnamediv>
2706
2707  <indexterm><primary>SPI_gettypeid</primary></indexterm>
2708
2709  <refsynopsisdiv>
2710 <synopsis>
2711 Oid SPI_gettypeid(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2712 </synopsis>
2713  </refsynopsisdiv>
2714
2715  <refsect1>
2716   <title>Description</title>
2717
2718   <para>
2719    <function>SPI_gettypeid</function> returns the
2720    <acronym>OID</acronym> of the data type of the specified column.
2721   </para>
2722  </refsect1>
2723
2724  <refsect1>
2725   <title>Arguments</title>
2726
2727   <variablelist>
2728    <varlistentry>
2729     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2730     <listitem>
2731      <para>
2732       input row description
2733      </para>
2734     </listitem>
2735    </varlistentry>
2736
2737    <varlistentry>
2738     <term><literal>int <parameter>colnumber</parameter></literal></term>
2739     <listitem>
2740      <para>
2741       column number (count starts at 1)
2742      </para>
2743     </listitem>
2744    </varlistentry>
2745   </variablelist>
2746  </refsect1>
2747
2748  <refsect1>
2749   <title>Return Value</title>
2750
2751   <para>
2752    The <acronym>OID</acronym> of the data type of the specified column
2753    or <symbol>InvalidOid</symbol> on error.  On error,
2754    <varname>SPI_result</varname> is set to
2755    <symbol>SPI_ERROR_NOATTRIBUTE</symbol>.
2756   </para>
2757  </refsect1>
2758 </refentry>
2759
2760 <!-- *********************************************** -->
2761
2762 <refentry id="spi-spi-getrelname">
2763  <refmeta>
2764   <refentrytitle>SPI_getrelname</refentrytitle>
2765  </refmeta>
2766
2767  <refnamediv>
2768   <refname>SPI_getrelname</refname>
2769   <refpurpose>return the name of the specified relation</refpurpose>
2770  </refnamediv>
2771
2772  <indexterm><primary>SPI_getrelname</primary></indexterm>
2773
2774  <refsynopsisdiv>
2775 <synopsis>
2776 char * SPI_getrelname(Relation <parameter>rel</parameter>)
2777 </synopsis>
2778  </refsynopsisdiv>
2779
2780  <refsect1>
2781   <title>Description</title>
2782
2783   <para>
2784    <function>SPI_getrelname</function> returns a copy of the name of the
2785    specified relation.  (You can use <function>pfree</function> to
2786    release the copy of the name when you don't need it anymore.)
2787   </para>
2788  </refsect1>
2789
2790  <refsect1>
2791   <title>Arguments</title>
2792
2793   <variablelist>
2794    <varlistentry>
2795     <term><literal>Relation <parameter>rel</parameter></literal></term>
2796     <listitem>
2797      <para>
2798       input relation
2799      </para>
2800     </listitem>
2801    </varlistentry>
2802   </variablelist>
2803  </refsect1>
2804
2805  <refsect1>
2806   <title>Return Value</title>
2807
2808   <para>
2809    The name of the specified relation.
2810   </para>
2811  </refsect1>
2812 </refentry>
2813
2814 <refentry id="spi-spi-getnspname">
2815  <refmeta>
2816   <refentrytitle>SPI_getnspname</refentrytitle>
2817  </refmeta>
2818
2819  <refnamediv>
2820   <refname>SPI_getnspname</refname>
2821   <refpurpose>return the namespace of the specified relation</refpurpose>
2822  </refnamediv>
2823
2824  <indexterm><primary>SPI_getnspname</primary></indexterm>
2825
2826  <refsynopsisdiv>
2827 <synopsis>
2828 char * SPI_getnspname(Relation <parameter>rel</parameter>)
2829 </synopsis>
2830  </refsynopsisdiv>
2831
2832  <refsect1>
2833   <title>Description</title>
2834
2835   <para>
2836    <function>SPI_getnspname</function> returns a copy of the name of
2837    the namespace that the specified <structname>Relation</structname>
2838    belongs to. This is equivalent to the relation's schema. You should
2839    <function>pfree</function> the return value of this function when
2840    you are finished with it.
2841   </para>
2842  </refsect1>
2843
2844  <refsect1>
2845   <title>Arguments</title>
2846
2847   <variablelist>
2848    <varlistentry>
2849     <term><literal>Relation <parameter>rel</parameter></literal></term>
2850     <listitem>
2851      <para>
2852       input relation
2853      </para>
2854     </listitem>
2855    </varlistentry>
2856   </variablelist>
2857  </refsect1>
2858
2859  <refsect1>
2860   <title>Return Value</title>
2861
2862   <para>
2863    The name of the specified relation's namespace.
2864   </para>
2865  </refsect1>
2866 </refentry>
2867
2868  </sect1>
2869
2870  <sect1 id="spi-memory">
2871   <title>Memory Management</title>
2872
2873   <para>
2874    <productname>PostgreSQL</productname> allocates memory within
2875    <firstterm>memory contexts</firstterm><indexterm><primary>memory
2876    context</primary><secondary>in SPI</secondary></indexterm>, which provide a convenient method of
2877    managing allocations made in many different places that need to
2878    live for differing amounts of time.  Destroying a context releases
2879    all the memory that was allocated in it.  Thus, it is not necessary
2880    to keep track of individual objects to avoid memory leaks; instead
2881    only a relatively small number of contexts have to be managed.
2882    <function>palloc</function> and related functions allocate memory
2883    from the <quote>current</> context.
2884   </para>
2885
2886   <para>
2887    <function>SPI_connect</function> creates a new memory context and
2888    makes it current.  <function>SPI_finish</function> restores the
2889    previous current memory context and destroys the context created by
2890    <function>SPI_connect</function>.  These actions ensure that
2891    transient memory allocations made inside your procedure are
2892    reclaimed at procedure exit, avoiding memory leakage.
2893   </para>
2894
2895   <para>
2896    However, if your procedure needs to return an object in allocated
2897    memory (such as a value of a pass-by-reference data type), you
2898    cannot allocate that memory using <function>palloc</function>, at
2899    least not while you are connected to SPI.  If you try, the object
2900    will be deallocated by <function>SPI_finish</function>, and your
2901    procedure will not work reliably.  To solve this problem, use
2902    <function>SPI_palloc</function> to allocate memory for your return
2903    object.  <function>SPI_palloc</function> allocates memory in the
2904    <quote>upper executor context</quote>, that is, the memory context
2905    that was current when <function>SPI_connect</function> was called,
2906    which is precisely the right context for a value returned from your
2907    procedure.
2908   </para>
2909
2910   <para>
2911    If <function>SPI_palloc</function> is called while the procedure is
2912    not connected to SPI, then it acts the same as a normal
2913    <function>palloc</function>.  Before a procedure connects to the
2914    SPI manager, the current memory context is the upper executor
2915    context, so all allocations made by the procedure via
2916    <function>palloc</function> or by SPI utility functions are made in
2917    this context.
2918   </para>
2919
2920   <para>
2921    When <function>SPI_connect</function> is called, the private
2922    context of the procedure, which is created by
2923    <function>SPI_connect</function>, is made the current context.  All
2924    allocations made by <function>palloc</function>,
2925    <function>repalloc</function>, or SPI utility functions (except for
2926    <function>SPI_copytuple</function>,
2927    <function>SPI_returntuple</function>,
2928    <function>SPI_modifytuple</function>, and
2929    <function>SPI_palloc</function>) are made in this context.  When a
2930    procedure disconnects from the SPI manager (via
2931    <function>SPI_finish</function>) the current context is restored to
2932    the upper executor context, and all allocations made in the
2933    procedure memory context are freed and cannot be used any more.
2934   </para>
2935
2936   <para>
2937    All functions described in this section can be used by both
2938    connected and unconnected procedures.  In an unconnected procedure,
2939    they act the same as the underlying ordinary server functions
2940    (<function>palloc</>, etc.).
2941   </para>
2942
2943 <!-- *********************************************** -->
2944
2945 <refentry id="spi-spi-palloc">
2946  <refmeta>
2947   <refentrytitle>SPI_palloc</refentrytitle>
2948  </refmeta>
2949
2950  <refnamediv>
2951   <refname>SPI_palloc</refname>
2952   <refpurpose>allocate memory in the upper executor context</refpurpose>
2953  </refnamediv>
2954
2955  <indexterm><primary>SPI_palloc</primary></indexterm>
2956
2957  <refsynopsisdiv>
2958 <synopsis>
2959 void * SPI_palloc(Size <parameter>size</parameter>)
2960 </synopsis>
2961  </refsynopsisdiv>
2962
2963  <refsect1>
2964   <title>Description</title>
2965
2966   <para>
2967    <function>SPI_palloc</function> allocates memory in the upper
2968    executor context.
2969   </para>
2970  </refsect1>
2971
2972  <refsect1>
2973   <title>Arguments</title>
2974
2975   <variablelist>
2976    <varlistentry>
2977     <term><literal>Size <parameter>size</parameter></literal></term>
2978     <listitem>
2979      <para>
2980       size in bytes of storage to allocate
2981      </para>
2982     </listitem>
2983    </varlistentry>
2984   </variablelist>
2985  </refsect1>
2986
2987  <refsect1>
2988   <title>Return Value</title>
2989
2990   <para>
2991    pointer to new storage space of the specified size
2992   </para>
2993  </refsect1>
2994 </refentry>
2995
2996 <!-- *********************************************** -->
2997
2998 <refentry id="spi-realloc">
2999  <refmeta>
3000   <refentrytitle>SPI_repalloc</refentrytitle>
3001  </refmeta>
3002
3003  <refnamediv>
3004   <refname>SPI_repalloc</refname>
3005   <refpurpose>reallocate memory in the upper executor context</refpurpose>
3006  </refnamediv>
3007
3008  <indexterm><primary>SPI_repalloc</primary></indexterm>
3009
3010  <refsynopsisdiv>
3011 <synopsis>
3012 void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)
3013 </synopsis>
3014  </refsynopsisdiv>
3015
3016  <refsect1>
3017   <title>Description</title>
3018
3019   <para>
3020    <function>SPI_repalloc</function> changes the size of a memory
3021    segment previously allocated using <function>SPI_palloc</function>.
3022   </para>
3023
3024   <para>
3025    This function is no longer different from plain
3026    <function>repalloc</function>.  It's kept just for backward
3027    compatibility of existing code.
3028   </para>
3029  </refsect1>
3030
3031  <refsect1>
3032   <title>Arguments</title>
3033
3034   <variablelist>
3035    <varlistentry>
3036     <term><literal>void * <parameter>pointer</parameter></literal></term>
3037     <listitem>
3038      <para>
3039       pointer to existing storage to change
3040      </para>
3041     </listitem>
3042    </varlistentry>
3043
3044    <varlistentry>
3045     <term><literal>Size <parameter>size</parameter></literal></term>
3046     <listitem>
3047      <para>
3048       size in bytes of storage to allocate
3049      </para>
3050     </listitem>
3051    </varlistentry>
3052   </variablelist>
3053  </refsect1>
3054
3055  <refsect1>
3056   <title>Return Value</title>
3057
3058   <para>
3059    pointer to new storage space of specified size with the contents
3060    copied from the existing area
3061   </para>
3062  </refsect1>
3063 </refentry>
3064
3065 <!-- *********************************************** -->
3066
3067 <refentry id="spi-spi-pfree">
3068  <refmeta>
3069   <refentrytitle>SPI_pfree</refentrytitle>
3070  </refmeta>
3071
3072  <refnamediv>
3073   <refname>SPI_pfree</refname>
3074   <refpurpose>free memory in the upper executor context</refpurpose>
3075  </refnamediv>
3076
3077  <indexterm><primary>SPI_pfree</primary></indexterm>
3078
3079  <refsynopsisdiv>
3080 <synopsis>
3081 void SPI_pfree(void * <parameter>pointer</parameter>)
3082 </synopsis>
3083  </refsynopsisdiv>
3084
3085  <refsect1>
3086   <title>Description</title>
3087
3088   <para>
3089    <function>SPI_pfree</function> frees memory previously allocated
3090    using <function>SPI_palloc</function> or
3091    <function>SPI_repalloc</function>.
3092   </para>
3093
3094   <para>
3095    This function is no longer different from plain
3096    <function>pfree</function>.  It's kept just for backward
3097    compatibility of existing code.
3098   </para>
3099  </refsect1>
3100
3101  <refsect1>
3102   <title>Arguments</title>
3103
3104   <variablelist>
3105    <varlistentry>
3106     <term><literal>void * <parameter>pointer</parameter></literal></term>
3107     <listitem>
3108      <para>
3109       pointer to existing storage to free
3110      </para>
3111     </listitem>
3112    </varlistentry>
3113   </variablelist>
3114  </refsect1>
3115 </refentry>
3116
3117 <!-- *********************************************** -->
3118
3119 <refentry id="spi-spi-copytuple">
3120  <refmeta>
3121   <refentrytitle>SPI_copytuple</refentrytitle>
3122  </refmeta>
3123
3124  <refnamediv>
3125   <refname>SPI_copytuple</refname>
3126   <refpurpose>make a copy of a row in the upper executor context</refpurpose>
3127  </refnamediv>
3128
3129  <indexterm><primary>SPI_copytuple</primary></indexterm>
3130
3131  <refsynopsisdiv>
3132 <synopsis>
3133 HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>)
3134 </synopsis>
3135  </refsynopsisdiv>
3136
3137  <refsect1>
3138   <title>Description</title>
3139
3140   <para>
3141    <function>SPI_copytuple</function> makes a copy of a row in the
3142    upper executor context.  This is normally used to return a modified
3143    row from a trigger.  In a function declared to return a composite
3144    type, use <function>SPI_returntuple</function> instead.
3145   </para>
3146  </refsect1>
3147
3148  <refsect1>
3149   <title>Arguments</title>
3150
3151   <variablelist>
3152    <varlistentry>
3153     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3154     <listitem>
3155      <para>
3156       row to be copied
3157      </para>
3158     </listitem>
3159    </varlistentry>
3160   </variablelist>
3161  </refsect1>
3162
3163  <refsect1>
3164   <title>Return Value</title>
3165
3166   <para>
3167    the copied row; <symbol>NULL</symbol> only if
3168    <parameter>tuple</parameter> is <symbol>NULL</symbol>
3169   </para>
3170  </refsect1>
3171 </refentry>
3172
3173 <!-- *********************************************** -->
3174
3175 <refentry id="spi-spi-returntuple">
3176  <refmeta>
3177   <refentrytitle>SPI_returntuple</refentrytitle>
3178  </refmeta>
3179
3180  <refnamediv>
3181   <refname>SPI_returntuple</refname>
3182   <refpurpose>prepare to return a tuple as a Datum</refpurpose>
3183  </refnamediv>
3184
3185  <indexterm><primary>SPI_returntuple</primary></indexterm>
3186
3187  <refsynopsisdiv>
3188 <synopsis>
3189 HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)
3190 </synopsis>
3191  </refsynopsisdiv>
3192
3193  <refsect1>
3194   <title>Description</title>
3195
3196   <para>
3197    <function>SPI_returntuple</function> makes a copy of a row in
3198    the upper executor context, returning it in the form of a row type <type>Datum</type>.
3199    The returned pointer need only be converted to <type>Datum</type> via <function>PointerGetDatum</function>
3200    before returning.
3201   </para>
3202
3203   <para>
3204    Note that this should be used for functions that are declared to return
3205    composite types.  It is not used for triggers; use
3206    <function>SPI_copytuple</> for returning a modified row in a trigger.
3207   </para>
3208  </refsect1>
3209
3210  <refsect1>
3211   <title>Arguments</title>
3212
3213   <variablelist>
3214    <varlistentry>
3215     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3216     <listitem>
3217      <para>
3218       row to be copied
3219      </para>
3220     </listitem>
3221    </varlistentry>
3222
3223    <varlistentry>
3224     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
3225     <listitem>
3226      <para>
3227       descriptor for row (pass the same descriptor each time for most
3228       effective caching)
3229      </para>
3230     </listitem>
3231    </varlistentry>
3232   </variablelist>
3233  </refsect1>
3234
3235  <refsect1>
3236   <title>Return Value</title>
3237
3238   <para>
3239    <type>HeapTupleHeader</type> pointing to copied row;
3240    <symbol>NULL</symbol> only if
3241    <parameter>row</parameter> or <parameter>rowdesc</parameter> is
3242    <symbol>NULL</symbol>
3243   </para>
3244  </refsect1>
3245 </refentry>
3246
3247 <!-- *********************************************** -->
3248
3249 <refentry id="spi-spi-modifytuple">
3250  <refmeta>
3251   <refentrytitle>SPI_modifytuple</refentrytitle>
3252  </refmeta>
3253
3254  <refnamediv>
3255   <refname>SPI_modifytuple</refname>
3256   <refpurpose>create a row by replacing selected fields of a given row</refpurpose>
3257  </refnamediv>
3258
3259  <indexterm><primary>SPI_modifytuple</primary></indexterm>
3260
3261  <refsynopsisdiv>
3262 <synopsis>
3263 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>)
3264 </synopsis>
3265  </refsynopsisdiv>
3266
3267  <refsect1>
3268   <title>Description</title>
3269
3270   <para>
3271    <function>SPI_modifytuple</function> creates a new row by
3272    substituting new values for selected columns, copying the original
3273    row's columns at other positions.  The input row is not modified.
3274   </para>
3275  </refsect1>
3276
3277  <refsect1>
3278   <title>Arguments</title>
3279
3280   <variablelist>
3281    <varlistentry>
3282     <term><literal>Relation <parameter>rel</parameter></literal></term>
3283     <listitem>
3284      <para>
3285       Used only as the source of the row descriptor for the row.
3286       (Passing a relation rather than a row descriptor is a
3287       misfeature.)
3288      </para>
3289     </listitem>
3290    </varlistentry>
3291
3292    <varlistentry>
3293     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3294     <listitem>
3295      <para>
3296       row to be modified
3297      </para>
3298     </listitem>
3299    </varlistentry>
3300
3301    <varlistentry>
3302     <term><literal>int <parameter>ncols</parameter></literal></term>
3303     <listitem>
3304      <para>
3305       number of column numbers in the array
3306       <parameter>colnum</parameter>
3307      </para>
3308     </listitem>
3309    </varlistentry>
3310
3311    <varlistentry>
3312     <term><literal>int * <parameter>colnum</parameter></literal></term>
3313     <listitem>
3314      <para>
3315       array of the numbers of the columns that are to be changed
3316       (column numbers start at 1)
3317      </para>
3318     </listitem>
3319    </varlistentry>
3320
3321    <varlistentry>
3322     <term><literal>Datum * <parameter>values</parameter></literal></term>
3323     <listitem>
3324      <para>
3325       new values for the specified columns
3326      </para>
3327     </listitem>
3328    </varlistentry>
3329
3330    <varlistentry>
3331     <term><literal>const char * <parameter>Nulls</parameter></literal></term>
3332     <listitem>
3333      <para>
3334       which new values are null, if any (see
3335       <function>SPI_execute_plan</function> for the format)
3336      </para>
3337     </listitem>
3338    </varlistentry>
3339   </variablelist>
3340  </refsect1>
3341
3342  <refsect1>
3343   <title>Return Value</title>
3344
3345   <para>
3346    new row with modifications, allocated in the upper executor
3347    context; <symbol>NULL</symbol> only if <parameter>row</parameter>
3348    is <symbol>NULL</symbol>
3349   </para>
3350
3351   <para>
3352    On error, <varname>SPI_result</varname> is set as follows:
3353    <variablelist>
3354     <varlistentry>
3355      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
3356      <listitem>
3357       <para>
3358        if <parameter>rel</> is <symbol>NULL</>, or if
3359        <parameter>row</> is <symbol>NULL</>, or if <parameter>ncols</>
3360        is less than or equal to 0, or if <parameter>colnum</> is
3361        <symbol>NULL</>, or if <parameter>values</> is <symbol>NULL</>.
3362       </para>
3363      </listitem>
3364     </varlistentry>
3365
3366     <varlistentry>
3367      <term><symbol>SPI_ERROR_NOATTRIBUTE</symbol></term>
3368      <listitem>
3369       <para>
3370        if <parameter>colnum</> contains an invalid column number (less
3371        than or equal to 0 or greater than the number of column in
3372        <parameter>row</>)
3373       </para>
3374      </listitem>
3375     </varlistentry>
3376    </variablelist>
3377   </para>
3378  </refsect1>
3379 </refentry>
3380
3381 <!-- *********************************************** -->
3382
3383 <refentry id="spi-spi-freetuple">
3384  <refmeta>
3385   <refentrytitle>SPI_freetuple</refentrytitle>
3386  </refmeta>
3387
3388  <refnamediv>
3389   <refname>SPI_freetuple</refname>
3390   <refpurpose>free a row allocated in the upper executor context</refpurpose>
3391  </refnamediv>
3392
3393  <indexterm><primary>SPI_freetuple</primary></indexterm>
3394
3395  <refsynopsisdiv>
3396 <synopsis>
3397 void SPI_freetuple(HeapTuple <parameter>row</parameter>)
3398 </synopsis>
3399  </refsynopsisdiv>
3400
3401  <refsect1>
3402   <title>Description</title>
3403
3404   <para>
3405    <function>SPI_freetuple</function> frees a row previously allocated
3406    in the upper executor context.
3407   </para>
3408
3409   <para>
3410    This function is no longer different from plain
3411    <function>heap_freetuple</function>.  It's kept just for backward
3412    compatibility of existing code.
3413   </para>
3414  </refsect1>
3415
3416  <refsect1>
3417   <title>Arguments</title>
3418
3419   <variablelist>
3420    <varlistentry>
3421     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3422     <listitem>
3423      <para>
3424       row to free
3425      </para>
3426     </listitem>
3427    </varlistentry>
3428   </variablelist>
3429  </refsect1>
3430 </refentry>
3431
3432 <!-- *********************************************** -->
3433
3434 <refentry id="spi-spi-freetupletable">
3435  <refmeta>
3436   <refentrytitle>SPI_freetuptable</refentrytitle>
3437  </refmeta>
3438
3439  <refnamediv>
3440   <refname>SPI_freetuptable</refname>
3441   <refpurpose>free a row set created by <function>SPI_execute</> or a similar
3442   function</refpurpose>
3443  </refnamediv>
3444
3445  <indexterm><primary>SPI_freetuptable</primary></indexterm>
3446
3447  <refsynopsisdiv>
3448 <synopsis>
3449 void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)
3450 </synopsis>
3451  </refsynopsisdiv>
3452
3453  <refsect1>
3454   <title>Description</title>
3455
3456   <para>
3457    <function>SPI_freetuptable</function> frees a row set created by a
3458    prior SPI command execution function, such as
3459    <function>SPI_execute</>.  Therefore, this function is usually called
3460    with the global variable <varname>SPI_tupletable</varname> as
3461    argument.
3462   </para>
3463
3464   <para>
3465    This function is useful if a SPI procedure needs to execute
3466    multiple commands and does not want to keep the results of earlier
3467    commands around until it ends.  Note that any unfreed row sets will
3468    be freed anyway at <function>SPI_finish</>.
3469   </para>
3470  </refsect1>
3471
3472  <refsect1>
3473   <title>Arguments</title>
3474
3475   <variablelist>
3476    <varlistentry>
3477     <term><literal>SPITupleTable * <parameter>tuptable</parameter></literal></term>
3478     <listitem>
3479      <para>
3480       pointer to row set to free
3481      </para>
3482     </listitem>
3483    </varlistentry>
3484   </variablelist>
3485  </refsect1>
3486 </refentry>
3487
3488 <!-- *********************************************** -->
3489
3490 <refentry id="spi-spi-freeplan">
3491  <refmeta>
3492   <refentrytitle>SPI_freeplan</refentrytitle>
3493  </refmeta>
3494
3495  <refnamediv>
3496   <refname>SPI_freeplan</refname>
3497   <refpurpose>free a previously saved plan</refpurpose>
3498  </refnamediv>
3499
3500  <indexterm><primary>SPI_freeplan</primary></indexterm>
3501
3502  <refsynopsisdiv>
3503 <synopsis>
3504 int SPI_freeplan(SPIPlanPtr <parameter>plan</parameter>)
3505 </synopsis>
3506  </refsynopsisdiv>
3507
3508  <refsect1>
3509   <title>Description</title>
3510
3511   <para>
3512    <function>SPI_freeplan</function> releases a command execution plan
3513    previously returned by <function>SPI_prepare</function> or saved by
3514    <function>SPI_saveplan</function>.
3515   </para>
3516  </refsect1>
3517
3518  <refsect1>
3519   <title>Arguments</title>
3520
3521   <variablelist>
3522    <varlistentry>
3523     <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
3524     <listitem>
3525      <para>
3526       pointer to plan to free
3527      </para>
3528     </listitem>
3529    </varlistentry>
3530   </variablelist>
3531  </refsect1>
3532
3533  <refsect1>
3534   <title>Return Value</title>
3535
3536   <para>
3537    <symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>plan</parameter>
3538    is <symbol>NULL</symbol> or invalid
3539   </para>
3540  </refsect1>
3541 </refentry>
3542
3543  </sect1>
3544
3545  <sect1 id="spi-visibility">
3546   <title>Visibility of Data Changes</title>
3547
3548   <para>
3549    The following rules govern the visibility of data changes in
3550    functions that use SPI (or any other C function):
3551
3552    <itemizedlist>
3553     <listitem>
3554      <para>
3555       During the execution of an SQL command, any data changes made by
3556       the command are invisible to the command itself.  For
3557       example, in:
3558 <programlisting>
3559 INSERT INTO a SELECT * FROM a;
3560 </programlisting>
3561       the inserted rows are invisible to the <command>SELECT</command>
3562       part.
3563      </para>
3564     </listitem>
3565
3566     <listitem>
3567      <para>
3568       Changes made by a command C are visible to all commands that are
3569       started after C, no matter whether they are started inside C
3570       (during the execution of C) or after C is done.
3571      </para>
3572     </listitem>
3573
3574     <listitem>
3575      <para>
3576       Commands executed via SPI inside a function called by an SQL command
3577       (either an ordinary function or a trigger) follow one or the
3578       other of the above rules depending on the read/write flag passed
3579       to SPI.  Commands executed in read-only mode follow the first
3580       rule: they cannot see changes of the calling command.  Commands executed
3581       in read-write mode follow the second rule: they can see all changes made
3582       so far.
3583      </para>
3584     </listitem>
3585
3586     <listitem>
3587      <para>
3588       All standard procedural languages set the SPI read-write mode
3589       depending on the volatility attribute of the function.  Commands of
3590       <literal>STABLE</> and <literal>IMMUTABLE</> functions are done in
3591       read-only mode, while commands of <literal>VOLATILE</> functions are
3592       done in read-write mode.  While authors of C functions are able to
3593       violate this convention, it's unlikely to be a good idea to do so.
3594      </para>
3595     </listitem>
3596    </itemizedlist>
3597   </para>
3598
3599   <para>
3600    The next section contains an example that illustrates the
3601    application of these rules.
3602   </para>
3603  </sect1>
3604
3605  <sect1 id="spi-examples">
3606   <title>Examples</title>
3607
3608   <para>
3609    This section contains a very simple example of SPI usage. The
3610    procedure <function>execq</function> takes an SQL command as its
3611    first argument and a row count as its second, executes the command
3612    using <function>SPI_exec</function> and returns the number of rows
3613    that were processed by the command.  You can find more complex
3614    examples for SPI in the source tree in
3615    <filename>src/test/regress/regress.c</filename> and in
3616    <filename>contrib/spi</filename>.
3617   </para>
3618
3619 <programlisting>
3620 #include "executor/spi.h"
3621
3622 #ifdef PG_MODULE_MAGIC
3623 PG_MODULE_MAGIC;
3624 #endif
3625
3626 int execq(text *sql, int cnt);
3627
3628 int
3629 execq(text *sql, int cnt)
3630 {
3631     char *command;
3632     int ret;
3633     int proc;
3634
3635     /* Convert given text object to a C string */
3636     command = text_to_cstring(sql);
3637
3638     SPI_connect();
3639
3640     ret = SPI_exec(command, cnt);
3641
3642     proc = SPI_processed;
3643     /*
3644      * If some rows were fetched, print them via elog(INFO).
3645      */
3646     if (ret &gt; 0 &amp;&amp; SPI_tuptable != NULL)
3647     {
3648         TupleDesc tupdesc = SPI_tuptable-&gt;tupdesc;
3649         SPITupleTable *tuptable = SPI_tuptable;
3650         char buf[8192];
3651         int i, j;
3652
3653         for (j = 0; j &lt; proc; j++)
3654         {
3655             HeapTuple tuple = tuptable-&gt;vals[j];
3656
3657             for (i = 1, buf[0] = 0; i &lt;= tupdesc-&gt;natts; i++)
3658                 snprintf(buf + strlen (buf), sizeof(buf) - strlen(buf), " %s%s",
3659                         SPI_getvalue(tuple, tupdesc, i),
3660                         (i == tupdesc-&gt;natts) ? " " : " |");
3661             elog(INFO, "EXECQ: %s", buf);
3662         }
3663     }
3664
3665     SPI_finish();
3666     pfree(command);
3667
3668     return (proc);
3669 }
3670 </programlisting>
3671
3672   <para>
3673    (This function uses call convention version 0, to make the example
3674    easier to understand.  In real applications you should use the new
3675    version 1 interface.)
3676   </para>
3677
3678   <para>
3679    This is how you declare the function after having compiled it into
3680    a shared library (details are in <xref linkend="dfunc">.):
3681
3682 <programlisting>
3683 CREATE FUNCTION execq(text, integer) RETURNS integer
3684     AS '<replaceable>filename</replaceable>'
3685     LANGUAGE C;
3686 </programlisting>
3687   </para>
3688
3689   <para>
3690    Here is a sample session:
3691
3692 <programlisting>
3693 =&gt; SELECT execq('CREATE TABLE a (x integer)', 0);
3694  execq
3695 -------
3696      0
3697 (1 row)
3698
3699 =&gt; INSERT INTO a VALUES (execq('INSERT INTO a VALUES (0)', 0));
3700 INSERT 0 1
3701 =&gt; SELECT execq('SELECT * FROM a', 0);
3702 INFO:  EXECQ:  0    -- inserted by execq
3703 INFO:  EXECQ:  1    -- returned by execq and inserted by upper INSERT
3704
3705  execq
3706 -------
3707      2
3708 (1 row)
3709
3710 =&gt; SELECT execq('INSERT INTO a SELECT x + 2 FROM a', 1);
3711  execq
3712 -------
3713      1
3714 (1 row)
3715
3716 =&gt; SELECT execq('SELECT * FROM a', 10);
3717 INFO:  EXECQ:  0
3718 INFO:  EXECQ:  1
3719 INFO:  EXECQ:  2    -- 0 + 2, only one row inserted - as specified
3720
3721  execq
3722 -------
3723      3              -- 10 is the max value only, 3 is the real number of rows
3724 (1 row)
3725
3726 =&gt; DELETE FROM a;
3727 DELETE 3
3728 =&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
3729 INSERT 0 1
3730 =&gt; SELECT * FROM a;
3731  x
3732 ---
3733  1                  -- no rows in a (0) + 1
3734 (1 row)
3735
3736 =&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
3737 INFO:  EXECQ:  1
3738 INSERT 0 1
3739 =&gt; SELECT * FROM a;
3740  x
3741 ---
3742  1
3743  2                  -- there was one row in a + 1
3744 (2 rows)
3745
3746 -- This demonstrates the data changes visibility rule:
3747
3748 =&gt; INSERT INTO a SELECT execq('SELECT * FROM a', 0) * x FROM a;
3749 INFO:  EXECQ:  1
3750 INFO:  EXECQ:  2
3751 INFO:  EXECQ:  1
3752 INFO:  EXECQ:  2
3753 INFO:  EXECQ:  2
3754 INSERT 0 2
3755 =&gt; SELECT * FROM a;
3756  x
3757 ---
3758  1
3759  2
3760  2                  -- 2 rows * 1 (x in first row)
3761  6                  -- 3 rows (2 + 1 just inserted) * 2 (x in second row)
3762 (4 rows)               ^^^^^^
3763                        rows visible to execq() in different invocations
3764 </programlisting>
3765   </para>
3766  </sect1>
3767 </chapter>