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

   1 <!-- $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.48 2006/09/10 20:56:42 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   optimizer, 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 may 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 may 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 may 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 may pass multiple commands in one string.
 325    <function>SPI_execute</function> returns the
 326    result for the command executed last.  The <parameter>count</parameter>
 327    limit applies to each command separately, but it is not applied to
 328    hidden commands generated by rules.
 329   </para>
 330
 331   <para>
 332    When <parameter>read_only</parameter> is <literal>false</>,
 333    <function>SPI_execute</function> increments the command
 334    counter and computes a new <firstterm>snapshot</> before executing each
 335    command in the string.  The snapshot does not actually change if the
 336    current transaction isolation level is <literal>SERIALIZABLE</>, but in
 337    <literal>READ COMMITTED</> mode the snapshot update allows each command to
 338    see the results of newly committed transactions from other sessions.
 339    This is essential for consistent behavior when the commands are modifying
 340    the database.
 341   </para>
 342
 343   <para>
 344    When <parameter>read_only</parameter> is <literal>true</>,
 345    <function>SPI_execute</function> does not update either the snapshot
 346    or the command counter, and it allows only plain <command>SELECT</>
 347    commands to appear in the command string.  The commands are executed
 348    using the snapshot previously established for the surrounding query.
 349    This execution mode is somewhat faster than the read/write mode due
 350    to eliminating per-command overhead.  It also allows genuinely
 351    <firstterm>stable</> functions to be built: since successive executions
 352    will all use the same snapshot, there will be no change in the results.
 353   </para>
 354
 355   <para>
 356    It is generally unwise to mix read-only and read-write commands within
 357    a single function using SPI; that could result in very confusing behavior,
 358    since the read-only queries would not see the results of any database
 359    updates done by the read-write queries.
 360   </para>
 361
 362   <para>
 363    The actual number of rows for which the (last) command was executed
 364    is returned in the global variable <varname>SPI_processed</varname>.
 365    If the return value of the function is <symbol>SPI_OK_SELECT</symbol>,
 366    <symbol>SPI_OK_INSERT_RETURNING</symbol>,
 367    <symbol>SPI_OK_DELETE_RETURNING</symbol>, or
 368    <symbol>SPI_OK_UPDATE_RETURNING</symbol>,
 369    then you may use the
 370    global pointer <literal>SPITupleTable *SPI_tuptable</literal> to
 371    access the result rows.  Some utility commands (such as
 372    <command>EXPLAIN</>) also return rowsets, and <literal>SPI_tuptable</>
 373    will contain the result in these cases too.
 374   </para>
 375
 376   <para>
 377    The structure <structname>SPITupleTable</structname> is defined
 378    thus:
 379 <programlisting>
 380 typedef struct
 381 {
 382     MemoryContext tuptabcxt;    /* memory context of result table */
 383     uint32      alloced;        /* number of alloced vals */
 384     uint32      free;           /* number of free vals */
 385     TupleDesc   tupdesc;        /* row descriptor */
 386     HeapTuple  *vals;           /* rows */
 387 } SPITupleTable;
 388 </programlisting>
 389    <structfield>vals</> is an array of pointers to rows.  (The number
 390    of valid entries is given by <varname>SPI_processed</varname>.)
 391    <structfield>tupdesc</> is a row descriptor which you may pass to
 392    SPI functions dealing with rows.  <structfield>tuptabcxt</>,
 393    <structfield>alloced</>, and <structfield>free</> are internal
 394    fields not intended for use by SPI callers.
 395   </para>
 396
 397   <para>
 398    <function>SPI_finish</function> frees all
 399    <structname>SPITupleTable</>s allocated during the current
 400    procedure.  You can free a particular result table earlier, if you
 401    are done with it, by calling <function>SPI_freetuptable</function>.
 402   </para>
 403  </refsect1>
 404
 405  <refsect1>
 406   <title>Arguments</title>
 407
 408   <variablelist>
 409    <varlistentry>
 410     <term><literal>const char * <parameter>command</parameter></literal></term>
 411     <listitem>
 412      <para>
 413       string containing command to execute
 414      </para>
 415     </listitem>
 416    </varlistentry>
 417
 418    <varlistentry>
 419     <term><literal>bool <parameter>read_only</parameter></literal></term>
 420     <listitem>
 421      <para>
 422       <literal>true</> for read-only execution
 423      </para>
 424     </listitem>
 425    </varlistentry>
 426
 427    <varlistentry>
 428     <term><literal>long <parameter>count</parameter></literal></term>
 429     <listitem>
 430      <para>
 431       maximum number of rows to process or return
 432      </para>
 433     </listitem>
 434    </varlistentry>
 435   </variablelist>
 436  </refsect1>
 437
 438  <refsect1>
 439   <title>Return Value</title>
 440
 441   <para>
 442    If the execution of the command was successful then one of the
 443    following (nonnegative) values will be returned:
 444
 445    <variablelist>
 446     <varlistentry>
 447      <term><symbol>SPI_OK_SELECT</symbol></term>
 448      <listitem>
 449       <para>
 450        if a <command>SELECT</command> (but not <command>SELECT
 451        INTO</>) was executed
 452       </para>
 453      </listitem>
 454     </varlistentry>
 455
 456     <varlistentry>
 457      <term><symbol>SPI_OK_SELINTO</symbol></term>
 458      <listitem>
 459       <para>
 460        if a <command>SELECT INTO</command> was executed
 461       </para>
 462      </listitem>
 463     </varlistentry>
 464
 465     <varlistentry>
 466      <term><symbol>SPI_OK_INSERT</symbol></term>
 467      <listitem>
 468       <para>
 469        if an <command>INSERT</command> was executed
 470       </para>
 471      </listitem>
 472     </varlistentry>
 473
 474     <varlistentry>
 475      <term><symbol>SPI_OK_DELETE</symbol></term>
 476      <listitem>
 477       <para>
 478        if a <command>DELETE</command> was executed
 479       </para>
 480      </listitem>
 481     </varlistentry>
 482
 483     <varlistentry>
 484      <term><symbol>SPI_OK_UPDATE</symbol></term>
 485      <listitem>
 486       <para>
 487        if an <command>UPDATE</command> was executed
 488       </para>
 489      </listitem>
 490     </varlistentry>
 491
 492     <varlistentry>
 493      <term><symbol>SPI_OK_INSERT_RETURNING</symbol></term>
 494      <listitem>
 495       <para>
 496        if an <command>INSERT RETURNING</command> was executed
 497       </para>
 498      </listitem>
 499     </varlistentry>
 500
 501     <varlistentry>
 502      <term><symbol>SPI_OK_DELETE_RETURNING</symbol></term>
 503      <listitem>
 504       <para>
 505        if a <command>DELETE RETURNING</command> was executed
 506       </para>
 507      </listitem>
 508     </varlistentry>
 509
 510     <varlistentry>
 511      <term><symbol>SPI_OK_UPDATE_RETURNING</symbol></term>
 512      <listitem>
 513       <para>
 514        if an <command>UPDATE RETURNING</command> was executed
 515       </para>
 516      </listitem>
 517     </varlistentry>
 518
 519     <varlistentry>
 520      <term><symbol>SPI_OK_UTILITY</symbol></term>
 521      <listitem>
 522       <para>
 523        if a utility command (e.g., <command>CREATE TABLE</command>)
 524        was executed
 525       </para>
 526      </listitem>
 527     </varlistentry>
 528    </variablelist>
 529   </para>
 530
 531   <para>
 532    On error, one of the following negative values is returned:
 533
 534    <variablelist>
 535     <varlistentry>
 536      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
 537      <listitem>
 538       <para>
 539        if <parameter>command</parameter> is <symbol>NULL</symbol> or
 540        <parameter>count</parameter> is less than 0
 541       </para>
 542      </listitem>
 543     </varlistentry>
 544
 545     <varlistentry>
 546      <term><symbol>SPI_ERROR_COPY</symbol></term>
 547      <listitem>
 548       <para>
 549        if <command>COPY TO stdout</> or <command>COPY FROM stdin</>
 550        was attempted
 551       </para>
 552      </listitem>
 553     </varlistentry>
 554
 555     <varlistentry>
 556      <term><symbol>SPI_ERROR_CURSOR</symbol></term>
 557      <listitem>
 558       <para>
 559        if <command>DECLARE</>, <command>CLOSE</>, or <command>FETCH</>
 560        was attempted
 561       </para>
 562      </listitem>
 563     </varlistentry>
 564
 565     <varlistentry>
 566      <term><symbol>SPI_ERROR_TRANSACTION</symbol></term>
 567      <listitem>
 568       <para>
 569        if any command involving transaction manipulation was attempted
 570        (<command>BEGIN</>,
 571        <command>COMMIT</>,
 572        <command>ROLLBACK</>,
 573        <command>SAVEPOINT</>,
 574        <command>PREPARE TRANSACTION</>,
 575        <command>COMMIT PREPARED</>,
 576        <command>ROLLBACK PREPARED</>,
 577        or any variant thereof)
 578       </para>
 579      </listitem>
 580     </varlistentry>
 581
 582     <varlistentry>
 583      <term><symbol>SPI_ERROR_OPUNKNOWN</symbol></term>
 584      <listitem>
 585       <para>
 586        if the command type is unknown (shouldn't happen)
 587       </para>
 588      </listitem>
 589     </varlistentry>
 590
 591     <varlistentry>
 592      <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
 593      <listitem>
 594       <para>
 595        if called from an unconnected procedure
 596       </para>
 597      </listitem>
 598     </varlistentry>
 599    </variablelist>
 600   </para>
 601  </refsect1>
 602
 603  <refsect1>
 604   <title>Notes</title>
 605
 606   <para>
 607    The functions <function>SPI_execute</function>,
 608    <function>SPI_exec</function>,
 609    <function>SPI_execute_plan</function>, and
 610    <function>SPI_execp</function> change both
 611    <varname>SPI_processed</varname> and
 612    <varname>SPI_tuptable</varname> (just the pointer, not the contents
 613    of the structure).  Save these two global variables into local
 614    procedure variables if you need to access the result table of
 615    <function>SPI_execute</function> or a related function
 616    across later calls.
 617   </para>
 618  </refsect1>
 619 </refentry>
 620
 621 <!-- *********************************************** -->
 622
 623 <refentry id="spi-spi-exec">
 624  <refmeta>
 625   <refentrytitle>SPI_exec</refentrytitle>
 626  </refmeta>
 627
 628  <refnamediv>
 629   <refname>SPI_exec</refname>
 630   <refpurpose>execute a read/write command</refpurpose>
 631  </refnamediv>
 632
 633  <indexterm><primary>SPI_exec</primary></indexterm>
 634
 635  <refsynopsisdiv>
 636 <synopsis>
 637 int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count</parameter>)
 638 </synopsis>
 639  </refsynopsisdiv>
 640
 641  <refsect1>
 642   <title>Description</title>
 643
 644   <para>
 645    <function>SPI_exec</function> is the same as
 646    <function>SPI_execute</function>, with the latter's
 647    <parameter>read_only</parameter> parameter always taken as
 648    <literal>false</>.
 649   </para>
 650  </refsect1>
 651
 652  <refsect1>
 653   <title>Arguments</title>
 654
 655   <variablelist>
 656    <varlistentry>
 657     <term><literal>const char * <parameter>command</parameter></literal></term>
 658     <listitem>
 659      <para>
 660       string containing command to execute
 661      </para>
 662     </listitem>
 663    </varlistentry>
 664
 665    <varlistentry>
 666     <term><literal>long <parameter>count</parameter></literal></term>
 667     <listitem>
 668      <para>
 669       maximum number of rows to process or return
 670      </para>
 671     </listitem>
 672    </varlistentry>
 673   </variablelist>
 674  </refsect1>
 675
 676  <refsect1>
 677   <title>Return Value</title>
 678
 679   <para>
 680    See <function>SPI_execute</function>.
 681   </para>
 682  </refsect1>
 683 </refentry>
 684
 685 <!-- *********************************************** -->
 686
 687 <refentry id="spi-spi-prepare">
 688  <refmeta>
 689   <refentrytitle>SPI_prepare</refentrytitle>
 690  </refmeta>
 691
 692  <refnamediv>
 693   <refname>SPI_prepare</refname>
 694   <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
 695  </refnamediv>
 696
 697  <indexterm><primary>SPI_prepare</primary></indexterm>
 698
 699  <refsynopsisdiv>
 700 <synopsis>
 701 void * SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
 702 </synopsis>
 703  </refsynopsisdiv>
 704
 705  <refsect1>
 706   <title>Description</title>
 707
 708   <para>
 709    <function>SPI_prepare</function> creates and returns an execution
 710    plan for the specified command but doesn't execute the command.
 711    This function should only be called from a connected procedure.
 712   </para>
 713
 714   <para>
 715    When the same or a similar command is to be executed repeatedly, it
 716    may be advantageous to perform the planning only once.
 717    <function>SPI_prepare</function> converts a command string into an
 718    execution plan that can be executed repeatedly using
 719    <function>SPI_execute_plan</function>.
 720   </para>
 721
 722   <para>
 723    A prepared command can be generalized by writing parameters
 724    (<literal>$1</>, <literal>$2</>, etc.) in place of what would be
 725    constants in a normal command.  The actual values of the parameters
 726    are then specified when <function>SPI_execute_plan</function> is called.
 727    This allows the prepared command to be used over a wider range of
 728    situations than would be possible without parameters.
 729   </para>
 730
 731   <para>
 732    The plan returned by <function>SPI_prepare</function> can be used
 733    only in the current invocation of the procedure, since
 734    <function>SPI_finish</function> frees memory allocated for a plan.
 735    But a plan can be saved for longer using the function
 736    <function>SPI_saveplan</function>.
 737   </para>
 738  </refsect1>
 739
 740  <refsect1>
 741   <title>Arguments</title>
 742
 743   <variablelist>
 744    <varlistentry>
 745     <term><literal>const char * <parameter>command</parameter></literal></term>
 746     <listitem>
 747      <para>
 748       command string
 749      </para>
 750     </listitem>
 751    </varlistentry>
 752
 753    <varlistentry>
 754     <term><literal>int <parameter>nargs</parameter></literal></term>
 755     <listitem>
 756      <para>
 757       number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
 758      </para>
 759     </listitem>
 760    </varlistentry>
 761
 762    <varlistentry>
 763     <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
 764     <listitem>
 765      <para>
 766       pointer to an array containing the <acronym>OID</acronym>s of
 767       the data types of the parameters
 768      </para>
 769     </listitem>
 770    </varlistentry>
 771   </variablelist>
 772  </refsect1>
 773
 774  <refsect1>
 775   <title>Return Value</title>
 776
 777   <para>
 778    <function>SPI_prepare</function> returns a non-null pointer to an
 779    execution plan.  On error, <symbol>NULL</symbol> will be returned,
 780    and <varname>SPI_result</varname> will be set to one of the same
 781    error codes used by <function>SPI_execute</function>, except that
 782    it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if
 783    <parameter>command</parameter> is <symbol>NULL</symbol>, or if
 784    <parameter>nargs</> is less than 0, or if <parameter>nargs</> is
 785    greater than 0 and <parameter>argtypes</> is <symbol>NULL</symbol>.
 786   </para>
 787  </refsect1>
 788
 789  <refsect1>
 790   <title>Notes</title>
 791
 792   <para>
 793    There is a disadvantage to using parameters: since the planner does
 794    not know the values that will be supplied for the parameters, it
 795    may make worse planning choices than it would make for a normal
 796    command with all constants visible.
 797   </para>
 798  </refsect1>
 799 </refentry>
 800
 801 <!-- *********************************************** -->
 802
 803 <refentry id="spi-spi-getargcount">
 804  <refmeta>
 805   <refentrytitle>SPI_getargcount</refentrytitle>
 806  </refmeta>
 807
 808  <refnamediv>
 809   <refname>SPI_getargcount</refname>
 810   <refpurpose>return the number of arguments needed by a plan
 811   prepared by <function>SPI_prepare</function></refpurpose>
 812  </refnamediv>
 813
 814  <indexterm><primary>SPI_getargcount</primary></indexterm>
 815
 816  <refsynopsisdiv>
 817 <synopsis>
 818 int SPI_getargcount(void * <parameter>plan</parameter>)
 819 </synopsis>
 820  </refsynopsisdiv>
 821
 822  <refsect1>
 823   <title>Description</title>
 824
 825   <para>
 826    <function>SPI_getargcount</function> returns the number of arguments needed
 827    to execute a plan prepared by <function>SPI_prepare</function>.
 828   </para>
 829  </refsect1>
 830
 831  <refsect1>
 832   <title>Arguments</title>
 833
 834   <variablelist>
 835    <varlistentry>
 836     <term><literal>void * <parameter>plan</parameter></literal></term>
 837     <listitem>
 838      <para>
 839       execution plan (returned by <function>SPI_prepare</function>)
 840      </para>
 841     </listitem>
 842    </varlistentry>
 843   </variablelist>
 844  </refsect1>
 845
 846  <refsect1>
 847   <title>Return Value</title>
 848   <para>
 849     The expected argument count for the <parameter>plan</parameter>, or
 850     <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan
 851     </parameter> is <symbol>NULL</symbol>
 852   </para>
 853  </refsect1>
 854 </refentry>
 855
 856 <!-- *********************************************** -->
 857
 858 <refentry id="spi-spi-getargtypeid">
 859  <refmeta>
 860   <refentrytitle>SPI_getargtypeid</refentrytitle>
 861  </refmeta>
 862
 863  <refnamediv>
 864   <refname>SPI_getargtypeid</refname>
 865   <refpurpose>return the data type OID for an argument of
 866   a plan prepared by <function>SPI_prepare</function></refpurpose>
 867  </refnamediv>
 868
 869  <indexterm><primary>SPI_getargtypeid</primary></indexterm>
 870
 871  <refsynopsisdiv>
 872 <synopsis>
 873 Oid SPI_getargtypeid(void * <parameter>plan</parameter>, int <parameter>argIndex</parameter>)
 874 </synopsis>
 875  </refsynopsisdiv>
 876
 877  <refsect1>
 878   <title>Description</title>
 879
 880   <para>
 881    <function>SPI_getargtypeid</function> returns the OID representing the type
 882    id for the <parameter>argIndex</parameter>'th argument of a plan prepared by
 883    <function>SPI_prepare</function>. First argument is at index zero.
 884   </para>
 885  </refsect1>
 886
 887  <refsect1>
 888   <title>Arguments</title>
 889
 890   <variablelist>
 891    <varlistentry>
 892     <term><literal>void * <parameter>plan</parameter></literal></term>
 893     <listitem>
 894      <para>
 895       execution plan (returned by <function>SPI_prepare</function>)
 896      </para>
 897     </listitem>
 898    </varlistentry>
 899
 900    <varlistentry>
 901     <term><literal>int <parameter>argIndex</parameter></literal></term>
 902     <listitem>
 903      <para>
 904       zero based index of the argument
 905      </para>
 906     </listitem>
 907    </varlistentry>
 908   </variablelist>
 909  </refsect1>
 910
 911  <refsect1>
 912   <title>Return Value</title>
 913   <para>
 914     The type id of the argument at the given index, or
 915     <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan</parameter> is
 916     <symbol>NULL</symbol> or <parameter>argIndex</parameter> is less than 0 or
 917     not less than the number of arguments declared for the
 918     <parameter>plan</parameter>
 919   </para>
 920  </refsect1>
 921 </refentry>
 922
 923 <!-- *********************************************** -->
 924
 925 <refentry id="spi-spi-is-cursor-plan">
 926  <refmeta>
 927   <refentrytitle>SPI_is_cursor_plan</refentrytitle>
 928  </refmeta>
 929
 930  <refnamediv>
 931   <refname>SPI_is_cursor_plan</refname>
 932   <refpurpose>return <symbol>true</symbol> if a plan
 933   prepared by <function>SPI_prepare</function> can be used with
 934   <function>SPI_cursor_open</function></refpurpose>
 935  </refnamediv>
 936
 937  <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>
 938
 939  <refsynopsisdiv>
 940 <synopsis>
 941 bool SPI_is_cursor_plan(void * <parameter>plan</parameter>)
 942 </synopsis>
 943  </refsynopsisdiv>
 944
 945  <refsect1>
 946   <title>Description</title>
 947
 948   <para>
 949    <function>SPI_is_cursor_plan</function> returns <symbol>true</symbol>
 950    if a plan prepared by <function>SPI_prepare</function> can be passed
 951    as an argument to <function>SPI_cursor_open</function>, or
 952    <symbol>false</symbol> if that is not the case. The criteria are that the
 953    <parameter>plan</parameter> represents one single command and that this
 954    command returns tuples to the caller; for example, <command>SELECT</>
 955    is allowed unless it contains an <literal>INTO</> clause, and
 956    <command>UPDATE</> is allowed only if it contains a <literal>RETURNING</>
 957    clause.
 958   </para>
 959  </refsect1>
 960
 961  <refsect1>
 962   <title>Arguments</title>
 963
 964   <variablelist>
 965    <varlistentry>
 966     <term><literal>void * <parameter>plan</parameter></literal></term>
 967     <listitem>
 968      <para>
 969       execution plan (returned by <function>SPI_prepare</function>)
 970      </para>
 971     </listitem>
 972    </varlistentry>
 973   </variablelist>
 974  </refsect1>
 975
 976  <refsect1>
 977   <title>Return Value</title>
 978   <para>
 979     <symbol>true</symbol> or <symbol>false</symbol> to indicate if the
 980     <parameter>plan</parameter> can produce a cursor or not, or
 981     <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan</parameter>
 982     is <symbol>NULL</symbol>
 983   </para>
 984  </refsect1>
 985 </refentry>
 986
 987 <!-- *********************************************** -->
 988
 989 <refentry id="spi-spi-execute-plan">
 990  <refmeta>
 991   <refentrytitle>SPI_execute_plan</refentrytitle>
 992  </refmeta>
 993
 994  <refnamediv>
 995   <refname>SPI_execute_plan</refname>
 996   <refpurpose>execute a plan prepared by <function>SPI_prepare</function></refpurpose>
 997  </refnamediv>
 998
 999  <indexterm><primary>SPI_execute_plan</primary></indexterm>
1000
1001  <refsynopsisdiv>
1002 <synopsis>
1003 int SPI_execute_plan(void * <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
1004                      bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
1005 </synopsis>
1006  </refsynopsisdiv>
1007
1008  <refsect1>
1009   <title>Description</title>
1010
1011   <para>
1012    <function>SPI_execute_plan</function> executes a plan prepared by
1013    <function>SPI_prepare</function>.  <parameter>read_only</parameter> and
1014    <parameter>count</parameter> have the same interpretation as in
1015    <function>SPI_execute</function>.
1016   </para>
1017  </refsect1>
1018
1019  <refsect1>
1020   <title>Arguments</title>
1021
1022   <variablelist>
1023    <varlistentry>
1024     <term><literal>void * <parameter>plan</parameter></literal></term>
1025     <listitem>
1026      <para>
1027       execution plan (returned by <function>SPI_prepare</function>)
1028      </para>
1029     </listitem>
1030    </varlistentry>
1031
1032    <varlistentry>
1033     <term><literal>Datum * <parameter>values</parameter></literal></term>
1034     <listitem>
1035      <para>
1036       An array of actual parameter values.  Must have same length as the
1037       plan's number of arguments.
1038      </para>
1039     </listitem>
1040    </varlistentry>
1041
1042    <varlistentry>
1043     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1044     <listitem>
1045      <para>
1046       An array describing which parameters are null.  Must have same length as
1047       the plan's number of arguments.
1048       <literal>n</literal> indicates a null value (entry in
1049       <parameter>values</> will be ignored); a space indicates a
1050       nonnull value (entry in <parameter>values</> is valid).
1051      </para>
1052
1053      <para>
1054       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1055       <function>SPI_execute_plan</function> assumes that no parameters are
1056       null.
1057      </para>
1058     </listitem>
1059    </varlistentry>
1060
1061    <varlistentry>
1062     <term><literal>bool <parameter>read_only</parameter></literal></term>
1063     <listitem>
1064      <para>
1065       <literal>true</> for read-only execution
1066      </para>
1067     </listitem>
1068    </varlistentry>
1069
1070    <varlistentry>
1071     <term><literal>long <parameter>count</parameter></literal></term>
1072     <listitem>
1073      <para>
1074       maximum number of rows to process or return
1075      </para>
1076     </listitem>
1077    </varlistentry>
1078   </variablelist>
1079  </refsect1>
1080
1081  <refsect1>
1082   <title>Return Value</title>
1083
1084   <para>
1085    The return value is the same as for <function>SPI_execute</function>,
1086    with the following additional possible error (negative) results:
1087
1088    <variablelist>
1089     <varlistentry>
1090      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
1091      <listitem>
1092       <para>
1093        if <parameter>plan</parameter> is <symbol>NULL</symbol> or
1094        <parameter>count</parameter> is less than 0
1095       </para>
1096      </listitem>
1097     </varlistentry>
1098
1099     <varlistentry>
1100      <term><symbol>SPI_ERROR_PARAM</symbol></term>
1101      <listitem>
1102       <para>
1103        if <parameter>values</parameter> is <symbol>NULL</symbol> and
1104        <parameter>plan</parameter> was prepared with some parameters
1105       </para>
1106      </listitem>
1107     </varlistentry>
1108    </variablelist>
1109   </para>
1110
1111   <para>
1112    <varname>SPI_processed</varname> and
1113    <varname>SPI_tuptable</varname> are set as in
1114    <function>SPI_execute</function> if successful.
1115   </para>
1116  </refsect1>
1117
1118  <refsect1>
1119   <title>Notes</title>
1120
1121   <para>
1122    If one of the objects (a table, function, etc.) referenced by the
1123    prepared plan is dropped during the session then the result of
1124    <function>SPI_execute_plan</function> for this plan will be unpredictable.
1125   </para>
1126  </refsect1>
1127 </refentry>
1128
1129 <!-- *********************************************** -->
1130
1131 <refentry id="spi-spi-execp">
1132  <refmeta>
1133   <refentrytitle>SPI_execp</refentrytitle>
1134  </refmeta>
1135
1136  <refnamediv>
1137   <refname>SPI_execp</refname>
1138   <refpurpose>execute a plan in read/write mode</refpurpose>
1139  </refnamediv>
1140
1141  <indexterm><primary>SPI_execp</primary></indexterm>
1142
1143  <refsynopsisdiv>
1144 <synopsis>
1145 int SPI_execp(void * <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, long <parameter>count</parameter>)
1146 </synopsis>
1147  </refsynopsisdiv>
1148
1149  <refsect1>
1150   <title>Description</title>
1151
1152   <para>
1153    <function>SPI_execp</function> is the same as
1154    <function>SPI_execute_plan</function>, with the latter's
1155    <parameter>read_only</parameter> parameter always taken as
1156    <literal>false</>.
1157   </para>
1158  </refsect1>
1159
1160  <refsect1>
1161   <title>Arguments</title>
1162
1163   <variablelist>
1164    <varlistentry>
1165     <term><literal>void * <parameter>plan</parameter></literal></term>
1166     <listitem>
1167      <para>
1168       execution plan (returned by <function>SPI_prepare</function>)
1169      </para>
1170     </listitem>
1171    </varlistentry>
1172
1173    <varlistentry>
1174     <term><literal>Datum * <parameter>values</parameter></literal></term>
1175     <listitem>
1176      <para>
1177       An array of actual parameter values.  Must have same length as the
1178       plan's number of arguments.
1179      </para>
1180     </listitem>
1181    </varlistentry>
1182
1183    <varlistentry>
1184     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1185     <listitem>
1186      <para>
1187       An array describing which parameters are null.  Must have same length as
1188       the plan's number of arguments.
1189       <literal>n</literal> indicates a null value (entry in
1190       <parameter>values</> will be ignored); a space indicates a
1191       nonnull value (entry in <parameter>values</> is valid).
1192      </para>
1193
1194      <para>
1195       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1196       <function>SPI_execp</function> assumes that no parameters are
1197       null.
1198      </para>
1199     </listitem>
1200    </varlistentry>
1201
1202    <varlistentry>
1203     <term><literal>long <parameter>count</parameter></literal></term>
1204     <listitem>
1205      <para>
1206       maximum number of rows to process or return
1207      </para>
1208     </listitem>
1209    </varlistentry>
1210   </variablelist>
1211  </refsect1>
1212
1213  <refsect1>
1214   <title>Return Value</title>
1215
1216   <para>
1217    See <function>SPI_execute_plan</function>.
1218   </para>
1219
1220   <para>
1221    <varname>SPI_processed</varname> and
1222    <varname>SPI_tuptable</varname> are set as in
1223    <function>SPI_execute</function> if successful.
1224   </para>
1225  </refsect1>
1226 </refentry>
1227
1228 <!-- *********************************************** -->
1229
1230 <refentry id="spi-spi-cursor-open">
1231  <refmeta>
1232   <refentrytitle>SPI_cursor_open</refentrytitle>
1233  </refmeta>
1234
1235  <refnamediv>
1236   <refname>SPI_cursor_open</refname>
1237   <refpurpose>set up a cursor using a plan created with <function>SPI_prepare</function></refpurpose>
1238  </refnamediv>
1239
1240  <indexterm><primary>SPI_cursor_open</primary></indexterm>
1241
1242  <refsynopsisdiv>
1243 <synopsis>
1244 Portal SPI_cursor_open(const char * <parameter>name</parameter>, void * <parameter>plan</parameter>,
1245                        Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
1246                        bool <parameter>read_only</parameter>)
1247 </synopsis>
1248  </refsynopsisdiv>
1249
1250  <refsect1>
1251   <title>Description</title>
1252
1253   <para>
1254    <function>SPI_cursor_open</function> sets up a cursor (internally,
1255    a portal) that will execute a plan prepared by
1256    <function>SPI_prepare</function>.  The parameters have the same
1257    meanings as the corresponding parameters to
1258    <function>SPI_execute_plan</function>.
1259   </para>
1260
1261   <para>
1262    Using a cursor instead of executing the plan directly has two
1263    benefits.  First, the result rows can be retrieved a few at a time,
1264    avoiding memory overrun for queries that return many rows.  Second,
1265    a portal can outlive the current procedure (it can, in fact, live
1266    to the end of the current transaction).  Returning the portal name
1267    to the procedure's caller provides a way of returning a row set as
1268    result.
1269   </para>
1270  </refsect1>
1271
1272  <refsect1>
1273   <title>Arguments</title>
1274
1275   <variablelist>
1276    <varlistentry>
1277     <term><literal>const char * <parameter>name</parameter></literal></term>
1278     <listitem>
1279      <para>
1280       name for portal, or <symbol>NULL</symbol> to let the system
1281       select a name
1282      </para>
1283     </listitem>
1284    </varlistentry>
1285
1286    <varlistentry>
1287     <term><literal>void * <parameter>plan</parameter></literal></term>
1288     <listitem>
1289      <para>
1290       execution plan (returned by <function>SPI_prepare</function>)
1291      </para>
1292     </listitem>
1293    </varlistentry>
1294
1295    <varlistentry>
1296     <term><literal>Datum * <parameter>values</parameter></literal></term>
1297     <listitem>
1298      <para>
1299       An array of actual parameter values.  Must have same length as the
1300       plan's number of arguments.
1301      </para>
1302     </listitem>
1303    </varlistentry>
1304
1305    <varlistentry>
1306     <term><literal>const char * <parameter>nulls</parameter></literal></term>
1307     <listitem>
1308      <para>
1309       An array describing which parameters are null.  Must have same length as
1310       the plan's number of arguments.
1311       <literal>n</literal> indicates a null value (entry in
1312       <parameter>values</> will be ignored); a space indicates a
1313       nonnull value (entry in <parameter>values</> is valid).
1314      </para>
1315
1316      <para>
1317       If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1318       <function>SPI_cursor_open</function> assumes that no parameters are
1319       null.
1320      </para>
1321     </listitem>
1322    </varlistentry>
1323
1324    <varlistentry>
1325     <term><literal>bool <parameter>read_only</parameter></literal></term>
1326     <listitem>
1327      <para>
1328       <literal>true</> for read-only execution
1329      </para>
1330     </listitem>
1331    </varlistentry>
1332   </variablelist>
1333  </refsect1>
1334
1335  <refsect1>
1336   <title>Return Value</title>
1337
1338   <para>
1339    pointer to portal containing the cursor, or <symbol>NULL</symbol>
1340    on error
1341   </para>
1342  </refsect1>
1343 </refentry>
1344
1345 <!-- *********************************************** -->
1346
1347 <refentry id="spi-spi-cursor-find">
1348  <refmeta>
1349   <refentrytitle>SPI_cursor_find</refentrytitle>
1350  </refmeta>
1351
1352  <refnamediv>
1353   <refname>SPI_cursor_find</refname>
1354   <refpurpose>find an existing cursor by name</refpurpose>
1355  </refnamediv>
1356
1357  <indexterm><primary>SPI_cursor_find</primary></indexterm>
1358
1359  <refsynopsisdiv>
1360 <synopsis>
1361 Portal SPI_cursor_find(const char * <parameter>name</parameter>)
1362 </synopsis>
1363  </refsynopsisdiv>
1364
1365  <refsect1>
1366   <title>Description</title>
1367
1368   <para>
1369    <function>SPI_cursor_find</function> finds an existing portal by
1370    name.  This is primarily useful to resolve a cursor name returned
1371    as text by some other function.
1372   </para>
1373  </refsect1>
1374
1375  <refsect1>
1376   <title>Arguments</title>
1377
1378   <variablelist>
1379    <varlistentry>
1380     <term><literal>const char * <parameter>name</parameter></literal></term>
1381     <listitem>
1382      <para>
1383       name of the portal
1384      </para>
1385     </listitem>
1386    </varlistentry>
1387   </variablelist>
1388  </refsect1>
1389
1390  <refsect1>
1391   <title>Return Value</title>
1392
1393   <para>
1394    pointer to the portal with the specified name, or
1395    <symbol>NULL</symbol> if none was found
1396   </para>
1397  </refsect1>
1398 </refentry>
1399
1400 <!-- *********************************************** -->
1401
1402 <refentry id="spi-spi-cursor-fetch">
1403  <refmeta>
1404   <refentrytitle>SPI_cursor_fetch</refentrytitle>
1405  </refmeta>
1406
1407  <refnamediv>
1408   <refname>SPI_cursor_fetch</refname>
1409   <refpurpose>fetch some rows from a cursor</refpurpose>
1410  </refnamediv>
1411
1412  <indexterm><primary>SPI_cursor_fetch</primary></indexterm>
1413
1414  <refsynopsisdiv>
1415 <synopsis>
1416 void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
1417 </synopsis>
1418  </refsynopsisdiv>
1419
1420  <refsect1>
1421   <title>Description</title>
1422
1423   <para>
1424    <function>SPI_cursor_fetch</function> fetches some rows from a
1425    cursor.  This is equivalent to the SQL command <command>FETCH</>.
1426   </para>
1427  </refsect1>
1428
1429  <refsect1>
1430   <title>Arguments</title>
1431
1432   <variablelist>
1433    <varlistentry>
1434     <term><literal>Portal <parameter>portal</parameter></literal></term>
1435     <listitem>
1436      <para>
1437       portal containing the cursor
1438      </para>
1439     </listitem>
1440    </varlistentry>
1441
1442    <varlistentry>
1443     <term><literal>bool <parameter>forward</parameter></literal></term>
1444     <listitem>
1445      <para>
1446       true for fetch forward, false for fetch backward
1447      </para>
1448     </listitem>
1449    </varlistentry>
1450
1451    <varlistentry>
1452     <term><literal>long <parameter>count</parameter></literal></term>
1453     <listitem>
1454      <para>
1455       maximum number of rows to fetch
1456      </para>
1457     </listitem>
1458    </varlistentry>
1459   </variablelist>
1460  </refsect1>
1461
1462  <refsect1>
1463   <title>Return Value</title>
1464
1465   <para>
1466    <varname>SPI_processed</varname> and
1467    <varname>SPI_tuptable</varname> are set as in
1468    <function>SPI_execute</function> if successful.
1469   </para>
1470  </refsect1>
1471 </refentry>
1472
1473 <!-- *********************************************** -->
1474
1475 <refentry id="spi-spi-cursor-move">
1476  <refmeta>
1477   <refentrytitle>SPI_cursor_move</refentrytitle>
1478  </refmeta>
1479
1480  <refnamediv>
1481   <refname>SPI_cursor_move</refname>
1482   <refpurpose>move a cursor</refpurpose>
1483  </refnamediv>
1484
1485  <indexterm><primary>SPI_cursor_move</primary></indexterm>
1486
1487  <refsynopsisdiv>
1488 <synopsis>
1489 void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
1490 </synopsis>
1491  </refsynopsisdiv>
1492
1493  <refsect1>
1494   <title>Description</title>
1495
1496   <para>
1497    <function>SPI_cursor_move</function> skips over some number of rows
1498    in a cursor.  This is equivalent to the SQL command
1499    <command>MOVE</>.
1500   </para>
1501  </refsect1>
1502
1503  <refsect1>
1504   <title>Arguments</title>
1505
1506   <variablelist>
1507    <varlistentry>
1508     <term><literal>Portal <parameter>portal</parameter></literal></term>
1509     <listitem>
1510      <para>
1511       portal containing the cursor
1512      </para>
1513     </listitem>
1514    </varlistentry>
1515
1516    <varlistentry>
1517     <term><literal>bool <parameter>forward</parameter></literal></term>
1518     <listitem>
1519      <para>
1520       true for move forward, false for move backward
1521      </para>
1522     </listitem>
1523    </varlistentry>
1524
1525    <varlistentry>
1526     <term><literal>long <parameter>count</parameter></literal></term>
1527     <listitem>
1528      <para>
1529       maximum number of rows to move
1530      </para>
1531     </listitem>
1532    </varlistentry>
1533   </variablelist>
1534  </refsect1>
1535 </refentry>
1536
1537 <!-- *********************************************** -->
1538
1539 <refentry id="spi-spi-cursor-close">
1540  <refmeta>
1541   <refentrytitle>SPI_cursor_close</refentrytitle>
1542  </refmeta>
1543
1544  <refnamediv>
1545   <refname>SPI_cursor_close</refname>
1546   <refpurpose>close a cursor</refpurpose>
1547  </refnamediv>
1548
1549  <indexterm><primary>SPI_cursor_close</primary></indexterm>
1550
1551  <refsynopsisdiv>
1552 <synopsis>
1553 void SPI_cursor_close(Portal <parameter>portal</parameter>)
1554 </synopsis>
1555  </refsynopsisdiv>
1556
1557  <refsect1>
1558   <title>Description</title>
1559
1560   <para>
1561    <function>SPI_cursor_close</function> closes a previously created
1562    cursor and releases its portal storage.
1563   </para>
1564
1565   <para>
1566    All open cursors are closed automatically at the end of a
1567    transaction.  <function>SPI_cursor_close</function> need only be
1568    invoked if it is desirable to release resources sooner.
1569   </para>
1570  </refsect1>
1571
1572  <refsect1>
1573   <title>Arguments</title>
1574
1575   <variablelist>
1576    <varlistentry>
1577     <term><literal>Portal <parameter>portal</parameter></literal></term>
1578     <listitem>
1579      <para>
1580       portal containing the cursor
1581      </para>
1582     </listitem>
1583    </varlistentry>
1584   </variablelist>
1585  </refsect1>
1586 </refentry>
1587
1588 <!-- *********************************************** -->
1589
1590 <refentry id="spi-spi-saveplan">
1591  <refmeta>
1592   <refentrytitle>SPI_saveplan</refentrytitle>
1593  </refmeta>
1594
1595  <refnamediv>
1596   <refname>SPI_saveplan</refname>
1597   <refpurpose>save a plan</refpurpose>
1598  </refnamediv>
1599
1600  <indexterm><primary>SPI_saveplan</primary></indexterm>
1601
1602  <refsynopsisdiv>
1603 <synopsis>
1604 void * SPI_saveplan(void * <parameter>plan</parameter>)
1605 </synopsis>
1606  </refsynopsisdiv>
1607
1608  <refsect1>
1609   <title>Description</title>
1610
1611   <para>
1612    <function>SPI_saveplan</function> saves a passed plan (prepared by
1613    <function>SPI_prepare</function>) in memory protected from freeing
1614    by <function>SPI_finish</function> and by the transaction manager
1615    and returns a pointer to the saved plan.  This gives you the
1616    ability to reuse prepared plans in the subsequent invocations of
1617    your procedure in the current session.
1618   </para>
1619  </refsect1>
1620
1621  <refsect1>
1622   <title>Arguments</title>
1623
1624   <variablelist>
1625    <varlistentry>
1626     <term><literal>void * <parameter>plan</parameter></literal></term>
1627     <listitem>
1628      <para>
1629       the plan to be saved
1630      </para>
1631     </listitem>
1632    </varlistentry>
1633   </variablelist>
1634  </refsect1>
1635
1636  <refsect1>
1637   <title>Return Value</title>
1638
1639   <para>
1640    Pointer to the saved plan; <symbol>NULL</symbol> if unsuccessful.
1641    On error, <varname>SPI_result</varname> is set thus:
1642
1643    <variablelist>
1644     <varlistentry>
1645      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
1646      <listitem>
1647       <para>
1648        if <parameter>plan</parameter> is <symbol>NULL</symbol>
1649       </para>
1650      </listitem>
1651     </varlistentry>
1652
1653     <varlistentry>
1654      <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
1655      <listitem>
1656       <para>
1657        if called from an unconnected procedure
1658       </para>
1659      </listitem>
1660     </varlistentry>
1661    </variablelist>
1662   </para>
1663  </refsect1>
1664
1665  <refsect1>
1666   <title>Notes</title>
1667
1668   <para>
1669    If one of the objects (a table, function, etc.) referenced by the
1670    prepared plan is dropped during the session then the results of
1671    <function>SPI_execute_plan</function> for this plan will be unpredictable.
1672   </para>
1673  </refsect1>
1674 </refentry>
1675
1676 </sect1>
1677
1678 <sect1 id="spi-interface-support">
1679  <title>Interface Support Functions</title>
1680
1681  <para>
1682   The functions described here provide an interface for extracting
1683   information from result sets returned by <function>SPI_execute</> and
1684   other SPI functions.
1685  </para>
1686
1687  <para>
1688   All functions described in this section may be used by both
1689   connected and unconnected procedures.
1690  </para>
1691
1692 <!-- *********************************************** -->
1693
1694 <refentry id="spi-spi-fname">
1695  <refmeta>
1696   <refentrytitle>SPI_fname</refentrytitle>
1697  </refmeta>
1698
1699  <refnamediv>
1700   <refname>SPI_fname</refname>
1701   <refpurpose>determine the column name for the specified column number</refpurpose>
1702  </refnamediv>
1703
1704  <indexterm><primary>SPI_fname</primary></indexterm>
1705
1706  <refsynopsisdiv>
1707 <synopsis>
1708 char * SPI_fname(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
1709 </synopsis>
1710  </refsynopsisdiv>
1711
1712  <refsect1>
1713   <title>Description</title>
1714
1715   <para>
1716    <function>SPI_fname</function> returns a copy of the column name of the
1717    specified column.  (You can use <function>pfree</function> to
1718    release the copy of the name when you don't need it anymore.)
1719   </para>
1720  </refsect1>
1721
1722  <refsect1>
1723   <title>Arguments</title>
1724
1725   <variablelist>
1726    <varlistentry>
1727     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1728     <listitem>
1729      <para>
1730       input row description
1731      </para>
1732     </listitem>
1733    </varlistentry>
1734
1735    <varlistentry>
1736     <term><literal>int <parameter>colnumber</parameter></literal></term>
1737     <listitem>
1738      <para>
1739       column number (count starts at 1)
1740      </para>
1741     </listitem>
1742    </varlistentry>
1743   </variablelist>
1744  </refsect1>
1745
1746  <refsect1>
1747   <title>Return Value</title>
1748
1749   <para>
1750    The column name; <symbol>NULL</symbol> if
1751    <parameter>colnumber</parameter> is out of range.
1752    <varname>SPI_result</varname> set to
1753    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
1754   </para>
1755  </refsect1>
1756 </refentry>
1757
1758 <!-- *********************************************** -->
1759
1760 <refentry id="spi-spi-fnumber">
1761  <refmeta>
1762   <refentrytitle>SPI_fnumber</refentrytitle>
1763  </refmeta>
1764
1765  <refnamediv>
1766   <refname>SPI_fnumber</refname>
1767   <refpurpose>determine the column number for the specified column name</refpurpose>
1768  </refnamediv>
1769
1770  <indexterm><primary>SPI_fnumber</primary></indexterm>
1771
1772  <refsynopsisdiv>
1773 <synopsis>
1774 int SPI_fnumber(TupleDesc <parameter>rowdesc</parameter>, const char * <parameter>colname</parameter>)
1775 </synopsis>
1776  </refsynopsisdiv>
1777
1778  <refsect1>
1779   <title>Description</title>
1780
1781   <para>
1782    <function>SPI_fnumber</function> returns the column number for the
1783    column with the specified name.
1784   </para>
1785
1786   <para>
1787    If <parameter>colname</parameter> refers to a system column (e.g.,
1788    <literal>oid</>) then the appropriate negative column number will
1789    be returned.  The caller should be careful to test the return value
1790    for exact equality to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> to
1791    detect an error; testing the result for less than or equal to 0 is
1792    not correct unless system columns should be rejected.
1793   </para>
1794  </refsect1>
1795
1796  <refsect1>
1797   <title>Arguments</title>
1798
1799   <variablelist>
1800    <varlistentry>
1801     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1802     <listitem>
1803      <para>
1804       input row description
1805      </para>
1806     </listitem>
1807    </varlistentry>
1808
1809    <varlistentry>
1810     <term><literal>const char * <parameter>colname</parameter></literal></term>
1811     <listitem>
1812      <para>
1813       column name
1814      </para>
1815     </listitem>
1816    </varlistentry>
1817   </variablelist>
1818  </refsect1>
1819
1820  <refsect1>
1821   <title>Return Value</title>
1822
1823   <para>
1824    Column number (count starts at 1), or
1825    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> if the named column was not
1826    found.
1827   </para>
1828  </refsect1>
1829 </refentry>
1830
1831 <!-- *********************************************** -->
1832
1833 <refentry id="spi-spi-getvalue">
1834  <refmeta>
1835   <refentrytitle>SPI_getvalue</refentrytitle>
1836  </refmeta>
1837
1838  <refnamediv>
1839   <refname>SPI_getvalue</refname>
1840   <refpurpose>return the string value of the specified column</refpurpose>
1841  </refnamediv>
1842
1843  <indexterm><primary>SPI_getvalue</primary></indexterm>
1844
1845  <refsynopsisdiv>
1846 <synopsis>
1847 char * SPI_getvalue(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
1848 </synopsis>
1849  </refsynopsisdiv>
1850
1851  <refsect1>
1852   <title>Description</title>
1853
1854   <para>
1855    <function>SPI_getvalue</function> returns the string representation
1856    of the value of the specified column.
1857   </para>
1858
1859   <para>
1860    The result is returned in memory allocated using
1861    <function>palloc</function>.  (You can use
1862    <function>pfree</function> to release the memory when you don't
1863    need it anymore.)
1864   </para>
1865  </refsect1>
1866
1867  <refsect1>
1868   <title>Arguments</title>
1869
1870   <variablelist>
1871    <varlistentry>
1872     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
1873     <listitem>
1874      <para>
1875       input row to be examined
1876      </para>
1877     </listitem>
1878    </varlistentry>
1879
1880    <varlistentry>
1881     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1882     <listitem>
1883      <para>
1884       input row description
1885      </para>
1886     </listitem>
1887    </varlistentry>
1888
1889    <varlistentry>
1890     <term><literal>int <parameter>colnumber</parameter></literal></term>
1891     <listitem>
1892      <para>
1893       column number (count starts at 1)
1894      </para>
1895     </listitem>
1896    </varlistentry>
1897   </variablelist>
1898  </refsect1>
1899
1900  <refsect1>
1901   <title>Return Value</title>
1902
1903   <para>
1904    Column value, or <symbol>NULL</symbol> if the column is null,
1905    <parameter>colnumber</parameter> is out of range
1906    (<varname>SPI_result</varname> is set to
1907    <symbol>SPI_ERROR_NOATTRIBUTE</symbol>), or no no output function
1908    available (<varname>SPI_result</varname> is set to
1909    <symbol>SPI_ERROR_NOOUTFUNC</symbol>).
1910   </para>
1911  </refsect1>
1912 </refentry>
1913
1914 <!-- *********************************************** -->
1915
1916 <refentry id="spi-spi-getbinval">
1917  <refmeta>
1918   <refentrytitle>SPI_getbinval</refentrytitle>
1919  </refmeta>
1920
1921  <refnamediv>
1922   <refname>SPI_getbinval</refname>
1923   <refpurpose>return the binary value of the specified column</refpurpose>
1924  </refnamediv>
1925
1926  <indexterm><primary>SPI_getbinval</primary></indexterm>
1927
1928  <refsynopsisdiv>
1929 <synopsis>
1930 Datum SPI_getbinval(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>, bool * <parameter>isnull</parameter>)
1931 </synopsis>
1932  </refsynopsisdiv>
1933
1934  <refsect1>
1935   <title>Description</title>
1936
1937   <para>
1938    <function>SPI_getbinval</function> returns the value of the
1939    specified column in the internal form (as type <type>Datum</type>).
1940   </para>
1941
1942   <para>
1943    This function does not allocate new space for the datum.  In the
1944    case of a pass-by-reference data type, the return value will be a
1945    pointer into the passed row.
1946   </para>
1947  </refsect1>
1948
1949  <refsect1>
1950   <title>Arguments</title>
1951
1952   <variablelist>
1953    <varlistentry>
1954     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
1955     <listitem>
1956      <para>
1957       input row to be examined
1958      </para>
1959     </listitem>
1960    </varlistentry>
1961
1962    <varlistentry>
1963     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
1964     <listitem>
1965      <para>
1966       input row description
1967      </para>
1968     </listitem>
1969    </varlistentry>
1970
1971    <varlistentry>
1972     <term><literal>int <parameter>colnumber</parameter></literal></term>
1973     <listitem>
1974      <para>
1975       column number (count starts at 1)
1976      </para>
1977     </listitem>
1978    </varlistentry>
1979
1980    <varlistentry>
1981     <term><literal>bool * <parameter>isnull</parameter></literal></term>
1982     <listitem>
1983      <para>
1984       flag for a null value in the column
1985      </para>
1986     </listitem>
1987    </varlistentry>
1988   </variablelist>
1989  </refsect1>
1990
1991  <refsect1>
1992   <title>Return Value</title>
1993
1994   <para>
1995    The binary value of the column is returned.  The variable pointed
1996    to by <parameter>isnull</parameter> is set to true if the column is
1997    null, else to false.
1998   </para>
1999
2000   <para>
2001    <varname>SPI_result</varname> is set to
2002    <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2003   </para>
2004  </refsect1>
2005 </refentry>
2006
2007 <!-- *********************************************** -->
2008
2009 <refentry id="spi-spi-gettype">
2010  <refmeta>
2011   <refentrytitle>SPI_gettype</refentrytitle>
2012  </refmeta>
2013
2014  <refnamediv>
2015   <refname>SPI_gettype</refname>
2016   <refpurpose>return the data type name of the specified column</refpurpose>
2017  </refnamediv>
2018
2019  <indexterm><primary>SPI_gettype</primary></indexterm>
2020
2021  <refsynopsisdiv>
2022 <synopsis>
2023 char * SPI_gettype(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2024 </synopsis>
2025  </refsynopsisdiv>
2026
2027  <refsect1>
2028   <title>Description</title>
2029
2030   <para>
2031    <function>SPI_gettype</function> returns a copy of the data type name of the
2032    specified column.  (You can use <function>pfree</function> to
2033    release the copy of the name when you don't need it anymore.)
2034   </para>
2035  </refsect1>
2036
2037  <refsect1>
2038   <title>Arguments</title>
2039
2040   <variablelist>
2041    <varlistentry>
2042     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2043     <listitem>
2044      <para>
2045       input row description
2046      </para>
2047     </listitem>
2048    </varlistentry>
2049
2050    <varlistentry>
2051     <term><literal>int <parameter>colnumber</parameter></literal></term>
2052     <listitem>
2053      <para>
2054       column number (count starts at 1)
2055      </para>
2056     </listitem>
2057    </varlistentry>
2058   </variablelist>
2059  </refsect1>
2060
2061  <refsect1>
2062   <title>Return Value</title>
2063
2064   <para>
2065    The data type name of the specified column, or
2066    <symbol>NULL</symbol> on error.  <varname>SPI_result</varname> is
2067    set to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2068   </para>
2069  </refsect1>
2070 </refentry>
2071
2072 <!-- *********************************************** -->
2073
2074 <refentry id="spi-spi-gettypeid">
2075  <refmeta>
2076   <refentrytitle>SPI_gettypeid</refentrytitle>
2077  </refmeta>
2078
2079  <refnamediv>
2080   <refname>SPI_gettypeid</refname>
2081   <refpurpose>return the data type <acronym>OID</acronym> of the specified column</refpurpose>
2082  </refnamediv>
2083
2084  <indexterm><primary>SPI_gettypeid</primary></indexterm>
2085
2086  <refsynopsisdiv>
2087 <synopsis>
2088 Oid SPI_gettypeid(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2089 </synopsis>
2090  </refsynopsisdiv>
2091
2092  <refsect1>
2093   <title>Description</title>
2094
2095   <para>
2096    <function>SPI_gettypeid</function> returns the
2097    <acronym>OID</acronym> of the data type of the specified column.
2098   </para>
2099  </refsect1>
2100
2101  <refsect1>
2102   <title>Arguments</title>
2103
2104   <variablelist>
2105    <varlistentry>
2106     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2107     <listitem>
2108      <para>
2109       input row description
2110      </para>
2111     </listitem>
2112    </varlistentry>
2113
2114    <varlistentry>
2115     <term><literal>int <parameter>colnumber</parameter></literal></term>
2116     <listitem>
2117      <para>
2118       column number (count starts at 1)
2119      </para>
2120     </listitem>
2121    </varlistentry>
2122   </variablelist>
2123  </refsect1>
2124
2125  <refsect1>
2126   <title>Return Value</title>
2127
2128   <para>
2129    The <acronym>OID</acronym> of the data type of the specified column
2130    or <symbol>InvalidOid</symbol> on error.  On error,
2131    <varname>SPI_result</varname> is set to
2132    <symbol>SPI_ERROR_NOATTRIBUTE</symbol>.
2133   </para>
2134  </refsect1>
2135 </refentry>
2136
2137 <!-- *********************************************** -->
2138
2139 <refentry id="spi-spi-getrelname">
2140  <refmeta>
2141   <refentrytitle>SPI_getrelname</refentrytitle>
2142  </refmeta>
2143
2144  <refnamediv>
2145   <refname>SPI_getrelname</refname>
2146   <refpurpose>return the name of the specified relation</refpurpose>
2147  </refnamediv>
2148
2149  <indexterm><primary>SPI_getrelname</primary></indexterm>
2150
2151  <refsynopsisdiv>
2152 <synopsis>
2153 char * SPI_getrelname(Relation <parameter>rel</parameter>)
2154 </synopsis>
2155  </refsynopsisdiv>
2156
2157  <refsect1>
2158   <title>Description</title>
2159
2160   <para>
2161    <function>SPI_getrelname</function> returns a copy of the name of the
2162    specified relation.  (You can use <function>pfree</function> to
2163    release the copy of the name when you don't need it anymore.)
2164   </para>
2165  </refsect1>
2166
2167  <refsect1>
2168   <title>Arguments</title>
2169
2170   <variablelist>
2171    <varlistentry>
2172     <term><literal>Relation <parameter>rel</parameter></literal></term>
2173     <listitem>
2174      <para>
2175       input relation
2176      </para>
2177     </listitem>
2178    </varlistentry>
2179   </variablelist>
2180  </refsect1>
2181
2182  <refsect1>
2183   <title>Return Value</title>
2184
2185   <para>
2186    The name of the specified relation.
2187   </para>
2188  </refsect1>
2189 </refentry>
2190
2191 <refentry id="spi-spi-getnspname">
2192  <refmeta>
2193   <refentrytitle>SPI_getnspname</refentrytitle>
2194  </refmeta>
2195
2196  <refnamediv>
2197   <refname>SPI_getnspname</refname>
2198   <refpurpose>return the namespace of the specified relation</refpurpose>
2199  </refnamediv>
2200
2201  <indexterm><primary>SPI_getnspname</primary></indexterm>
2202
2203  <refsynopsisdiv>
2204 <synopsis>
2205 char * SPI_getnspname(Relation <parameter>rel</parameter>)
2206 </synopsis>
2207  </refsynopsisdiv>
2208
2209  <refsect1>
2210   <title>Description</title>
2211
2212   <para>
2213    <function>SPI_getnspname</function> returns a copy of the name of
2214    the namespace that the specified <structname>Relation</structname>
2215    belongs to. This is equivalent to the relation's schema. You should
2216    <function>pfree</function> the return value of this function when
2217    you are finished with it.
2218   </para>
2219  </refsect1>
2220
2221  <refsect1>
2222   <title>Arguments</title>
2223
2224   <variablelist>
2225    <varlistentry>
2226     <term><literal>Relation <parameter>rel</parameter></literal></term>
2227     <listitem>
2228      <para>
2229       input relation
2230      </para>
2231     </listitem>
2232    </varlistentry>
2233   </variablelist>
2234  </refsect1>
2235
2236  <refsect1>
2237   <title>Return Value</title>
2238
2239   <para>
2240    The name of the specified relation's namespace.
2241   </para>
2242  </refsect1>
2243 </refentry>
2244
2245  </sect1>
2246
2247  <sect1 id="spi-memory">
2248   <title>Memory Management</title>
2249
2250   <para>
2251    <productname>PostgreSQL</productname> allocates memory within
2252    <firstterm>memory contexts</firstterm><indexterm><primary>memory
2253    context</primary><secondary>in SPI</secondary></indexterm>, which provide a convenient method of
2254    managing allocations made in many different places that need to
2255    live for differing amounts of time.  Destroying a context releases
2256    all the memory that was allocated in it.  Thus, it is not necessary
2257    to keep track of individual objects to avoid memory leaks; instead
2258    only a relatively small number of contexts have to be managed.
2259    <function>palloc</function> and related functions allocate memory
2260    from the <quote>current</> context.
2261   </para>
2262
2263   <para>
2264    <function>SPI_connect</function> creates a new memory context and
2265    makes it current.  <function>SPI_finish</function> restores the
2266    previous current memory context and destroys the context created by
2267    <function>SPI_connect</function>.  These actions ensure that
2268    transient memory allocations made inside your procedure are
2269    reclaimed at procedure exit, avoiding memory leakage.
2270   </para>
2271
2272   <para>
2273    However, if your procedure needs to return an object in allocated
2274    memory (such as a value of a pass-by-reference data type), you
2275    cannot allocate that memory using <function>palloc</function>, at
2276    least not while you are connected to SPI.  If you try, the object
2277    will be deallocated by <function>SPI_finish</function>, and your
2278    procedure will not work reliably.  To solve this problem, use
2279    <function>SPI_palloc</function> to allocate memory for your return
2280    object.  <function>SPI_palloc</function> allocates memory in the
2281    <quote>upper executor context</quote>, that is, the memory context
2282    that was current when <function>SPI_connect</function> was called,
2283    which is precisely the right context for a value returned from your
2284    procedure.
2285   </para>
2286
2287   <para>
2288    If <function>SPI_palloc</function> is called while the procedure is
2289    not connected to SPI, then it acts the same as a normal
2290    <function>palloc</function>.  Before a procedure connects to the
2291    SPI manager, the current memory context is the upper executor
2292    context, so all allocations made by the procedure via
2293    <function>palloc</function> or by SPI utility functions are made in
2294    this context.
2295   </para>
2296
2297   <para>
2298    When <function>SPI_connect</function> is called, the private
2299    context of the procedure, which is created by
2300    <function>SPI_connect</function>, is made the current context.  All
2301    allocations made by <function>palloc</function>,
2302    <function>repalloc</function>, or SPI utility functions (except for
2303    <function>SPI_copytuple</function>,
2304    <function>SPI_returntuple</function>,
2305    <function>SPI_modifytuple</function>, and
2306    <function>SPI_palloc</function>) are made in this context.  When a
2307    procedure disconnects from the SPI manager (via
2308    <function>SPI_finish</function>) the current context is restored to
2309    the upper executor context, and all allocations made in the
2310    procedure memory context are freed and cannot be used any more.
2311   </para>
2312
2313   <para>
2314    All functions described in this section may be used by both
2315    connected and unconnected procedures.  In an unconnected procedure,
2316    they act the same as the underlying ordinary server functions
2317    (<function>palloc</>, etc.).
2318   </para>
2319
2320 <!-- *********************************************** -->
2321
2322 <refentry id="spi-spi-palloc">
2323  <refmeta>
2324   <refentrytitle>SPI_palloc</refentrytitle>
2325  </refmeta>
2326
2327  <refnamediv>
2328   <refname>SPI_palloc</refname>
2329   <refpurpose>allocate memory in the upper executor context</refpurpose>
2330  </refnamediv>
2331
2332  <indexterm><primary>SPI_palloc</primary></indexterm>
2333
2334  <refsynopsisdiv>
2335 <synopsis>
2336 void * SPI_palloc(Size <parameter>size</parameter>)
2337 </synopsis>
2338  </refsynopsisdiv>
2339
2340  <refsect1>
2341   <title>Description</title>
2342
2343   <para>
2344    <function>SPI_palloc</function> allocates memory in the upper
2345    executor context.
2346   </para>
2347  </refsect1>
2348
2349  <refsect1>
2350   <title>Arguments</title>
2351
2352   <variablelist>
2353    <varlistentry>
2354     <term><literal>Size <parameter>size</parameter></literal></term>
2355     <listitem>
2356      <para>
2357       size in bytes of storage to allocate
2358      </para>
2359     </listitem>
2360    </varlistentry>
2361   </variablelist>
2362  </refsect1>
2363
2364  <refsect1>
2365   <title>Return Value</title>
2366
2367   <para>
2368    pointer to new storage space of the specified size
2369   </para>
2370  </refsect1>
2371 </refentry>
2372
2373 <!-- *********************************************** -->
2374
2375 <refentry id="spi-realloc">
2376  <refmeta>
2377   <refentrytitle>SPI_repalloc</refentrytitle>
2378  </refmeta>
2379
2380  <refnamediv>
2381   <refname>SPI_repalloc</refname>
2382   <refpurpose>reallocate memory in the upper executor context</refpurpose>
2383  </refnamediv>
2384
2385  <indexterm><primary>SPI_repalloc</primary></indexterm>
2386
2387  <refsynopsisdiv>
2388 <synopsis>
2389 void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)
2390 </synopsis>
2391  </refsynopsisdiv>
2392
2393  <refsect1>
2394   <title>Description</title>
2395
2396   <para>
2397    <function>SPI_repalloc</function> changes the size of a memory
2398    segment previously allocated using <function>SPI_palloc</function>.
2399   </para>
2400
2401   <para>
2402    This function is no longer different from plain
2403    <function>repalloc</function>.  It's kept just for backward
2404    compatibility of existing code.
2405   </para>
2406  </refsect1>
2407
2408  <refsect1>
2409   <title>Arguments</title>
2410
2411   <variablelist>
2412    <varlistentry>
2413     <term><literal>void * <parameter>pointer</parameter></literal></term>
2414     <listitem>
2415      <para>
2416       pointer to existing storage to change
2417      </para>
2418     </listitem>
2419    </varlistentry>
2420
2421    <varlistentry>
2422     <term><literal>Size <parameter>size</parameter></literal></term>
2423     <listitem>
2424      <para>
2425       size in bytes of storage to allocate
2426      </para>
2427     </listitem>
2428    </varlistentry>
2429   </variablelist>
2430  </refsect1>
2431
2432  <refsect1>
2433   <title>Return Value</title>
2434
2435   <para>
2436    pointer to new storage space of specified size with the contents
2437    copied from the existing area
2438   </para>
2439  </refsect1>
2440 </refentry>
2441
2442 <!-- *********************************************** -->
2443
2444 <refentry id="spi-spi-pfree">
2445  <refmeta>
2446   <refentrytitle>SPI_pfree</refentrytitle>
2447  </refmeta>
2448
2449  <refnamediv>
2450   <refname>SPI_pfree</refname>
2451   <refpurpose>free memory in the upper executor context</refpurpose>
2452  </refnamediv>
2453
2454  <indexterm><primary>SPI_pfree</primary></indexterm>
2455
2456  <refsynopsisdiv>
2457 <synopsis>
2458 void SPI_pfree(void * <parameter>pointer</parameter>)
2459 </synopsis>
2460  </refsynopsisdiv>
2461
2462  <refsect1>
2463   <title>Description</title>
2464
2465   <para>
2466    <function>SPI_pfree</function> frees memory previously allocated
2467    using <function>SPI_palloc</function> or
2468    <function>SPI_repalloc</function>.
2469   </para>
2470
2471   <para>
2472    This function is no longer different from plain
2473    <function>pfree</function>.  It's kept just for backward
2474    compatibility of existing code.
2475   </para>
2476  </refsect1>
2477
2478  <refsect1>
2479   <title>Arguments</title>
2480
2481   <variablelist>
2482    <varlistentry>
2483     <term><literal>void * <parameter>pointer</parameter></literal></term>
2484     <listitem>
2485      <para>
2486       pointer to existing storage to free
2487      </para>
2488     </listitem>
2489    </varlistentry>
2490   </variablelist>
2491  </refsect1>
2492 </refentry>
2493
2494 <!-- *********************************************** -->
2495
2496 <refentry id="spi-spi-copytuple">
2497  <refmeta>
2498   <refentrytitle>SPI_copytuple</refentrytitle>
2499  </refmeta>
2500
2501  <refnamediv>
2502   <refname>SPI_copytuple</refname>
2503   <refpurpose>make a copy of a row in the upper executor context</refpurpose>
2504  </refnamediv>
2505
2506  <indexterm><primary>SPI_copytuple</primary></indexterm>
2507
2508  <refsynopsisdiv>
2509 <synopsis>
2510 HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>)
2511 </synopsis>
2512  </refsynopsisdiv>
2513
2514  <refsect1>
2515   <title>Description</title>
2516
2517   <para>
2518    <function>SPI_copytuple</function> makes a copy of a row in the
2519    upper executor context.  This is normally used to return a modified
2520    row from a trigger.  In a function declared to return a composite
2521    type, use <function>SPI_returntuple</function> instead.
2522   </para>
2523  </refsect1>
2524
2525  <refsect1>
2526   <title>Arguments</title>
2527
2528   <variablelist>
2529    <varlistentry>
2530     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2531     <listitem>
2532      <para>
2533       row to be copied
2534      </para>
2535     </listitem>
2536    </varlistentry>
2537   </variablelist>
2538  </refsect1>
2539
2540  <refsect1>
2541   <title>Return Value</title>
2542
2543   <para>
2544    the copied row; <symbol>NULL</symbol> only if
2545    <parameter>tuple</parameter> is <symbol>NULL</symbol>
2546   </para>
2547  </refsect1>
2548 </refentry>
2549
2550 <!-- *********************************************** -->
2551
2552 <refentry id="spi-spi-returntuple">
2553  <refmeta>
2554   <refentrytitle>SPI_returntuple</refentrytitle>
2555  </refmeta>
2556
2557  <refnamediv>
2558   <refname>SPI_returntuple</refname>
2559   <refpurpose>prepare to return a tuple as a Datum</refpurpose>
2560  </refnamediv>
2561
2562  <indexterm><primary>SPI_returntuple</primary></indexterm>
2563
2564  <refsynopsisdiv>
2565 <synopsis>
2566 HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)
2567 </synopsis>
2568  </refsynopsisdiv>
2569
2570  <refsect1>
2571   <title>Description</title>
2572
2573   <para>
2574    <function>SPI_returntuple</function> makes a copy of a row in
2575    the upper executor context, returning it in the form of a row type <type>Datum</type>.
2576    The returned pointer need only be converted to <type>Datum</type> via <function>PointerGetDatum</function>
2577    before returning.
2578   </para>
2579
2580   <para>
2581    Note that this should be used for functions that are declared to return
2582    composite types.  It is not used for triggers; use
2583    <function>SPI_copytuple</> for returning a modified row in a trigger.
2584   </para>
2585  </refsect1>
2586
2587  <refsect1>
2588   <title>Arguments</title>
2589
2590   <variablelist>
2591    <varlistentry>
2592     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2593     <listitem>
2594      <para>
2595       row to be copied
2596      </para>
2597     </listitem>
2598    </varlistentry>
2599
2600    <varlistentry>
2601     <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2602     <listitem>
2603      <para>
2604       descriptor for row (pass the same descriptor each time for most
2605       effective caching)
2606      </para>
2607     </listitem>
2608    </varlistentry>
2609   </variablelist>
2610  </refsect1>
2611
2612  <refsect1>
2613   <title>Return Value</title>
2614
2615   <para>
2616    <type>HeapTupleHeader</type> pointing to copied row;
2617    <symbol>NULL</symbol> only if
2618    <parameter>row</parameter> or <parameter>rowdesc</parameter> is
2619    <symbol>NULL</symbol>
2620   </para>
2621  </refsect1>
2622 </refentry>
2623
2624 <!-- *********************************************** -->
2625
2626 <refentry id="spi-spi-modifytuple">
2627  <refmeta>
2628   <refentrytitle>SPI_modifytuple</refentrytitle>
2629  </refmeta>
2630
2631  <refnamediv>
2632   <refname>SPI_modifytuple</refname>
2633   <refpurpose>create a row by replacing selected fields of a given row</refpurpose>
2634  </refnamediv>
2635
2636  <indexterm><primary>SPI_modifytuple</primary></indexterm>
2637
2638  <refsynopsisdiv>
2639 <synopsis>
2640 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>)
2641 </synopsis>
2642  </refsynopsisdiv>
2643
2644  <refsect1>
2645   <title>Description</title>
2646
2647   <para>
2648    <function>SPI_modifytuple</function> creates a new row by
2649    substituting new values for selected columns, copying the original
2650    row's columns at other positions.  The input row is not modified.
2651   </para>
2652  </refsect1>
2653
2654  <refsect1>
2655   <title>Arguments</title>
2656
2657   <variablelist>
2658    <varlistentry>
2659     <term><literal>Relation <parameter>rel</parameter></literal></term>
2660     <listitem>
2661      <para>
2662       Used only as the source of the row descriptor for the row.
2663       (Passing a relation rather than a row descriptor is a
2664       misfeature.)
2665      </para>
2666     </listitem>
2667    </varlistentry>
2668
2669    <varlistentry>
2670     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2671     <listitem>
2672      <para>
2673       row to be modified
2674      </para>
2675     </listitem>
2676    </varlistentry>
2677
2678    <varlistentry>
2679     <term><literal>int <parameter>ncols</parameter></literal></term>
2680     <listitem>
2681      <para>
2682       number of column numbers in the array
2683       <parameter>colnum</parameter>
2684      </para>
2685     </listitem>
2686    </varlistentry>
2687
2688    <varlistentry>
2689     <term><literal>int * <parameter>colnum</parameter></literal></term>
2690     <listitem>
2691      <para>
2692       array of the numbers of the columns that are to be changed
2693       (column numbers start at 1)
2694      </para>
2695     </listitem>
2696    </varlistentry>
2697
2698    <varlistentry>
2699     <term><literal>Datum * <parameter>values</parameter></literal></term>
2700     <listitem>
2701      <para>
2702       new values for the specified columns
2703      </para>
2704     </listitem>
2705    </varlistentry>
2706
2707    <varlistentry>
2708     <term><literal>const char * <parameter>Nulls</parameter></literal></term>
2709     <listitem>
2710      <para>
2711       which new values are null, if any (see
2712       <function>SPI_execute_plan</function> for the format)
2713      </para>
2714     </listitem>
2715    </varlistentry>
2716   </variablelist>
2717  </refsect1>
2718
2719  <refsect1>
2720   <title>Return Value</title>
2721
2722   <para>
2723    new row with modifications, allocated in the upper executor
2724    context; <symbol>NULL</symbol> only if <parameter>row</parameter>
2725    is <symbol>NULL</symbol>
2726   </para>
2727
2728   <para>
2729    On error, <varname>SPI_result</varname> is set as follows:
2730    <variablelist>
2731     <varlistentry>
2732      <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
2733      <listitem>
2734       <para>
2735        if <parameter>rel</> is <symbol>NULL</>, or if
2736        <parameter>row</> is <symbol>NULL</>, or if <parameter>ncols</>
2737        is less than or equal to 0, or if <parameter>colnum</> is
2738        <symbol>NULL</>, or if <parameter>values</> is <symbol>NULL</>.
2739       </para>
2740      </listitem>
2741     </varlistentry>
2742
2743     <varlistentry>
2744      <term><symbol>SPI_ERROR_NOATTRIBUTE</symbol></term>
2745      <listitem>
2746       <para>
2747        if <parameter>colnum</> contains an invalid column number (less
2748        than or equal to 0 or greater than the number of column in
2749        <parameter>row</>)
2750       </para>
2751      </listitem>
2752     </varlistentry>
2753    </variablelist>
2754   </para>
2755  </refsect1>
2756 </refentry>
2757
2758 <!-- *********************************************** -->
2759
2760 <refentry id="spi-spi-freetuple">
2761  <refmeta>
2762   <refentrytitle>SPI_freetuple</refentrytitle>
2763  </refmeta>
2764
2765  <refnamediv>
2766   <refname>SPI_freetuple</refname>
2767   <refpurpose>free a row allocated in the upper executor context</refpurpose>
2768  </refnamediv>
2769
2770  <indexterm><primary>SPI_freetuple</primary></indexterm>
2771
2772  <refsynopsisdiv>
2773 <synopsis>
2774 void SPI_freetuple(HeapTuple <parameter>row</parameter>)
2775 </synopsis>
2776  </refsynopsisdiv>
2777
2778  <refsect1>
2779   <title>Description</title>
2780
2781   <para>
2782    <function>SPI_freetuple</function> frees a row previously allocated
2783    in the upper executor context.
2784   </para>
2785
2786   <para>
2787    This function is no longer different from plain
2788    <function>heap_freetuple</function>.  It's kept just for backward
2789    compatibility of existing code.
2790   </para>
2791  </refsect1>
2792
2793  <refsect1>
2794   <title>Arguments</title>
2795
2796   <variablelist>
2797    <varlistentry>
2798     <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2799     <listitem>
2800      <para>
2801       row to free
2802      </para>
2803     </listitem>
2804    </varlistentry>
2805   </variablelist>
2806  </refsect1>
2807 </refentry>
2808
2809 <!-- *********************************************** -->
2810
2811 <refentry id="spi-spi-freetupletable">
2812  <refmeta>
2813   <refentrytitle>SPI_freetuptable</refentrytitle>
2814  </refmeta>
2815
2816  <refnamediv>
2817   <refname>SPI_freetuptable</refname>
2818   <refpurpose>free a row set created by <function>SPI_execute</> or a similar
2819   function</refpurpose>
2820  </refnamediv>
2821
2822  <indexterm><primary>SPI_freetuptable</primary></indexterm>
2823
2824  <refsynopsisdiv>
2825 <synopsis>
2826 void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)
2827 </synopsis>
2828  </refsynopsisdiv>
2829
2830  <refsect1>
2831   <title>Description</title>
2832
2833   <para>
2834    <function>SPI_freetuptable</function> frees a row set created by a
2835    prior SPI command execution function, such as
2836    <function>SPI_execute</>.  Therefore, this function is usually called
2837    with the global variable <varname>SPI_tupletable</varname> as
2838    argument.
2839   </para>
2840
2841   <para>
2842    This function is useful if a SPI procedure needs to execute
2843    multiple commands and does not want to keep the results of earlier
2844    commands around until it ends.  Note that any unfreed row sets will
2845    be freed anyway at <function>SPI_finish</>.
2846   </para>
2847  </refsect1>
2848
2849  <refsect1>
2850   <title>Arguments</title>
2851
2852   <variablelist>
2853    <varlistentry>
2854     <term><literal>SPITupleTable * <parameter>tuptable</parameter></literal></term>
2855     <listitem>
2856      <para>
2857       pointer to row set to free
2858      </para>
2859     </listitem>
2860    </varlistentry>
2861   </variablelist>
2862  </refsect1>
2863 </refentry>
2864
2865 <!-- *********************************************** -->
2866
2867 <refentry id="spi-spi-freeplan">
2868  <refmeta>
2869   <refentrytitle>SPI_freeplan</refentrytitle>
2870  </refmeta>
2871
2872  <refnamediv>
2873   <refname>SPI_freeplan</refname>
2874   <refpurpose>free a previously saved plan</refpurpose>
2875  </refnamediv>
2876
2877  <indexterm><primary>SPI_freeplan</primary></indexterm>
2878
2879  <refsynopsisdiv>
2880 <synopsis>
2881 int SPI_freeplan(void *<parameter>plan</parameter>)
2882 </synopsis>
2883  </refsynopsisdiv>
2884
2885  <refsect1>
2886   <title>Description</title>
2887
2888   <para>
2889    <function>SPI_freeplan</function> releases a command execution plan
2890    previously returned by <function>SPI_prepare</function> or saved by
2891    <function>SPI_saveplan</function>.
2892   </para>
2893  </refsect1>
2894
2895  <refsect1>
2896   <title>Arguments</title>
2897
2898   <variablelist>
2899    <varlistentry>
2900     <term><literal>void * <parameter>plan</parameter></literal></term>
2901     <listitem>
2902      <para>
2903       pointer to plan to free
2904      </para>
2905     </listitem>
2906    </varlistentry>
2907   </variablelist>
2908  </refsect1>
2909
2910  <refsect1>
2911   <title>Return Value</title>
2912
2913   <para>
2914    <symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>plan</parameter>
2915    is <symbol>NULL</symbol>.
2916   </para>
2917  </refsect1>
2918 </refentry>
2919
2920  </sect1>
2921
2922  <sect1 id="spi-visibility">
2923   <title>Visibility of Data Changes</title>
2924
2925   <para>
2926    The following rules govern the visibility of data changes in
2927    functions that use SPI (or any other C function):
2928
2929    <itemizedlist>
2930     <listitem>
2931      <para>
2932       During the execution of an SQL command, any data changes made by
2933       the command are invisible to the command itself.  For
2934       example, in
2935 <programlisting>
2936 INSERT INTO a SELECT * FROM a;
2937 </programlisting>
2938       the inserted rows are invisible to the <command>SELECT</command>
2939       part.
2940      </para>
2941     </listitem>
2942
2943     <listitem>
2944      <para>
2945       Changes made by a command C are visible to all commands that are
2946       started after C, no matter whether they are started inside C
2947       (during the execution of C) or after C is done.
2948      </para>
2949     </listitem>
2950
2951     <listitem>
2952      <para>
2953       Commands executed via SPI inside a function called by an SQL command
2954       (either an ordinary function or a trigger) follow one or the
2955       other of the above rules depending on the read/write flag passed
2956       to SPI.  Commands executed in read-only mode follow the first
2957       rule: they can't see changes of the calling command.  Commands executed
2958       in read-write mode follow the second rule: they can see all changes made
2959       so far.
2960      </para>
2961     </listitem>
2962
2963     <listitem>
2964      <para>
2965       All standard procedural languages set the SPI read-write mode
2966       depending on the volatility attribute of the function.  Commands of
2967       <literal>STABLE</> and <literal>IMMUTABLE</> functions are done in
2968       read-only mode, while commands of <literal>VOLATILE</> functions are
2969       done in read-write mode.  While authors of C functions are able to
2970       violate this convention, it's unlikely to be a good idea to do so.
2971      </para>
2972     </listitem>
2973    </itemizedlist>
2974   </para>
2975
2976   <para>
2977    The next section contains an example that illustrates the
2978    application of these rules.
2979   </para>
2980  </sect1>
2981
2982  <sect1 id="spi-examples">
2983   <title>Examples</title>
2984
2985   <para>
2986    This section contains a very simple example of SPI usage. The
2987    procedure <function>execq</function> takes an SQL command as its
2988    first argument and a row count as its second, executes the command
2989    using <function>SPI_exec</function> and returns the number of rows
2990    that were processed by the command.  You can find more complex
2991    examples for SPI in the source tree in
2992    <filename>src/test/regress/regress.c</filename> and in
2993    <filename>contrib/spi</filename>.
2994   </para>
2995
2996 <programlisting>
2997 #include "executor/spi.h"
2998
2999 int execq(text *sql, int cnt);
3000
3001 int
3002 execq(text *sql, int cnt)
3003 {
3004     char *command;
3005     int ret;
3006     int proc;
3007
3008     /* Convert given text object to a C string */
3009     command = DatumGetCString(DirectFunctionCall1(textout,
3010                                                   PointerGetDatum(sql)));
3011
3012     SPI_connect();
3013
3014     ret = SPI_exec(command, cnt);
3015
3016     proc = SPI_processed;
3017     /*
3018      * If some rows were fetched, print them via elog(INFO).
3019      */
3020     if (ret &gt; 0 &amp;&amp; SPI_tuptable != NULL)
3021     {
3022         TupleDesc tupdesc = SPI_tuptable-&gt;tupdesc;
3023         SPITupleTable *tuptable = SPI_tuptable;
3024         char buf[8192];
3025         int i, j;
3026
3027         for (j = 0; j &lt; proc; j++)
3028         {
3029             HeapTuple tuple = tuptable-&gt;vals[j];
3030
3031             for (i = 1, buf[0] = 0; i &lt;= tupdesc-&gt;natts; i++)
3032                 snprintf(buf + strlen (buf), sizeof(buf) - strlen(buf), " %s%s",
3033                         SPI_getvalue(tuple, tupdesc, i),
3034                         (i == tupdesc-&gt;natts) ? " " : " |");
3035             elog(INFO, "EXECQ: %s", buf);
3036         }
3037     }
3038
3039     SPI_finish();
3040     pfree(command);
3041
3042     return (proc);
3043 }
3044 </programlisting>
3045
3046   <para>
3047    (This function uses call convention version 0, to make the example
3048    easier to understand.  In real applications you should use the new
3049    version 1 interface.)
3050   </para>
3051
3052   <para>
3053    This is how you declare the function after having compiled it into
3054    a shared library:
3055
3056 <programlisting>
3057 CREATE FUNCTION execq(text, integer) RETURNS integer
3058     AS '<replaceable>filename</replaceable>'
3059     LANGUAGE C;
3060 </programlisting>
3061   </para>
3062
3063   <para>
3064    Here is a sample session:
3065
3066 <programlisting>
3067 =&gt; SELECT execq('CREATE TABLE a (x integer)', 0);
3068  execq
3069 -------
3070      0
3071 (1 row)
3072
3073 =&gt; INSERT INTO a VALUES (execq('INSERT INTO a VALUES (0)', 0));
3074 INSERT 0 1
3075 =&gt; SELECT execq('SELECT * FROM a', 0);
3076 INFO:  EXECQ:  0    -- inserted by execq
3077 INFO:  EXECQ:  1    -- returned by execq and inserted by upper INSERT
3078
3079  execq
3080 -------
3081      2
3082 (1 row)
3083
3084 =&gt; SELECT execq('INSERT INTO a SELECT x + 2 FROM a', 1);
3085  execq
3086 -------
3087      1
3088 (1 row)
3089
3090 =&gt; SELECT execq('SELECT * FROM a', 10);
3091 INFO:  EXECQ:  0
3092 INFO:  EXECQ:  1
3093 INFO:  EXECQ:  2    -- 0 + 2, only one row inserted - as specified
3094
3095  execq
3096 -------
3097      3              -- 10 is the max value only, 3 is the real number of rows
3098 (1 row)
3099
3100 =&gt; DELETE FROM a;
3101 DELETE 3
3102 =&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
3103 INSERT 0 1
3104 =&gt; SELECT * FROM a;
3105  x
3106 ---
3107  1                  -- no rows in a (0) + 1
3108 (1 row)
3109
3110 =&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
3111 INFO:  EXECQ:  1
3112 INSERT 0 1
3113 =&gt; SELECT * FROM a;
3114  x
3115 ---
3116  1
3117  2                  -- there was one row in a + 1
3118 (2 rows)
3119
3120 -- This demonstrates the data changes visibility rule:
3121
3122 =&gt; INSERT INTO a SELECT execq('SELECT * FROM a', 0) * x FROM a;
3123 INFO:  EXECQ:  1
3124 INFO:  EXECQ:  2
3125 INFO:  EXECQ:  1
3126 INFO:  EXECQ:  2
3127 INFO:  EXECQ:  2
3128 INSERT 0 2
3129 =&gt; SELECT * FROM a;
3130  x
3131 ---
3132  1
3133  2
3134  2                  -- 2 rows * 1 (x in first row)
3135  6                  -- 3 rows (2 + 1 just inserted) * 2 (x in second row)
3136 (4 rows)               ^^^^^^
3137                        rows visible to execq() in different invocations
3138 </programlisting>
3139   </para>
3140  </sect1>
3141 </chapter>