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

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