The code to unlink dropped relations in FinishPreparedTransaction() was
[PostgreSQL.git] / doc / src / sgml / spi.sgml
blob0db9c329042d823668d9b0b09f27aa17f25caf57
1 <!-- $PostgreSQL$ -->
3 <chapter id="spi">
4 <title>Server Programming Interface</title>
6 <indexterm zone="spi">
7 <primary>SPI</primary>
8 </indexterm>
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>
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>
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>
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>
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>
56 <para>
57 Source code files that use SPI must include the header file
58 <filename>executor/spi.h</filename>.
59 </para>
62 <sect1 id="spi-interface">
63 <title>Interface Functions</title>
65 <refentry id="spi-spi-connect">
66 <refmeta>
67 <refentrytitle>SPI_connect</refentrytitle>
68 </refmeta>
70 <refnamediv>
71 <refname>SPI_connect</refname>
72 <refpurpose>connect a procedure to the SPI manager</refpurpose>
73 </refnamediv>
75 <indexterm><primary>SPI_connect</primary></indexterm>
77 <refsynopsisdiv>
78 <synopsis>
79 int SPI_connect(void)
80 </synopsis>
81 </refsynopsisdiv>
83 <refsect1>
84 <title>Description</title>
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>
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>
109 <refsect1>
110 <title>Return Value</title>
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>
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>
134 <!-- *********************************************** -->
136 <refentry id="spi-spi-finish">
137 <refmeta>
138 <refentrytitle>SPI_finish</refentrytitle>
139 </refmeta>
141 <refnamediv>
142 <refname>SPI_finish</refname>
143 <refpurpose>disconnect a procedure from the SPI manager</refpurpose>
144 </refnamediv>
146 <indexterm><primary>SPI_finish</primary></indexterm>
148 <refsynopsisdiv>
149 <synopsis>
150 int SPI_finish(void)
151 </synopsis>
152 </refsynopsisdiv>
154 <refsect1>
155 <title>Description</title>
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>
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>
174 <refsect1>
175 <title>Return Value</title>
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>
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>
199 <!-- *********************************************** -->
201 <refentry id="spi-spi-push">
202 <refmeta>
203 <refentrytitle>SPI_push</refentrytitle>
204 </refmeta>
206 <refnamediv>
207 <refname>SPI_push</refname>
208 <refpurpose>push SPI stack to allow recursive SPI usage</refpurpose>
209 </refnamediv>
211 <indexterm><primary>SPI_push</primary></indexterm>
213 <refsynopsisdiv>
214 <synopsis>
215 void SPI_push(void)
216 </synopsis>
217 </refsynopsisdiv>
219 <refsect1>
220 <title>Description</title>
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>
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>
244 </refentry>
246 <!-- *********************************************** -->
248 <refentry id="spi-spi-pop">
249 <refmeta>
250 <refentrytitle>SPI_pop</refentrytitle>
251 </refmeta>
253 <refnamediv>
254 <refname>SPI_pop</refname>
255 <refpurpose>pop SPI stack to return from recursive SPI usage</refpurpose>
256 </refnamediv>
258 <indexterm><primary>SPI_pop</primary></indexterm>
260 <refsynopsisdiv>
261 <synopsis>
262 void SPI_pop(void)
263 </synopsis>
264 </refsynopsisdiv>
266 <refsect1>
267 <title>Description</title>
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>
275 </refentry>
277 <!-- *********************************************** -->
279 <refentry id="spi-spi-execute">
280 <refmeta>
281 <refentrytitle>SPI_execute</refentrytitle>
282 </refmeta>
284 <refnamediv>
285 <refname>SPI_execute</refname>
286 <refpurpose>execute a command</refpurpose>
287 </refnamediv>
289 <indexterm><primary>SPI_execute</primary></indexterm>
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>
297 <refsect1>
298 <title>Description</title>
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>
307 <para>
308 This function can only be called from a connected procedure.
309 </para>
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>
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>
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>
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>
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>
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>
378 <para>
379 The structure <structname>SPITupleTable</structname> is defined
380 thus:
381 <programlisting>
382 typedef struct
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>
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>
407 <refsect1>
408 <title>Arguments</title>
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>
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>
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>
440 <refsect1>
441 <title>Return Value</title>
443 <para>
444 If the execution of the command was successful then one of the
445 following (nonnegative) values will be returned:
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>
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>
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>
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>
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>
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>
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>
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>
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>
531 <varlistentry>
532 <term><symbol>SPI_OK_REWRITTEN</symbol></term>
533 <listitem>
534 <para>
535 if the command was rewritten into another kind of command (e.g.,
536 <command>UPDATE</command> became an <command>INSERT</command>) by a <link linkend="rules">rule</link>.
537 </para>
538 </listitem>
539 </varlistentry>
540 </variablelist>
541 </para>
543 <para>
544 On error, one of the following negative values is returned:
546 <variablelist>
547 <varlistentry>
548 <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
549 <listitem>
550 <para>
551 if <parameter>command</parameter> is <symbol>NULL</symbol> or
552 <parameter>count</parameter> is less than 0
553 </para>
554 </listitem>
555 </varlistentry>
557 <varlistentry>
558 <term><symbol>SPI_ERROR_COPY</symbol></term>
559 <listitem>
560 <para>
561 if <command>COPY TO stdout</> or <command>COPY FROM stdin</>
562 was attempted
563 </para>
564 </listitem>
565 </varlistentry>
567 <varlistentry>
568 <term><symbol>SPI_ERROR_TRANSACTION</symbol></term>
569 <listitem>
570 <para>
571 if a transaction manipulation command was attempted
572 (<command>BEGIN</>,
573 <command>COMMIT</>,
574 <command>ROLLBACK</>,
575 <command>SAVEPOINT</>,
576 <command>PREPARE TRANSACTION</>,
577 <command>COMMIT PREPARED</>,
578 <command>ROLLBACK PREPARED</>,
579 or any variant thereof)
580 </para>
581 </listitem>
582 </varlistentry>
584 <varlistentry>
585 <term><symbol>SPI_ERROR_OPUNKNOWN</symbol></term>
586 <listitem>
587 <para>
588 if the command type is unknown (shouldn't happen)
589 </para>
590 </listitem>
591 </varlistentry>
593 <varlistentry>
594 <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
595 <listitem>
596 <para>
597 if called from an unconnected procedure
598 </para>
599 </listitem>
600 </varlistentry>
601 </variablelist>
602 </para>
603 </refsect1>
605 <refsect1>
606 <title>Notes</title>
608 <para>
609 The functions <function>SPI_execute</function>,
610 <function>SPI_exec</function>,
611 <function>SPI_execute_plan</function>, and
612 <function>SPI_execp</function> change both
613 <varname>SPI_processed</varname> and
614 <varname>SPI_tuptable</varname> (just the pointer, not the contents
615 of the structure). Save these two global variables into local
616 procedure variables if you need to access the result table of
617 <function>SPI_execute</function> or a related function
618 across later calls.
619 </para>
620 </refsect1>
621 </refentry>
623 <!-- *********************************************** -->
625 <refentry id="spi-spi-exec">
626 <refmeta>
627 <refentrytitle>SPI_exec</refentrytitle>
628 </refmeta>
630 <refnamediv>
631 <refname>SPI_exec</refname>
632 <refpurpose>execute a read/write command</refpurpose>
633 </refnamediv>
635 <indexterm><primary>SPI_exec</primary></indexterm>
637 <refsynopsisdiv>
638 <synopsis>
639 int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count</parameter>)
640 </synopsis>
641 </refsynopsisdiv>
643 <refsect1>
644 <title>Description</title>
646 <para>
647 <function>SPI_exec</function> is the same as
648 <function>SPI_execute</function>, with the latter's
649 <parameter>read_only</parameter> parameter always taken as
650 <literal>false</>.
651 </para>
652 </refsect1>
654 <refsect1>
655 <title>Arguments</title>
657 <variablelist>
658 <varlistentry>
659 <term><literal>const char * <parameter>command</parameter></literal></term>
660 <listitem>
661 <para>
662 string containing command to execute
663 </para>
664 </listitem>
665 </varlistentry>
667 <varlistentry>
668 <term><literal>long <parameter>count</parameter></literal></term>
669 <listitem>
670 <para>
671 maximum number of rows to process or return
672 </para>
673 </listitem>
674 </varlistentry>
675 </variablelist>
676 </refsect1>
678 <refsect1>
679 <title>Return Value</title>
681 <para>
682 See <function>SPI_execute</function>.
683 </para>
684 </refsect1>
685 </refentry>
687 <!-- *********************************************** -->
689 <refentry id="spi-spi-execute-with-args">
690 <refmeta>
691 <refentrytitle>SPI_execute_with_args</refentrytitle>
692 </refmeta>
694 <refnamediv>
695 <refname>SPI_execute_with_args</refname>
696 <refpurpose>execute a command with out-of-line parameters</refpurpose>
697 </refnamediv>
699 <indexterm><primary>SPI_execute_with_args</primary></indexterm>
701 <refsynopsisdiv>
702 <synopsis>
703 int SPI_execute_with_args(const char *<parameter>command</parameter>,
704 int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
705 Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
706 bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
707 </synopsis>
708 </refsynopsisdiv>
710 <refsect1>
711 <title>Description</title>
713 <para>
714 <function>SPI_execute_with_args</function> executes a command that might
715 include references to externally supplied parameters. The command text
716 refers to a parameter as <literal>$<replaceable>n</></literal>, and
717 the call specifies data types and values for each such symbol.
718 <parameter>read_only</parameter> and <parameter>count</parameter> have
719 the same interpretation as in <function>SPI_execute</function>.
720 </para>
722 <para>
723 The main advantage of this routine compared to
724 <function>SPI_execute</function> is that data values can be inserted
725 into the command without tedious quoting/escaping, and thus with much
726 less risk of SQL-injection attacks.
727 </para>
729 <para>
730 Similar results can be achieved with <function>SPI_prepare</> followed by
731 <function>SPI_execute_plan</function>; however, when using this function
732 the query plan is customized to the specific parameter values provided.
733 For one-time query execution, this function should be preferred.
734 If the same command is to be executed with many different parameters,
735 either method might be faster, depending on the cost of re-planning
736 versus the benefit of custom plans.
737 </para>
738 </refsect1>
740 <refsect1>
741 <title>Arguments</title>
743 <variablelist>
744 <varlistentry>
745 <term><literal>const char * <parameter>command</parameter></literal></term>
746 <listitem>
747 <para>
748 command string
749 </para>
750 </listitem>
751 </varlistentry>
753 <varlistentry>
754 <term><literal>int <parameter>nargs</parameter></literal></term>
755 <listitem>
756 <para>
757 number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
758 </para>
759 </listitem>
760 </varlistentry>
762 <varlistentry>
763 <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
764 <listitem>
765 <para>
766 an array containing the <acronym>OID</acronym>s of
767 the data types of the parameters
768 </para>
769 </listitem>
770 </varlistentry>
772 <varlistentry>
773 <term><literal>Datum * <parameter>values</parameter></literal></term>
774 <listitem>
775 <para>
776 an array of actual parameter values
777 </para>
778 </listitem>
779 </varlistentry>
781 <varlistentry>
782 <term><literal>const char * <parameter>nulls</parameter></literal></term>
783 <listitem>
784 <para>
785 an array describing which parameters are null
786 </para>
788 <para>
789 If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
790 <function>SPI_execute_with_args</function> assumes that no parameters are
791 null.
792 </para>
793 </listitem>
794 </varlistentry>
796 <varlistentry>
797 <term><literal>bool <parameter>read_only</parameter></literal></term>
798 <listitem>
799 <para>
800 <literal>true</> for read-only execution
801 </para>
802 </listitem>
803 </varlistentry>
805 <varlistentry>
806 <term><literal>long <parameter>count</parameter></literal></term>
807 <listitem>
808 <para>
809 maximum number of rows to process or return
810 </para>
811 </listitem>
812 </varlistentry>
813 </variablelist>
814 </refsect1>
816 <refsect1>
817 <title>Return Value</title>
819 <para>
820 The return value is the same as for <function>SPI_execute</function>.
821 </para>
823 <para>
824 <varname>SPI_processed</varname> and
825 <varname>SPI_tuptable</varname> are set as in
826 <function>SPI_execute</function> if successful.
827 </para>
828 </refsect1>
829 </refentry>
831 <!-- *********************************************** -->
833 <refentry id="spi-spi-prepare">
834 <refmeta>
835 <refentrytitle>SPI_prepare</refentrytitle>
836 </refmeta>
838 <refnamediv>
839 <refname>SPI_prepare</refname>
840 <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
841 </refnamediv>
843 <indexterm><primary>SPI_prepare</primary></indexterm>
845 <refsynopsisdiv>
846 <synopsis>
847 SPIPlanPtr SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
848 </synopsis>
849 </refsynopsisdiv>
851 <refsect1>
852 <title>Description</title>
854 <para>
855 <function>SPI_prepare</function> creates and returns an execution
856 plan for the specified command but doesn't execute the command.
857 This function should only be called from a connected procedure.
858 </para>
860 <para>
861 When the same or a similar command is to be executed repeatedly, it
862 might be advantageous to perform the planning only once.
863 <function>SPI_prepare</function> converts a command string into an
864 execution plan that can be executed repeatedly using
865 <function>SPI_execute_plan</function>.
866 </para>
868 <para>
869 A prepared command can be generalized by writing parameters
870 (<literal>$1</>, <literal>$2</>, etc.) in place of what would be
871 constants in a normal command. The actual values of the parameters
872 are then specified when <function>SPI_execute_plan</function> is called.
873 This allows the prepared command to be used over a wider range of
874 situations than would be possible without parameters.
875 </para>
877 <para>
878 The plan returned by <function>SPI_prepare</function> can be used
879 only in the current invocation of the procedure, since
880 <function>SPI_finish</function> frees memory allocated for a plan.
881 But a plan can be saved for longer using the function
882 <function>SPI_saveplan</function>.
883 </para>
884 </refsect1>
886 <refsect1>
887 <title>Arguments</title>
889 <variablelist>
890 <varlistentry>
891 <term><literal>const char * <parameter>command</parameter></literal></term>
892 <listitem>
893 <para>
894 command string
895 </para>
896 </listitem>
897 </varlistentry>
899 <varlistentry>
900 <term><literal>int <parameter>nargs</parameter></literal></term>
901 <listitem>
902 <para>
903 number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
904 </para>
905 </listitem>
906 </varlistentry>
908 <varlistentry>
909 <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
910 <listitem>
911 <para>
912 pointer to an array containing the <acronym>OID</acronym>s of
913 the data types of the parameters
914 </para>
915 </listitem>
916 </varlistentry>
917 </variablelist>
918 </refsect1>
920 <refsect1>
921 <title>Return Value</title>
923 <para>
924 <function>SPI_prepare</function> returns a non-null pointer to an
925 execution plan. On error, <symbol>NULL</symbol> will be returned,
926 and <varname>SPI_result</varname> will be set to one of the same
927 error codes used by <function>SPI_execute</function>, except that
928 it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if
929 <parameter>command</parameter> is <symbol>NULL</symbol>, or if
930 <parameter>nargs</> is less than 0, or if <parameter>nargs</> is
931 greater than 0 and <parameter>argtypes</> is <symbol>NULL</symbol>.
932 </para>
933 </refsect1>
935 <refsect1>
936 <title>Notes</title>
938 <para>
939 <type>SPIPlanPtr</> is declared as a pointer to an opaque struct type in
940 <filename>spi.h</>. It is unwise to try to access its contents
941 directly, as that makes your code much more likely to break in
942 future revisions of <productname>PostgreSQL</productname>.
943 </para>
945 <para>
946 There is a disadvantage to using parameters: since the planner does
947 not know the values that will be supplied for the parameters, it
948 might make worse planning choices than it would make for a normal
949 command with all constants visible.
950 </para>
951 </refsect1>
952 </refentry>
954 <!-- *********************************************** -->
956 <refentry id="spi-spi-prepare-cursor">
957 <refmeta>
958 <refentrytitle>SPI_prepare_cursor</refentrytitle>
959 </refmeta>
961 <refnamediv>
962 <refname>SPI_prepare_cursor</refname>
963 <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
964 </refnamediv>
966 <indexterm><primary>SPI_prepare_cursor</primary></indexterm>
968 <refsynopsisdiv>
969 <synopsis>
970 SPIPlanPtr SPI_prepare_cursor(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>, int <parameter>cursorOptions</parameter>)
971 </synopsis>
972 </refsynopsisdiv>
974 <refsect1>
975 <title>Description</title>
977 <para>
978 <function>SPI_prepare_cursor</function> is identical to
979 <function>SPI_prepare</function>, except that it also allows specification
980 of the planner's <quote>cursor options</> parameter. This is a bitmask
981 having the values shown in <filename>nodes/parsenodes.h</filename>
982 for the <structfield>options</> field of <structname>DeclareCursorStmt</>.
983 <function>SPI_prepare</function> always takes these options as zero.
984 </para>
985 </refsect1>
987 <refsect1>
988 <title>Arguments</title>
990 <variablelist>
991 <varlistentry>
992 <term><literal>const char * <parameter>command</parameter></literal></term>
993 <listitem>
994 <para>
995 command string
996 </para>
997 </listitem>
998 </varlistentry>
1000 <varlistentry>
1001 <term><literal>int <parameter>nargs</parameter></literal></term>
1002 <listitem>
1003 <para>
1004 number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
1005 </para>
1006 </listitem>
1007 </varlistentry>
1009 <varlistentry>
1010 <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
1011 <listitem>
1012 <para>
1013 pointer to an array containing the <acronym>OID</acronym>s of
1014 the data types of the parameters
1015 </para>
1016 </listitem>
1017 </varlistentry>
1019 <varlistentry>
1020 <term><literal>int <parameter>cursorOptions</parameter></literal></term>
1021 <listitem>
1022 <para>
1023 integer bitmask of cursor options; zero produces default behavior
1024 </para>
1025 </listitem>
1026 </varlistentry>
1027 </variablelist>
1028 </refsect1>
1030 <refsect1>
1031 <title>Return Value</title>
1033 <para>
1034 <function>SPI_prepare_cursor</function> has the same return conventions as
1035 <function>SPI_prepare</function>.
1036 </para>
1037 </refsect1>
1039 <refsect1>
1040 <title>Notes</title>
1042 <para>
1043 Useful bits to set in <parameter>cursorOptions</> include
1044 <symbol>CURSOR_OPT_SCROLL</symbol>,
1045 <symbol>CURSOR_OPT_NO_SCROLL</symbol>, and
1046 <symbol>CURSOR_OPT_FAST_PLAN</symbol>. Note in particular that
1047 <symbol>CURSOR_OPT_HOLD</symbol> is ignored.
1048 </para>
1049 </refsect1>
1050 </refentry>
1052 <!-- *********************************************** -->
1054 <refentry id="spi-spi-getargcount">
1055 <refmeta>
1056 <refentrytitle>SPI_getargcount</refentrytitle>
1057 </refmeta>
1059 <refnamediv>
1060 <refname>SPI_getargcount</refname>
1061 <refpurpose>return the number of arguments needed by a plan
1062 prepared by <function>SPI_prepare</function></refpurpose>
1063 </refnamediv>
1065 <indexterm><primary>SPI_getargcount</primary></indexterm>
1067 <refsynopsisdiv>
1068 <synopsis>
1069 int SPI_getargcount(SPIPlanPtr <parameter>plan</parameter>)
1070 </synopsis>
1071 </refsynopsisdiv>
1073 <refsect1>
1074 <title>Description</title>
1076 <para>
1077 <function>SPI_getargcount</function> returns the number of arguments needed
1078 to execute a plan prepared by <function>SPI_prepare</function>.
1079 </para>
1080 </refsect1>
1082 <refsect1>
1083 <title>Arguments</title>
1085 <variablelist>
1086 <varlistentry>
1087 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1088 <listitem>
1089 <para>
1090 execution plan (returned by <function>SPI_prepare</function>)
1091 </para>
1092 </listitem>
1093 </varlistentry>
1094 </variablelist>
1095 </refsect1>
1097 <refsect1>
1098 <title>Return Value</title>
1099 <para>
1100 The count of expected arguments for the <parameter>plan</parameter>.
1101 If the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1102 <varname>SPI_result</varname> is set to <symbol>SPI_ERROR_ARGUMENT</symbol>
1103 and <literal>-1</literal> is returned.
1104 </para>
1105 </refsect1>
1106 </refentry>
1108 <!-- *********************************************** -->
1110 <refentry id="spi-spi-getargtypeid">
1111 <refmeta>
1112 <refentrytitle>SPI_getargtypeid</refentrytitle>
1113 </refmeta>
1115 <refnamediv>
1116 <refname>SPI_getargtypeid</refname>
1117 <refpurpose>return the data type OID for an argument of
1118 a plan prepared by <function>SPI_prepare</function></refpurpose>
1119 </refnamediv>
1121 <indexterm><primary>SPI_getargtypeid</primary></indexterm>
1123 <refsynopsisdiv>
1124 <synopsis>
1125 Oid SPI_getargtypeid(SPIPlanPtr <parameter>plan</parameter>, int <parameter>argIndex</parameter>)
1126 </synopsis>
1127 </refsynopsisdiv>
1129 <refsect1>
1130 <title>Description</title>
1132 <para>
1133 <function>SPI_getargtypeid</function> returns the OID representing the type
1134 id for the <parameter>argIndex</parameter>'th argument of a plan prepared by
1135 <function>SPI_prepare</function>. First argument is at index zero.
1136 </para>
1137 </refsect1>
1139 <refsect1>
1140 <title>Arguments</title>
1142 <variablelist>
1143 <varlistentry>
1144 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1145 <listitem>
1146 <para>
1147 execution plan (returned by <function>SPI_prepare</function>)
1148 </para>
1149 </listitem>
1150 </varlistentry>
1152 <varlistentry>
1153 <term><literal>int <parameter>argIndex</parameter></literal></term>
1154 <listitem>
1155 <para>
1156 zero based index of the argument
1157 </para>
1158 </listitem>
1159 </varlistentry>
1160 </variablelist>
1161 </refsect1>
1163 <refsect1>
1164 <title>Return Value</title>
1165 <para>
1166 The type id of the argument at the given index.
1167 If the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1168 or <parameter>argIndex</parameter> is less than 0 or
1169 not less than the number of arguments declared for the
1170 <parameter>plan</parameter>,
1171 <varname>SPI_result</varname> is set to <symbol>SPI_ERROR_ARGUMENT</symbol>
1172 and <symbol>InvalidOid</symbol> is returned.
1173 </para>
1174 </refsect1>
1175 </refentry>
1177 <!-- *********************************************** -->
1179 <refentry id="spi-spi-is-cursor-plan">
1180 <refmeta>
1181 <refentrytitle>SPI_is_cursor_plan</refentrytitle>
1182 </refmeta>
1184 <refnamediv>
1185 <refname>SPI_is_cursor_plan</refname>
1186 <refpurpose>return <symbol>true</symbol> if a plan
1187 prepared by <function>SPI_prepare</function> can be used with
1188 <function>SPI_cursor_open</function></refpurpose>
1189 </refnamediv>
1191 <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>
1193 <refsynopsisdiv>
1194 <synopsis>
1195 bool SPI_is_cursor_plan(SPIPlanPtr <parameter>plan</parameter>)
1196 </synopsis>
1197 </refsynopsisdiv>
1199 <refsect1>
1200 <title>Description</title>
1202 <para>
1203 <function>SPI_is_cursor_plan</function> returns <symbol>true</symbol>
1204 if a plan prepared by <function>SPI_prepare</function> can be passed
1205 as an argument to <function>SPI_cursor_open</function>, or
1206 <symbol>false</symbol> if that is not the case. The criteria are that the
1207 <parameter>plan</parameter> represents one single command and that this
1208 command returns tuples to the caller; for example, <command>SELECT</>
1209 is allowed unless it contains an <literal>INTO</> clause, and
1210 <command>UPDATE</> is allowed only if it contains a <literal>RETURNING</>
1211 clause.
1212 </para>
1213 </refsect1>
1215 <refsect1>
1216 <title>Arguments</title>
1218 <variablelist>
1219 <varlistentry>
1220 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1221 <listitem>
1222 <para>
1223 execution plan (returned by <function>SPI_prepare</function>)
1224 </para>
1225 </listitem>
1226 </varlistentry>
1227 </variablelist>
1228 </refsect1>
1230 <refsect1>
1231 <title>Return Value</title>
1232 <para>
1233 <symbol>true</symbol> or <symbol>false</symbol> to indicate if the
1234 <parameter>plan</parameter> can produce a cursor or not, with
1235 <varname>SPI_result</varname> set to zero.
1236 If it is not possible to determine the answer (for example,
1237 if the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1238 or if called when not connected to SPI), then
1239 <varname>SPI_result</varname> is set to a suitable error code
1240 and <symbol>false</symbol> is returned.
1241 </para>
1242 </refsect1>
1243 </refentry>
1245 <!-- *********************************************** -->
1247 <refentry id="spi-spi-execute-plan">
1248 <refmeta>
1249 <refentrytitle>SPI_execute_plan</refentrytitle>
1250 </refmeta>
1252 <refnamediv>
1253 <refname>SPI_execute_plan</refname>
1254 <refpurpose>execute a plan prepared by <function>SPI_prepare</function></refpurpose>
1255 </refnamediv>
1257 <indexterm><primary>SPI_execute_plan</primary></indexterm>
1259 <refsynopsisdiv>
1260 <synopsis>
1261 int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
1262 bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
1263 </synopsis>
1264 </refsynopsisdiv>
1266 <refsect1>
1267 <title>Description</title>
1269 <para>
1270 <function>SPI_execute_plan</function> executes a plan prepared by
1271 <function>SPI_prepare</function>. <parameter>read_only</parameter> and
1272 <parameter>count</parameter> have the same interpretation as in
1273 <function>SPI_execute</function>.
1274 </para>
1275 </refsect1>
1277 <refsect1>
1278 <title>Arguments</title>
1280 <variablelist>
1281 <varlistentry>
1282 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1283 <listitem>
1284 <para>
1285 execution plan (returned by <function>SPI_prepare</function>)
1286 </para>
1287 </listitem>
1288 </varlistentry>
1290 <varlistentry>
1291 <term><literal>Datum * <parameter>values</parameter></literal></term>
1292 <listitem>
1293 <para>
1294 An array of actual parameter values. Must have same length as the
1295 plan's number of arguments.
1296 </para>
1297 </listitem>
1298 </varlistentry>
1300 <varlistentry>
1301 <term><literal>const char * <parameter>nulls</parameter></literal></term>
1302 <listitem>
1303 <para>
1304 An array describing which parameters are null. Must have same length as
1305 the plan's number of arguments.
1306 <literal>n</literal> indicates a null value (entry in
1307 <parameter>values</> will be ignored); a space indicates a
1308 nonnull value (entry in <parameter>values</> is valid).
1309 </para>
1311 <para>
1312 If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1313 <function>SPI_execute_plan</function> assumes that no parameters are
1314 null.
1315 </para>
1316 </listitem>
1317 </varlistentry>
1319 <varlistentry>
1320 <term><literal>bool <parameter>read_only</parameter></literal></term>
1321 <listitem>
1322 <para>
1323 <literal>true</> for read-only execution
1324 </para>
1325 </listitem>
1326 </varlistentry>
1328 <varlistentry>
1329 <term><literal>long <parameter>count</parameter></literal></term>
1330 <listitem>
1331 <para>
1332 maximum number of rows to process or return
1333 </para>
1334 </listitem>
1335 </varlistentry>
1336 </variablelist>
1337 </refsect1>
1339 <refsect1>
1340 <title>Return Value</title>
1342 <para>
1343 The return value is the same as for <function>SPI_execute</function>,
1344 with the following additional possible error (negative) results:
1346 <variablelist>
1347 <varlistentry>
1348 <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
1349 <listitem>
1350 <para>
1351 if <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
1352 or <parameter>count</parameter> is less than 0
1353 </para>
1354 </listitem>
1355 </varlistentry>
1357 <varlistentry>
1358 <term><symbol>SPI_ERROR_PARAM</symbol></term>
1359 <listitem>
1360 <para>
1361 if <parameter>values</parameter> is <symbol>NULL</symbol> and
1362 <parameter>plan</parameter> was prepared with some parameters
1363 </para>
1364 </listitem>
1365 </varlistentry>
1366 </variablelist>
1367 </para>
1369 <para>
1370 <varname>SPI_processed</varname> and
1371 <varname>SPI_tuptable</varname> are set as in
1372 <function>SPI_execute</function> if successful.
1373 </para>
1374 </refsect1>
1376 <refsect1>
1377 <title>Notes</title>
1379 <para>
1380 If one of the objects (a table, function, etc.) referenced by the
1381 prepared plan is dropped during the session then the result of
1382 <function>SPI_execute_plan</function> for this plan will be unpredictable.
1383 </para>
1384 </refsect1>
1385 </refentry>
1387 <!-- *********************************************** -->
1389 <refentry id="spi-spi-execp">
1390 <refmeta>
1391 <refentrytitle>SPI_execp</refentrytitle>
1392 </refmeta>
1394 <refnamediv>
1395 <refname>SPI_execp</refname>
1396 <refpurpose>execute a plan in read/write mode</refpurpose>
1397 </refnamediv>
1399 <indexterm><primary>SPI_execp</primary></indexterm>
1401 <refsynopsisdiv>
1402 <synopsis>
1403 int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, long <parameter>count</parameter>)
1404 </synopsis>
1405 </refsynopsisdiv>
1407 <refsect1>
1408 <title>Description</title>
1410 <para>
1411 <function>SPI_execp</function> is the same as
1412 <function>SPI_execute_plan</function>, with the latter's
1413 <parameter>read_only</parameter> parameter always taken as
1414 <literal>false</>.
1415 </para>
1416 </refsect1>
1418 <refsect1>
1419 <title>Arguments</title>
1421 <variablelist>
1422 <varlistentry>
1423 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1424 <listitem>
1425 <para>
1426 execution plan (returned by <function>SPI_prepare</function>)
1427 </para>
1428 </listitem>
1429 </varlistentry>
1431 <varlistentry>
1432 <term><literal>Datum * <parameter>values</parameter></literal></term>
1433 <listitem>
1434 <para>
1435 An array of actual parameter values. Must have same length as the
1436 plan's number of arguments.
1437 </para>
1438 </listitem>
1439 </varlistentry>
1441 <varlistentry>
1442 <term><literal>const char * <parameter>nulls</parameter></literal></term>
1443 <listitem>
1444 <para>
1445 An array describing which parameters are null. Must have same length as
1446 the plan's number of arguments.
1447 <literal>n</literal> indicates a null value (entry in
1448 <parameter>values</> will be ignored); a space indicates a
1449 nonnull value (entry in <parameter>values</> is valid).
1450 </para>
1452 <para>
1453 If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1454 <function>SPI_execp</function> assumes that no parameters are
1455 null.
1456 </para>
1457 </listitem>
1458 </varlistentry>
1460 <varlistentry>
1461 <term><literal>long <parameter>count</parameter></literal></term>
1462 <listitem>
1463 <para>
1464 maximum number of rows to process or return
1465 </para>
1466 </listitem>
1467 </varlistentry>
1468 </variablelist>
1469 </refsect1>
1471 <refsect1>
1472 <title>Return Value</title>
1474 <para>
1475 See <function>SPI_execute_plan</function>.
1476 </para>
1478 <para>
1479 <varname>SPI_processed</varname> and
1480 <varname>SPI_tuptable</varname> are set as in
1481 <function>SPI_execute</function> if successful.
1482 </para>
1483 </refsect1>
1484 </refentry>
1486 <!-- *********************************************** -->
1488 <refentry id="spi-spi-cursor-open">
1489 <refmeta>
1490 <refentrytitle>SPI_cursor_open</refentrytitle>
1491 </refmeta>
1493 <refnamediv>
1494 <refname>SPI_cursor_open</refname>
1495 <refpurpose>set up a cursor using a plan created with <function>SPI_prepare</function></refpurpose>
1496 </refnamediv>
1498 <indexterm><primary>SPI_cursor_open</primary></indexterm>
1500 <refsynopsisdiv>
1501 <synopsis>
1502 Portal SPI_cursor_open(const char * <parameter>name</parameter>, SPIPlanPtr <parameter>plan</parameter>,
1503 Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
1504 bool <parameter>read_only</parameter>)
1505 </synopsis>
1506 </refsynopsisdiv>
1508 <refsect1>
1509 <title>Description</title>
1511 <para>
1512 <function>SPI_cursor_open</function> sets up a cursor (internally,
1513 a portal) that will execute a plan prepared by
1514 <function>SPI_prepare</function>. The parameters have the same
1515 meanings as the corresponding parameters to
1516 <function>SPI_execute_plan</function>.
1517 </para>
1519 <para>
1520 Using a cursor instead of executing the plan directly has two
1521 benefits. First, the result rows can be retrieved a few at a time,
1522 avoiding memory overrun for queries that return many rows. Second,
1523 a portal can outlive the current procedure (it can, in fact, live
1524 to the end of the current transaction). Returning the portal name
1525 to the procedure's caller provides a way of returning a row set as
1526 result.
1527 </para>
1529 <para>
1530 The passed-in data will be copied into the cursor's portal, so it
1531 can be freed while the cursor still exists.
1532 </para>
1533 </refsect1>
1535 <refsect1>
1536 <title>Arguments</title>
1538 <variablelist>
1539 <varlistentry>
1540 <term><literal>const char * <parameter>name</parameter></literal></term>
1541 <listitem>
1542 <para>
1543 name for portal, or <symbol>NULL</symbol> to let the system
1544 select a name
1545 </para>
1546 </listitem>
1547 </varlistentry>
1549 <varlistentry>
1550 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
1551 <listitem>
1552 <para>
1553 execution plan (returned by <function>SPI_prepare</function>)
1554 </para>
1555 </listitem>
1556 </varlistentry>
1558 <varlistentry>
1559 <term><literal>Datum * <parameter>values</parameter></literal></term>
1560 <listitem>
1561 <para>
1562 An array of actual parameter values. Must have same length as the
1563 plan's number of arguments.
1564 </para>
1565 </listitem>
1566 </varlistentry>
1568 <varlistentry>
1569 <term><literal>const char * <parameter>nulls</parameter></literal></term>
1570 <listitem>
1571 <para>
1572 An array describing which parameters are null. Must have same length as
1573 the plan's number of arguments.
1574 <literal>n</literal> indicates a null value (entry in
1575 <parameter>values</> will be ignored); a space indicates a
1576 nonnull value (entry in <parameter>values</> is valid).
1577 </para>
1579 <para>
1580 If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1581 <function>SPI_cursor_open</function> assumes that no parameters are
1582 null.
1583 </para>
1584 </listitem>
1585 </varlistentry>
1587 <varlistentry>
1588 <term><literal>bool <parameter>read_only</parameter></literal></term>
1589 <listitem>
1590 <para>
1591 <literal>true</> for read-only execution
1592 </para>
1593 </listitem>
1594 </varlistentry>
1595 </variablelist>
1596 </refsect1>
1598 <refsect1>
1599 <title>Return Value</title>
1601 <para>
1602 Pointer to portal containing the cursor. Note there is no error
1603 return convention; any error will be reported via <function>elog</>.
1604 </para>
1605 </refsect1>
1606 </refentry>
1608 <!-- *********************************************** -->
1610 <refentry id="spi-spi-cursor-open-with-args">
1611 <refmeta>
1612 <refentrytitle>SPI_cursor_open_with_args</refentrytitle>
1613 </refmeta>
1615 <refnamediv>
1616 <refname>SPI_cursor_open_with_args</refname>
1617 <refpurpose>set up a cursor using a query and parameters</refpurpose>
1618 </refnamediv>
1620 <indexterm><primary>SPI_cursor_open_with_args</primary></indexterm>
1622 <refsynopsisdiv>
1623 <synopsis>
1624 Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
1625 const char *<parameter>command</parameter>,
1626 int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
1627 Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
1628 bool <parameter>read_only</parameter>, int <parameter>cursorOptions</parameter>)
1629 </synopsis>
1630 </refsynopsisdiv>
1632 <refsect1>
1633 <title>Description</title>
1635 <para>
1636 <function>SPI_cursor_open_with_args</function> sets up a cursor
1637 (internally, a portal) that will execute the specified query.
1638 Most of the parameters have the same meanings as the corresponding
1639 parameters to <function>SPI_prepare_cursor</function>
1640 and <function>SPI_cursor_open</function>.
1641 </para>
1643 <para>
1644 For one-time query execution, this function should be preferred
1645 over <function>SPI_prepare_cursor</function> followed by
1646 <function>SPI_cursor_open</function>.
1647 If the same command is to be executed with many different parameters,
1648 either method might be faster, depending on the cost of re-planning
1649 versus the benefit of custom plans.
1650 </para>
1652 <para>
1653 The passed-in data will be copied into the cursor's portal, so it
1654 can be freed while the cursor still exists.
1655 </para>
1656 </refsect1>
1658 <refsect1>
1659 <title>Arguments</title>
1661 <variablelist>
1662 <varlistentry>
1663 <term><literal>const char * <parameter>name</parameter></literal></term>
1664 <listitem>
1665 <para>
1666 name for portal, or <symbol>NULL</symbol> to let the system
1667 select a name
1668 </para>
1669 </listitem>
1670 </varlistentry>
1672 <varlistentry>
1673 <term><literal>const char * <parameter>command</parameter></literal></term>
1674 <listitem>
1675 <para>
1676 command string
1677 </para>
1678 </listitem>
1679 </varlistentry>
1681 <varlistentry>
1682 <term><literal>int <parameter>nargs</parameter></literal></term>
1683 <listitem>
1684 <para>
1685 number of input parameters (<literal>$1</>, <literal>$2</>, etc.)
1686 </para>
1687 </listitem>
1688 </varlistentry>
1690 <varlistentry>
1691 <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
1692 <listitem>
1693 <para>
1694 an array containing the <acronym>OID</acronym>s of
1695 the data types of the parameters
1696 </para>
1697 </listitem>
1698 </varlistentry>
1700 <varlistentry>
1701 <term><literal>Datum * <parameter>values</parameter></literal></term>
1702 <listitem>
1703 <para>
1704 an array of actual parameter values
1705 </para>
1706 </listitem>
1707 </varlistentry>
1709 <varlistentry>
1710 <term><literal>const char * <parameter>nulls</parameter></literal></term>
1711 <listitem>
1712 <para>
1713 an array describing which parameters are null
1714 </para>
1716 <para>
1717 If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
1718 <function>SPI_cursor_open_with_args</function> assumes that no
1719 parameters are null.
1720 </para>
1721 </listitem>
1722 </varlistentry>
1724 <varlistentry>
1725 <term><literal>bool <parameter>read_only</parameter></literal></term>
1726 <listitem>
1727 <para>
1728 <literal>true</> for read-only execution
1729 </para>
1730 </listitem>
1731 </varlistentry>
1733 <varlistentry>
1734 <term><literal>int <parameter>cursorOptions</parameter></literal></term>
1735 <listitem>
1736 <para>
1737 integer bitmask of cursor options; zero produces default behavior
1738 </para>
1739 </listitem>
1740 </varlistentry>
1741 </variablelist>
1742 </refsect1>
1744 <refsect1>
1745 <title>Return Value</title>
1747 <para>
1748 Pointer to portal containing the cursor. Note there is no error
1749 return convention; any error will be reported via <function>elog</>.
1750 </para>
1751 </refsect1>
1752 </refentry>
1754 <!-- *********************************************** -->
1756 <refentry id="spi-spi-cursor-find">
1757 <refmeta>
1758 <refentrytitle>SPI_cursor_find</refentrytitle>
1759 </refmeta>
1761 <refnamediv>
1762 <refname>SPI_cursor_find</refname>
1763 <refpurpose>find an existing cursor by name</refpurpose>
1764 </refnamediv>
1766 <indexterm><primary>SPI_cursor_find</primary></indexterm>
1768 <refsynopsisdiv>
1769 <synopsis>
1770 Portal SPI_cursor_find(const char * <parameter>name</parameter>)
1771 </synopsis>
1772 </refsynopsisdiv>
1774 <refsect1>
1775 <title>Description</title>
1777 <para>
1778 <function>SPI_cursor_find</function> finds an existing portal by
1779 name. This is primarily useful to resolve a cursor name returned
1780 as text by some other function.
1781 </para>
1782 </refsect1>
1784 <refsect1>
1785 <title>Arguments</title>
1787 <variablelist>
1788 <varlistentry>
1789 <term><literal>const char * <parameter>name</parameter></literal></term>
1790 <listitem>
1791 <para>
1792 name of the portal
1793 </para>
1794 </listitem>
1795 </varlistentry>
1796 </variablelist>
1797 </refsect1>
1799 <refsect1>
1800 <title>Return Value</title>
1802 <para>
1803 pointer to the portal with the specified name, or
1804 <symbol>NULL</symbol> if none was found
1805 </para>
1806 </refsect1>
1807 </refentry>
1809 <!-- *********************************************** -->
1811 <refentry id="spi-spi-cursor-fetch">
1812 <refmeta>
1813 <refentrytitle>SPI_cursor_fetch</refentrytitle>
1814 </refmeta>
1816 <refnamediv>
1817 <refname>SPI_cursor_fetch</refname>
1818 <refpurpose>fetch some rows from a cursor</refpurpose>
1819 </refnamediv>
1821 <indexterm><primary>SPI_cursor_fetch</primary></indexterm>
1823 <refsynopsisdiv>
1824 <synopsis>
1825 void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
1826 </synopsis>
1827 </refsynopsisdiv>
1829 <refsect1>
1830 <title>Description</title>
1832 <para>
1833 <function>SPI_cursor_fetch</function> fetches some rows from a
1834 cursor. This is equivalent to a subset of the SQL command
1835 <command>FETCH</> (see <function>SPI_scroll_cursor_fetch</function>
1836 for more functionality).
1837 </para>
1838 </refsect1>
1840 <refsect1>
1841 <title>Arguments</title>
1843 <variablelist>
1844 <varlistentry>
1845 <term><literal>Portal <parameter>portal</parameter></literal></term>
1846 <listitem>
1847 <para>
1848 portal containing the cursor
1849 </para>
1850 </listitem>
1851 </varlistentry>
1853 <varlistentry>
1854 <term><literal>bool <parameter>forward</parameter></literal></term>
1855 <listitem>
1856 <para>
1857 true for fetch forward, false for fetch backward
1858 </para>
1859 </listitem>
1860 </varlistentry>
1862 <varlistentry>
1863 <term><literal>long <parameter>count</parameter></literal></term>
1864 <listitem>
1865 <para>
1866 maximum number of rows to fetch
1867 </para>
1868 </listitem>
1869 </varlistentry>
1870 </variablelist>
1871 </refsect1>
1873 <refsect1>
1874 <title>Return Value</title>
1876 <para>
1877 <varname>SPI_processed</varname> and
1878 <varname>SPI_tuptable</varname> are set as in
1879 <function>SPI_execute</function> if successful.
1880 </para>
1881 </refsect1>
1883 <refsect1>
1884 <title>Notes</title>
1886 <para>
1887 Fetching backward may fail if the cursor's plan was not created
1888 with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1889 </para>
1890 </refsect1>
1891 </refentry>
1893 <!-- *********************************************** -->
1895 <refentry id="spi-spi-cursor-move">
1896 <refmeta>
1897 <refentrytitle>SPI_cursor_move</refentrytitle>
1898 </refmeta>
1900 <refnamediv>
1901 <refname>SPI_cursor_move</refname>
1902 <refpurpose>move a cursor</refpurpose>
1903 </refnamediv>
1905 <indexterm><primary>SPI_cursor_move</primary></indexterm>
1907 <refsynopsisdiv>
1908 <synopsis>
1909 void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
1910 </synopsis>
1911 </refsynopsisdiv>
1913 <refsect1>
1914 <title>Description</title>
1916 <para>
1917 <function>SPI_cursor_move</function> skips over some number of rows
1918 in a cursor. This is equivalent to a subset of the SQL command
1919 <command>MOVE</> (see <function>SPI_scroll_cursor_move</function>
1920 for more functionality).
1921 </para>
1922 </refsect1>
1924 <refsect1>
1925 <title>Arguments</title>
1927 <variablelist>
1928 <varlistentry>
1929 <term><literal>Portal <parameter>portal</parameter></literal></term>
1930 <listitem>
1931 <para>
1932 portal containing the cursor
1933 </para>
1934 </listitem>
1935 </varlistentry>
1937 <varlistentry>
1938 <term><literal>bool <parameter>forward</parameter></literal></term>
1939 <listitem>
1940 <para>
1941 true for move forward, false for move backward
1942 </para>
1943 </listitem>
1944 </varlistentry>
1946 <varlistentry>
1947 <term><literal>long <parameter>count</parameter></literal></term>
1948 <listitem>
1949 <para>
1950 maximum number of rows to move
1951 </para>
1952 </listitem>
1953 </varlistentry>
1954 </variablelist>
1955 </refsect1>
1957 <refsect1>
1958 <title>Notes</title>
1960 <para>
1961 Moving backward may fail if the cursor's plan was not created
1962 with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
1963 </para>
1964 </refsect1>
1965 </refentry>
1967 <!-- *********************************************** -->
1969 <refentry id="spi-spi-scroll-cursor-fetch">
1970 <refmeta>
1971 <refentrytitle>SPI_scroll_cursor_fetch</refentrytitle>
1972 </refmeta>
1974 <refnamediv>
1975 <refname>SPI_scroll_cursor_fetch</refname>
1976 <refpurpose>fetch some rows from a cursor</refpurpose>
1977 </refnamediv>
1979 <indexterm><primary>SPI_scroll_cursor_fetch</primary></indexterm>
1981 <refsynopsisdiv>
1982 <synopsis>
1983 void SPI_scroll_cursor_fetch(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
1984 </synopsis>
1985 </refsynopsisdiv>
1987 <refsect1>
1988 <title>Description</title>
1990 <para>
1991 <function>SPI_scroll_cursor_fetch</function> fetches some rows from a
1992 cursor. This is equivalent to the SQL command <command>FETCH</>.
1993 </para>
1994 </refsect1>
1996 <refsect1>
1997 <title>Arguments</title>
1999 <variablelist>
2000 <varlistentry>
2001 <term><literal>Portal <parameter>portal</parameter></literal></term>
2002 <listitem>
2003 <para>
2004 portal containing the cursor
2005 </para>
2006 </listitem>
2007 </varlistentry>
2009 <varlistentry>
2010 <term><literal>FetchDirection <parameter>direction</parameter></literal></term>
2011 <listitem>
2012 <para>
2013 one of <symbol>FETCH_FORWARD</symbol>,
2014 <symbol>FETCH_BACKWARD</symbol>,
2015 <symbol>FETCH_ABSOLUTE</symbol> or
2016 <symbol>FETCH_RELATIVE</symbol>
2017 </para>
2018 </listitem>
2019 </varlistentry>
2021 <varlistentry>
2022 <term><literal>long <parameter>count</parameter></literal></term>
2023 <listitem>
2024 <para>
2025 number of rows to fetch for
2026 <symbol>FETCH_FORWARD</symbol> or
2027 <symbol>FETCH_BACKWARD</symbol>; absolute row number to fetch for
2028 <symbol>FETCH_ABSOLUTE</symbol>; or relative row number to fetch for
2029 <symbol>FETCH_RELATIVE</symbol>
2030 </para>
2031 </listitem>
2032 </varlistentry>
2033 </variablelist>
2034 </refsect1>
2036 <refsect1>
2037 <title>Return Value</title>
2039 <para>
2040 <varname>SPI_processed</varname> and
2041 <varname>SPI_tuptable</varname> are set as in
2042 <function>SPI_execute</function> if successful.
2043 </para>
2044 </refsect1>
2046 <refsect1>
2047 <title>Notes</title>
2049 <para>
2050 See the SQL <xref linkend="sql-fetch" endterm="sql-fetch-title"> command
2051 for details of the interpretation of the
2052 <parameter>direction</parameter> and
2053 <parameter>count</parameter> parameters.
2054 </para>
2056 <para>
2057 Direction values other than <symbol>FETCH_FORWARD</symbol>
2058 may fail if the cursor's plan was not created
2059 with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
2060 </para>
2061 </refsect1>
2062 </refentry>
2064 <!-- *********************************************** -->
2066 <refentry id="spi-spi-scroll-cursor-move">
2067 <refmeta>
2068 <refentrytitle>SPI_scroll_cursor_move</refentrytitle>
2069 </refmeta>
2071 <refnamediv>
2072 <refname>SPI_scroll_cursor_move</refname>
2073 <refpurpose>move a cursor</refpurpose>
2074 </refnamediv>
2076 <indexterm><primary>SPI_scroll_cursor_move</primary></indexterm>
2078 <refsynopsisdiv>
2079 <synopsis>
2080 void SPI_scroll_cursor_move(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
2081 </synopsis>
2082 </refsynopsisdiv>
2084 <refsect1>
2085 <title>Description</title>
2087 <para>
2088 <function>SPI_scroll_cursor_move</function> skips over some number of rows
2089 in a cursor. This is equivalent to the SQL command
2090 <command>MOVE</>.
2091 </para>
2092 </refsect1>
2094 <refsect1>
2095 <title>Arguments</title>
2097 <variablelist>
2098 <varlistentry>
2099 <term><literal>Portal <parameter>portal</parameter></literal></term>
2100 <listitem>
2101 <para>
2102 portal containing the cursor
2103 </para>
2104 </listitem>
2105 </varlistentry>
2107 <varlistentry>
2108 <term><literal>FetchDirection <parameter>direction</parameter></literal></term>
2109 <listitem>
2110 <para>
2111 one of <symbol>FETCH_FORWARD</symbol>,
2112 <symbol>FETCH_BACKWARD</symbol>,
2113 <symbol>FETCH_ABSOLUTE</symbol> or
2114 <symbol>FETCH_RELATIVE</symbol>
2115 </para>
2116 </listitem>
2117 </varlistentry>
2119 <varlistentry>
2120 <term><literal>long <parameter>count</parameter></literal></term>
2121 <listitem>
2122 <para>
2123 number of rows to move for
2124 <symbol>FETCH_FORWARD</symbol> or
2125 <symbol>FETCH_BACKWARD</symbol>; absolute row number to move to for
2126 <symbol>FETCH_ABSOLUTE</symbol>; or relative row number to move to for
2127 <symbol>FETCH_RELATIVE</symbol>
2128 </para>
2129 </listitem>
2130 </varlistentry>
2131 </variablelist>
2132 </refsect1>
2134 <refsect1>
2135 <title>Return Value</title>
2137 <para>
2138 <varname>SPI_processed</varname> is set as in
2139 <function>SPI_execute</function> if successful.
2140 <varname>SPI_tuptable</varname> is set to <symbol>NULL</>, since
2141 no rows are returned by this function.
2142 </para>
2143 </refsect1>
2145 <refsect1>
2146 <title>Notes</title>
2148 <para>
2149 See the SQL <xref linkend="sql-fetch" endterm="sql-fetch-title"> command
2150 for details of the interpretation of the
2151 <parameter>direction</parameter> and
2152 <parameter>count</parameter> parameters.
2153 </para>
2155 <para>
2156 Direction values other than <symbol>FETCH_FORWARD</symbol>
2157 may fail if the cursor's plan was not created
2158 with the <symbol>CURSOR_OPT_SCROLL</symbol> option.
2159 </para>
2160 </refsect1>
2161 </refentry>
2163 <!-- *********************************************** -->
2165 <refentry id="spi-spi-cursor-close">
2166 <refmeta>
2167 <refentrytitle>SPI_cursor_close</refentrytitle>
2168 </refmeta>
2170 <refnamediv>
2171 <refname>SPI_cursor_close</refname>
2172 <refpurpose>close a cursor</refpurpose>
2173 </refnamediv>
2175 <indexterm><primary>SPI_cursor_close</primary></indexterm>
2177 <refsynopsisdiv>
2178 <synopsis>
2179 void SPI_cursor_close(Portal <parameter>portal</parameter>)
2180 </synopsis>
2181 </refsynopsisdiv>
2183 <refsect1>
2184 <title>Description</title>
2186 <para>
2187 <function>SPI_cursor_close</function> closes a previously created
2188 cursor and releases its portal storage.
2189 </para>
2191 <para>
2192 All open cursors are closed automatically at the end of a
2193 transaction. <function>SPI_cursor_close</function> need only be
2194 invoked if it is desirable to release resources sooner.
2195 </para>
2196 </refsect1>
2198 <refsect1>
2199 <title>Arguments</title>
2201 <variablelist>
2202 <varlistentry>
2203 <term><literal>Portal <parameter>portal</parameter></literal></term>
2204 <listitem>
2205 <para>
2206 portal containing the cursor
2207 </para>
2208 </listitem>
2209 </varlistentry>
2210 </variablelist>
2211 </refsect1>
2212 </refentry>
2214 <!-- *********************************************** -->
2216 <refentry id="spi-spi-saveplan">
2217 <refmeta>
2218 <refentrytitle>SPI_saveplan</refentrytitle>
2219 </refmeta>
2221 <refnamediv>
2222 <refname>SPI_saveplan</refname>
2223 <refpurpose>save a plan</refpurpose>
2224 </refnamediv>
2226 <indexterm><primary>SPI_saveplan</primary></indexterm>
2228 <refsynopsisdiv>
2229 <synopsis>
2230 SPIPlanPtr SPI_saveplan(SPIPlanPtr <parameter>plan</parameter>)
2231 </synopsis>
2232 </refsynopsisdiv>
2234 <refsect1>
2235 <title>Description</title>
2237 <para>
2238 <function>SPI_saveplan</function> saves a passed plan (prepared by
2239 <function>SPI_prepare</function>) in memory that will not be freed
2240 by <function>SPI_finish</function> nor by the transaction manager,
2241 and returns a pointer to the saved plan. This gives you the
2242 ability to reuse prepared plans in the subsequent invocations of
2243 your procedure in the current session.
2244 </para>
2245 </refsect1>
2247 <refsect1>
2248 <title>Arguments</title>
2250 <variablelist>
2251 <varlistentry>
2252 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
2253 <listitem>
2254 <para>
2255 the plan to be saved
2256 </para>
2257 </listitem>
2258 </varlistentry>
2259 </variablelist>
2260 </refsect1>
2262 <refsect1>
2263 <title>Return Value</title>
2265 <para>
2266 Pointer to the saved plan; <symbol>NULL</symbol> if unsuccessful.
2267 On error, <varname>SPI_result</varname> is set thus:
2269 <variablelist>
2270 <varlistentry>
2271 <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
2272 <listitem>
2273 <para>
2274 if <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid
2275 </para>
2276 </listitem>
2277 </varlistentry>
2279 <varlistentry>
2280 <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
2281 <listitem>
2282 <para>
2283 if called from an unconnected procedure
2284 </para>
2285 </listitem>
2286 </varlistentry>
2287 </variablelist>
2288 </para>
2289 </refsect1>
2291 <refsect1>
2292 <title>Notes</title>
2294 <para>
2295 The passed-in plan is not freed, so you might wish to do
2296 <function>SPI_freeplan</function> on it to avoid leaking memory
2297 until <function>SPI_finish</>.
2298 </para>
2300 <para>
2301 If one of the objects (a table, function, etc.) referenced by the
2302 prepared plan is dropped or redefined, then future executions of
2303 <function>SPI_execute_plan</function> may fail or return different
2304 results than the plan initially indicates.
2305 </para>
2306 </refsect1>
2307 </refentry>
2309 </sect1>
2311 <sect1 id="spi-interface-support">
2312 <title>Interface Support Functions</title>
2314 <para>
2315 The functions described here provide an interface for extracting
2316 information from result sets returned by <function>SPI_execute</> and
2317 other SPI functions.
2318 </para>
2320 <para>
2321 All functions described in this section can be used by both
2322 connected and unconnected procedures.
2323 </para>
2325 <!-- *********************************************** -->
2327 <refentry id="spi-spi-fname">
2328 <refmeta>
2329 <refentrytitle>SPI_fname</refentrytitle>
2330 </refmeta>
2332 <refnamediv>
2333 <refname>SPI_fname</refname>
2334 <refpurpose>determine the column name for the specified column number</refpurpose>
2335 </refnamediv>
2337 <indexterm><primary>SPI_fname</primary></indexterm>
2339 <refsynopsisdiv>
2340 <synopsis>
2341 char * SPI_fname(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2342 </synopsis>
2343 </refsynopsisdiv>
2345 <refsect1>
2346 <title>Description</title>
2348 <para>
2349 <function>SPI_fname</function> returns a copy of the column name of the
2350 specified column. (You can use <function>pfree</function> to
2351 release the copy of the name when you don't need it anymore.)
2352 </para>
2353 </refsect1>
2355 <refsect1>
2356 <title>Arguments</title>
2358 <variablelist>
2359 <varlistentry>
2360 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2361 <listitem>
2362 <para>
2363 input row description
2364 </para>
2365 </listitem>
2366 </varlistentry>
2368 <varlistentry>
2369 <term><literal>int <parameter>colnumber</parameter></literal></term>
2370 <listitem>
2371 <para>
2372 column number (count starts at 1)
2373 </para>
2374 </listitem>
2375 </varlistentry>
2376 </variablelist>
2377 </refsect1>
2379 <refsect1>
2380 <title>Return Value</title>
2382 <para>
2383 The column name; <symbol>NULL</symbol> if
2384 <parameter>colnumber</parameter> is out of range.
2385 <varname>SPI_result</varname> set to
2386 <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2387 </para>
2388 </refsect1>
2389 </refentry>
2391 <!-- *********************************************** -->
2393 <refentry id="spi-spi-fnumber">
2394 <refmeta>
2395 <refentrytitle>SPI_fnumber</refentrytitle>
2396 </refmeta>
2398 <refnamediv>
2399 <refname>SPI_fnumber</refname>
2400 <refpurpose>determine the column number for the specified column name</refpurpose>
2401 </refnamediv>
2403 <indexterm><primary>SPI_fnumber</primary></indexterm>
2405 <refsynopsisdiv>
2406 <synopsis>
2407 int SPI_fnumber(TupleDesc <parameter>rowdesc</parameter>, const char * <parameter>colname</parameter>)
2408 </synopsis>
2409 </refsynopsisdiv>
2411 <refsect1>
2412 <title>Description</title>
2414 <para>
2415 <function>SPI_fnumber</function> returns the column number for the
2416 column with the specified name.
2417 </para>
2419 <para>
2420 If <parameter>colname</parameter> refers to a system column (e.g.,
2421 <literal>oid</>) then the appropriate negative column number will
2422 be returned. The caller should be careful to test the return value
2423 for exact equality to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> to
2424 detect an error; testing the result for less than or equal to 0 is
2425 not correct unless system columns should be rejected.
2426 </para>
2427 </refsect1>
2429 <refsect1>
2430 <title>Arguments</title>
2432 <variablelist>
2433 <varlistentry>
2434 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2435 <listitem>
2436 <para>
2437 input row description
2438 </para>
2439 </listitem>
2440 </varlistentry>
2442 <varlistentry>
2443 <term><literal>const char * <parameter>colname</parameter></literal></term>
2444 <listitem>
2445 <para>
2446 column name
2447 </para>
2448 </listitem>
2449 </varlistentry>
2450 </variablelist>
2451 </refsect1>
2453 <refsect1>
2454 <title>Return Value</title>
2456 <para>
2457 Column number (count starts at 1), or
2458 <symbol>SPI_ERROR_NOATTRIBUTE</symbol> if the named column was not
2459 found.
2460 </para>
2461 </refsect1>
2462 </refentry>
2464 <!-- *********************************************** -->
2466 <refentry id="spi-spi-getvalue">
2467 <refmeta>
2468 <refentrytitle>SPI_getvalue</refentrytitle>
2469 </refmeta>
2471 <refnamediv>
2472 <refname>SPI_getvalue</refname>
2473 <refpurpose>return the string value of the specified column</refpurpose>
2474 </refnamediv>
2476 <indexterm><primary>SPI_getvalue</primary></indexterm>
2478 <refsynopsisdiv>
2479 <synopsis>
2480 char * SPI_getvalue(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2481 </synopsis>
2482 </refsynopsisdiv>
2484 <refsect1>
2485 <title>Description</title>
2487 <para>
2488 <function>SPI_getvalue</function> returns the string representation
2489 of the value of the specified column.
2490 </para>
2492 <para>
2493 The result is returned in memory allocated using
2494 <function>palloc</function>. (You can use
2495 <function>pfree</function> to release the memory when you don't
2496 need it anymore.)
2497 </para>
2498 </refsect1>
2500 <refsect1>
2501 <title>Arguments</title>
2503 <variablelist>
2504 <varlistentry>
2505 <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2506 <listitem>
2507 <para>
2508 input row to be examined
2509 </para>
2510 </listitem>
2511 </varlistentry>
2513 <varlistentry>
2514 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2515 <listitem>
2516 <para>
2517 input row description
2518 </para>
2519 </listitem>
2520 </varlistentry>
2522 <varlistentry>
2523 <term><literal>int <parameter>colnumber</parameter></literal></term>
2524 <listitem>
2525 <para>
2526 column number (count starts at 1)
2527 </para>
2528 </listitem>
2529 </varlistentry>
2530 </variablelist>
2531 </refsect1>
2533 <refsect1>
2534 <title>Return Value</title>
2536 <para>
2537 Column value, or <symbol>NULL</symbol> if the column is null,
2538 <parameter>colnumber</parameter> is out of range
2539 (<varname>SPI_result</varname> is set to
2540 <symbol>SPI_ERROR_NOATTRIBUTE</symbol>), or no output function is
2541 available (<varname>SPI_result</varname> is set to
2542 <symbol>SPI_ERROR_NOOUTFUNC</symbol>).
2543 </para>
2544 </refsect1>
2545 </refentry>
2547 <!-- *********************************************** -->
2549 <refentry id="spi-spi-getbinval">
2550 <refmeta>
2551 <refentrytitle>SPI_getbinval</refentrytitle>
2552 </refmeta>
2554 <refnamediv>
2555 <refname>SPI_getbinval</refname>
2556 <refpurpose>return the binary value of the specified column</refpurpose>
2557 </refnamediv>
2559 <indexterm><primary>SPI_getbinval</primary></indexterm>
2561 <refsynopsisdiv>
2562 <synopsis>
2563 Datum SPI_getbinval(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>, bool * <parameter>isnull</parameter>)
2564 </synopsis>
2565 </refsynopsisdiv>
2567 <refsect1>
2568 <title>Description</title>
2570 <para>
2571 <function>SPI_getbinval</function> returns the value of the
2572 specified column in the internal form (as type <type>Datum</type>).
2573 </para>
2575 <para>
2576 This function does not allocate new space for the datum. In the
2577 case of a pass-by-reference data type, the return value will be a
2578 pointer into the passed row.
2579 </para>
2580 </refsect1>
2582 <refsect1>
2583 <title>Arguments</title>
2585 <variablelist>
2586 <varlistentry>
2587 <term><literal>HeapTuple <parameter>row</parameter></literal></term>
2588 <listitem>
2589 <para>
2590 input row to be examined
2591 </para>
2592 </listitem>
2593 </varlistentry>
2595 <varlistentry>
2596 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2597 <listitem>
2598 <para>
2599 input row description
2600 </para>
2601 </listitem>
2602 </varlistentry>
2604 <varlistentry>
2605 <term><literal>int <parameter>colnumber</parameter></literal></term>
2606 <listitem>
2607 <para>
2608 column number (count starts at 1)
2609 </para>
2610 </listitem>
2611 </varlistentry>
2613 <varlistentry>
2614 <term><literal>bool * <parameter>isnull</parameter></literal></term>
2615 <listitem>
2616 <para>
2617 flag for a null value in the column
2618 </para>
2619 </listitem>
2620 </varlistentry>
2621 </variablelist>
2622 </refsect1>
2624 <refsect1>
2625 <title>Return Value</title>
2627 <para>
2628 The binary value of the column is returned. The variable pointed
2629 to by <parameter>isnull</parameter> is set to true if the column is
2630 null, else to false.
2631 </para>
2633 <para>
2634 <varname>SPI_result</varname> is set to
2635 <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2636 </para>
2637 </refsect1>
2638 </refentry>
2640 <!-- *********************************************** -->
2642 <refentry id="spi-spi-gettype">
2643 <refmeta>
2644 <refentrytitle>SPI_gettype</refentrytitle>
2645 </refmeta>
2647 <refnamediv>
2648 <refname>SPI_gettype</refname>
2649 <refpurpose>return the data type name of the specified column</refpurpose>
2650 </refnamediv>
2652 <indexterm><primary>SPI_gettype</primary></indexterm>
2654 <refsynopsisdiv>
2655 <synopsis>
2656 char * SPI_gettype(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2657 </synopsis>
2658 </refsynopsisdiv>
2660 <refsect1>
2661 <title>Description</title>
2663 <para>
2664 <function>SPI_gettype</function> returns a copy of the data type name of the
2665 specified column. (You can use <function>pfree</function> to
2666 release the copy of the name when you don't need it anymore.)
2667 </para>
2668 </refsect1>
2670 <refsect1>
2671 <title>Arguments</title>
2673 <variablelist>
2674 <varlistentry>
2675 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2676 <listitem>
2677 <para>
2678 input row description
2679 </para>
2680 </listitem>
2681 </varlistentry>
2683 <varlistentry>
2684 <term><literal>int <parameter>colnumber</parameter></literal></term>
2685 <listitem>
2686 <para>
2687 column number (count starts at 1)
2688 </para>
2689 </listitem>
2690 </varlistentry>
2691 </variablelist>
2692 </refsect1>
2694 <refsect1>
2695 <title>Return Value</title>
2697 <para>
2698 The data type name of the specified column, or
2699 <symbol>NULL</symbol> on error. <varname>SPI_result</varname> is
2700 set to <symbol>SPI_ERROR_NOATTRIBUTE</symbol> on error.
2701 </para>
2702 </refsect1>
2703 </refentry>
2705 <!-- *********************************************** -->
2707 <refentry id="spi-spi-gettypeid">
2708 <refmeta>
2709 <refentrytitle>SPI_gettypeid</refentrytitle>
2710 </refmeta>
2712 <refnamediv>
2713 <refname>SPI_gettypeid</refname>
2714 <refpurpose>return the data type <acronym>OID</acronym> of the specified column</refpurpose>
2715 </refnamediv>
2717 <indexterm><primary>SPI_gettypeid</primary></indexterm>
2719 <refsynopsisdiv>
2720 <synopsis>
2721 Oid SPI_gettypeid(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)
2722 </synopsis>
2723 </refsynopsisdiv>
2725 <refsect1>
2726 <title>Description</title>
2728 <para>
2729 <function>SPI_gettypeid</function> returns the
2730 <acronym>OID</acronym> of the data type of the specified column.
2731 </para>
2732 </refsect1>
2734 <refsect1>
2735 <title>Arguments</title>
2737 <variablelist>
2738 <varlistentry>
2739 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
2740 <listitem>
2741 <para>
2742 input row description
2743 </para>
2744 </listitem>
2745 </varlistentry>
2747 <varlistentry>
2748 <term><literal>int <parameter>colnumber</parameter></literal></term>
2749 <listitem>
2750 <para>
2751 column number (count starts at 1)
2752 </para>
2753 </listitem>
2754 </varlistentry>
2755 </variablelist>
2756 </refsect1>
2758 <refsect1>
2759 <title>Return Value</title>
2761 <para>
2762 The <acronym>OID</acronym> of the data type of the specified column
2763 or <symbol>InvalidOid</symbol> on error. On error,
2764 <varname>SPI_result</varname> is set to
2765 <symbol>SPI_ERROR_NOATTRIBUTE</symbol>.
2766 </para>
2767 </refsect1>
2768 </refentry>
2770 <!-- *********************************************** -->
2772 <refentry id="spi-spi-getrelname">
2773 <refmeta>
2774 <refentrytitle>SPI_getrelname</refentrytitle>
2775 </refmeta>
2777 <refnamediv>
2778 <refname>SPI_getrelname</refname>
2779 <refpurpose>return the name of the specified relation</refpurpose>
2780 </refnamediv>
2782 <indexterm><primary>SPI_getrelname</primary></indexterm>
2784 <refsynopsisdiv>
2785 <synopsis>
2786 char * SPI_getrelname(Relation <parameter>rel</parameter>)
2787 </synopsis>
2788 </refsynopsisdiv>
2790 <refsect1>
2791 <title>Description</title>
2793 <para>
2794 <function>SPI_getrelname</function> returns a copy of the name of the
2795 specified relation. (You can use <function>pfree</function> to
2796 release the copy of the name when you don't need it anymore.)
2797 </para>
2798 </refsect1>
2800 <refsect1>
2801 <title>Arguments</title>
2803 <variablelist>
2804 <varlistentry>
2805 <term><literal>Relation <parameter>rel</parameter></literal></term>
2806 <listitem>
2807 <para>
2808 input relation
2809 </para>
2810 </listitem>
2811 </varlistentry>
2812 </variablelist>
2813 </refsect1>
2815 <refsect1>
2816 <title>Return Value</title>
2818 <para>
2819 The name of the specified relation.
2820 </para>
2821 </refsect1>
2822 </refentry>
2824 <refentry id="spi-spi-getnspname">
2825 <refmeta>
2826 <refentrytitle>SPI_getnspname</refentrytitle>
2827 </refmeta>
2829 <refnamediv>
2830 <refname>SPI_getnspname</refname>
2831 <refpurpose>return the namespace of the specified relation</refpurpose>
2832 </refnamediv>
2834 <indexterm><primary>SPI_getnspname</primary></indexterm>
2836 <refsynopsisdiv>
2837 <synopsis>
2838 char * SPI_getnspname(Relation <parameter>rel</parameter>)
2839 </synopsis>
2840 </refsynopsisdiv>
2842 <refsect1>
2843 <title>Description</title>
2845 <para>
2846 <function>SPI_getnspname</function> returns a copy of the name of
2847 the namespace that the specified <structname>Relation</structname>
2848 belongs to. This is equivalent to the relation's schema. You should
2849 <function>pfree</function> the return value of this function when
2850 you are finished with it.
2851 </para>
2852 </refsect1>
2854 <refsect1>
2855 <title>Arguments</title>
2857 <variablelist>
2858 <varlistentry>
2859 <term><literal>Relation <parameter>rel</parameter></literal></term>
2860 <listitem>
2861 <para>
2862 input relation
2863 </para>
2864 </listitem>
2865 </varlistentry>
2866 </variablelist>
2867 </refsect1>
2869 <refsect1>
2870 <title>Return Value</title>
2872 <para>
2873 The name of the specified relation's namespace.
2874 </para>
2875 </refsect1>
2876 </refentry>
2878 </sect1>
2880 <sect1 id="spi-memory">
2881 <title>Memory Management</title>
2883 <para>
2884 <productname>PostgreSQL</productname> allocates memory within
2885 <firstterm>memory contexts</firstterm><indexterm><primary>memory
2886 context</primary><secondary>in SPI</secondary></indexterm>, which provide a convenient method of
2887 managing allocations made in many different places that need to
2888 live for differing amounts of time. Destroying a context releases
2889 all the memory that was allocated in it. Thus, it is not necessary
2890 to keep track of individual objects to avoid memory leaks; instead
2891 only a relatively small number of contexts have to be managed.
2892 <function>palloc</function> and related functions allocate memory
2893 from the <quote>current</> context.
2894 </para>
2896 <para>
2897 <function>SPI_connect</function> creates a new memory context and
2898 makes it current. <function>SPI_finish</function> restores the
2899 previous current memory context and destroys the context created by
2900 <function>SPI_connect</function>. These actions ensure that
2901 transient memory allocations made inside your procedure are
2902 reclaimed at procedure exit, avoiding memory leakage.
2903 </para>
2905 <para>
2906 However, if your procedure needs to return an object in allocated
2907 memory (such as a value of a pass-by-reference data type), you
2908 cannot allocate that memory using <function>palloc</function>, at
2909 least not while you are connected to SPI. If you try, the object
2910 will be deallocated by <function>SPI_finish</function>, and your
2911 procedure will not work reliably. To solve this problem, use
2912 <function>SPI_palloc</function> to allocate memory for your return
2913 object. <function>SPI_palloc</function> allocates memory in the
2914 <quote>upper executor context</quote>, that is, the memory context
2915 that was current when <function>SPI_connect</function> was called,
2916 which is precisely the right context for a value returned from your
2917 procedure.
2918 </para>
2920 <para>
2921 If <function>SPI_palloc</function> is called while the procedure is
2922 not connected to SPI, then it acts the same as a normal
2923 <function>palloc</function>. Before a procedure connects to the
2924 SPI manager, the current memory context is the upper executor
2925 context, so all allocations made by the procedure via
2926 <function>palloc</function> or by SPI utility functions are made in
2927 this context.
2928 </para>
2930 <para>
2931 When <function>SPI_connect</function> is called, the private
2932 context of the procedure, which is created by
2933 <function>SPI_connect</function>, is made the current context. All
2934 allocations made by <function>palloc</function>,
2935 <function>repalloc</function>, or SPI utility functions (except for
2936 <function>SPI_copytuple</function>,
2937 <function>SPI_returntuple</function>,
2938 <function>SPI_modifytuple</function>, and
2939 <function>SPI_palloc</function>) are made in this context. When a
2940 procedure disconnects from the SPI manager (via
2941 <function>SPI_finish</function>) the current context is restored to
2942 the upper executor context, and all allocations made in the
2943 procedure memory context are freed and cannot be used any more.
2944 </para>
2946 <para>
2947 All functions described in this section can be used by both
2948 connected and unconnected procedures. In an unconnected procedure,
2949 they act the same as the underlying ordinary server functions
2950 (<function>palloc</>, etc.).
2951 </para>
2953 <!-- *********************************************** -->
2955 <refentry id="spi-spi-palloc">
2956 <refmeta>
2957 <refentrytitle>SPI_palloc</refentrytitle>
2958 </refmeta>
2960 <refnamediv>
2961 <refname>SPI_palloc</refname>
2962 <refpurpose>allocate memory in the upper executor context</refpurpose>
2963 </refnamediv>
2965 <indexterm><primary>SPI_palloc</primary></indexterm>
2967 <refsynopsisdiv>
2968 <synopsis>
2969 void * SPI_palloc(Size <parameter>size</parameter>)
2970 </synopsis>
2971 </refsynopsisdiv>
2973 <refsect1>
2974 <title>Description</title>
2976 <para>
2977 <function>SPI_palloc</function> allocates memory in the upper
2978 executor context.
2979 </para>
2980 </refsect1>
2982 <refsect1>
2983 <title>Arguments</title>
2985 <variablelist>
2986 <varlistentry>
2987 <term><literal>Size <parameter>size</parameter></literal></term>
2988 <listitem>
2989 <para>
2990 size in bytes of storage to allocate
2991 </para>
2992 </listitem>
2993 </varlistentry>
2994 </variablelist>
2995 </refsect1>
2997 <refsect1>
2998 <title>Return Value</title>
3000 <para>
3001 pointer to new storage space of the specified size
3002 </para>
3003 </refsect1>
3004 </refentry>
3006 <!-- *********************************************** -->
3008 <refentry id="spi-realloc">
3009 <refmeta>
3010 <refentrytitle>SPI_repalloc</refentrytitle>
3011 </refmeta>
3013 <refnamediv>
3014 <refname>SPI_repalloc</refname>
3015 <refpurpose>reallocate memory in the upper executor context</refpurpose>
3016 </refnamediv>
3018 <indexterm><primary>SPI_repalloc</primary></indexterm>
3020 <refsynopsisdiv>
3021 <synopsis>
3022 void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)
3023 </synopsis>
3024 </refsynopsisdiv>
3026 <refsect1>
3027 <title>Description</title>
3029 <para>
3030 <function>SPI_repalloc</function> changes the size of a memory
3031 segment previously allocated using <function>SPI_palloc</function>.
3032 </para>
3034 <para>
3035 This function is no longer different from plain
3036 <function>repalloc</function>. It's kept just for backward
3037 compatibility of existing code.
3038 </para>
3039 </refsect1>
3041 <refsect1>
3042 <title>Arguments</title>
3044 <variablelist>
3045 <varlistentry>
3046 <term><literal>void * <parameter>pointer</parameter></literal></term>
3047 <listitem>
3048 <para>
3049 pointer to existing storage to change
3050 </para>
3051 </listitem>
3052 </varlistentry>
3054 <varlistentry>
3055 <term><literal>Size <parameter>size</parameter></literal></term>
3056 <listitem>
3057 <para>
3058 size in bytes of storage to allocate
3059 </para>
3060 </listitem>
3061 </varlistentry>
3062 </variablelist>
3063 </refsect1>
3065 <refsect1>
3066 <title>Return Value</title>
3068 <para>
3069 pointer to new storage space of specified size with the contents
3070 copied from the existing area
3071 </para>
3072 </refsect1>
3073 </refentry>
3075 <!-- *********************************************** -->
3077 <refentry id="spi-spi-pfree">
3078 <refmeta>
3079 <refentrytitle>SPI_pfree</refentrytitle>
3080 </refmeta>
3082 <refnamediv>
3083 <refname>SPI_pfree</refname>
3084 <refpurpose>free memory in the upper executor context</refpurpose>
3085 </refnamediv>
3087 <indexterm><primary>SPI_pfree</primary></indexterm>
3089 <refsynopsisdiv>
3090 <synopsis>
3091 void SPI_pfree(void * <parameter>pointer</parameter>)
3092 </synopsis>
3093 </refsynopsisdiv>
3095 <refsect1>
3096 <title>Description</title>
3098 <para>
3099 <function>SPI_pfree</function> frees memory previously allocated
3100 using <function>SPI_palloc</function> or
3101 <function>SPI_repalloc</function>.
3102 </para>
3104 <para>
3105 This function is no longer different from plain
3106 <function>pfree</function>. It's kept just for backward
3107 compatibility of existing code.
3108 </para>
3109 </refsect1>
3111 <refsect1>
3112 <title>Arguments</title>
3114 <variablelist>
3115 <varlistentry>
3116 <term><literal>void * <parameter>pointer</parameter></literal></term>
3117 <listitem>
3118 <para>
3119 pointer to existing storage to free
3120 </para>
3121 </listitem>
3122 </varlistentry>
3123 </variablelist>
3124 </refsect1>
3125 </refentry>
3127 <!-- *********************************************** -->
3129 <refentry id="spi-spi-copytuple">
3130 <refmeta>
3131 <refentrytitle>SPI_copytuple</refentrytitle>
3132 </refmeta>
3134 <refnamediv>
3135 <refname>SPI_copytuple</refname>
3136 <refpurpose>make a copy of a row in the upper executor context</refpurpose>
3137 </refnamediv>
3139 <indexterm><primary>SPI_copytuple</primary></indexterm>
3141 <refsynopsisdiv>
3142 <synopsis>
3143 HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>)
3144 </synopsis>
3145 </refsynopsisdiv>
3147 <refsect1>
3148 <title>Description</title>
3150 <para>
3151 <function>SPI_copytuple</function> makes a copy of a row in the
3152 upper executor context. This is normally used to return a modified
3153 row from a trigger. In a function declared to return a composite
3154 type, use <function>SPI_returntuple</function> instead.
3155 </para>
3156 </refsect1>
3158 <refsect1>
3159 <title>Arguments</title>
3161 <variablelist>
3162 <varlistentry>
3163 <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3164 <listitem>
3165 <para>
3166 row to be copied
3167 </para>
3168 </listitem>
3169 </varlistentry>
3170 </variablelist>
3171 </refsect1>
3173 <refsect1>
3174 <title>Return Value</title>
3176 <para>
3177 the copied row; <symbol>NULL</symbol> only if
3178 <parameter>tuple</parameter> is <symbol>NULL</symbol>
3179 </para>
3180 </refsect1>
3181 </refentry>
3183 <!-- *********************************************** -->
3185 <refentry id="spi-spi-returntuple">
3186 <refmeta>
3187 <refentrytitle>SPI_returntuple</refentrytitle>
3188 </refmeta>
3190 <refnamediv>
3191 <refname>SPI_returntuple</refname>
3192 <refpurpose>prepare to return a tuple as a Datum</refpurpose>
3193 </refnamediv>
3195 <indexterm><primary>SPI_returntuple</primary></indexterm>
3197 <refsynopsisdiv>
3198 <synopsis>
3199 HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)
3200 </synopsis>
3201 </refsynopsisdiv>
3203 <refsect1>
3204 <title>Description</title>
3206 <para>
3207 <function>SPI_returntuple</function> makes a copy of a row in
3208 the upper executor context, returning it in the form of a row type <type>Datum</type>.
3209 The returned pointer need only be converted to <type>Datum</type> via <function>PointerGetDatum</function>
3210 before returning.
3211 </para>
3213 <para>
3214 Note that this should be used for functions that are declared to return
3215 composite types. It is not used for triggers; use
3216 <function>SPI_copytuple</> for returning a modified row in a trigger.
3217 </para>
3218 </refsect1>
3220 <refsect1>
3221 <title>Arguments</title>
3223 <variablelist>
3224 <varlistentry>
3225 <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3226 <listitem>
3227 <para>
3228 row to be copied
3229 </para>
3230 </listitem>
3231 </varlistentry>
3233 <varlistentry>
3234 <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
3235 <listitem>
3236 <para>
3237 descriptor for row (pass the same descriptor each time for most
3238 effective caching)
3239 </para>
3240 </listitem>
3241 </varlistentry>
3242 </variablelist>
3243 </refsect1>
3245 <refsect1>
3246 <title>Return Value</title>
3248 <para>
3249 <type>HeapTupleHeader</type> pointing to copied row;
3250 <symbol>NULL</symbol> only if
3251 <parameter>row</parameter> or <parameter>rowdesc</parameter> is
3252 <symbol>NULL</symbol>
3253 </para>
3254 </refsect1>
3255 </refentry>
3257 <!-- *********************************************** -->
3259 <refentry id="spi-spi-modifytuple">
3260 <refmeta>
3261 <refentrytitle>SPI_modifytuple</refentrytitle>
3262 </refmeta>
3264 <refnamediv>
3265 <refname>SPI_modifytuple</refname>
3266 <refpurpose>create a row by replacing selected fields of a given row</refpurpose>
3267 </refnamediv>
3269 <indexterm><primary>SPI_modifytuple</primary></indexterm>
3271 <refsynopsisdiv>
3272 <synopsis>
3273 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>)
3274 </synopsis>
3275 </refsynopsisdiv>
3277 <refsect1>
3278 <title>Description</title>
3280 <para>
3281 <function>SPI_modifytuple</function> creates a new row by
3282 substituting new values for selected columns, copying the original
3283 row's columns at other positions. The input row is not modified.
3284 </para>
3285 </refsect1>
3287 <refsect1>
3288 <title>Arguments</title>
3290 <variablelist>
3291 <varlistentry>
3292 <term><literal>Relation <parameter>rel</parameter></literal></term>
3293 <listitem>
3294 <para>
3295 Used only as the source of the row descriptor for the row.
3296 (Passing a relation rather than a row descriptor is a
3297 misfeature.)
3298 </para>
3299 </listitem>
3300 </varlistentry>
3302 <varlistentry>
3303 <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3304 <listitem>
3305 <para>
3306 row to be modified
3307 </para>
3308 </listitem>
3309 </varlistentry>
3311 <varlistentry>
3312 <term><literal>int <parameter>ncols</parameter></literal></term>
3313 <listitem>
3314 <para>
3315 number of column numbers in the array
3316 <parameter>colnum</parameter>
3317 </para>
3318 </listitem>
3319 </varlistentry>
3321 <varlistentry>
3322 <term><literal>int * <parameter>colnum</parameter></literal></term>
3323 <listitem>
3324 <para>
3325 array of the numbers of the columns that are to be changed
3326 (column numbers start at 1)
3327 </para>
3328 </listitem>
3329 </varlistentry>
3331 <varlistentry>
3332 <term><literal>Datum * <parameter>values</parameter></literal></term>
3333 <listitem>
3334 <para>
3335 new values for the specified columns
3336 </para>
3337 </listitem>
3338 </varlistentry>
3340 <varlistentry>
3341 <term><literal>const char * <parameter>Nulls</parameter></literal></term>
3342 <listitem>
3343 <para>
3344 which new values are null, if any (see
3345 <function>SPI_execute_plan</function> for the format)
3346 </para>
3347 </listitem>
3348 </varlistentry>
3349 </variablelist>
3350 </refsect1>
3352 <refsect1>
3353 <title>Return Value</title>
3355 <para>
3356 new row with modifications, allocated in the upper executor
3357 context; <symbol>NULL</symbol> only if <parameter>row</parameter>
3358 is <symbol>NULL</symbol>
3359 </para>
3361 <para>
3362 On error, <varname>SPI_result</varname> is set as follows:
3363 <variablelist>
3364 <varlistentry>
3365 <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
3366 <listitem>
3367 <para>
3368 if <parameter>rel</> is <symbol>NULL</>, or if
3369 <parameter>row</> is <symbol>NULL</>, or if <parameter>ncols</>
3370 is less than or equal to 0, or if <parameter>colnum</> is
3371 <symbol>NULL</>, or if <parameter>values</> is <symbol>NULL</>.
3372 </para>
3373 </listitem>
3374 </varlistentry>
3376 <varlistentry>
3377 <term><symbol>SPI_ERROR_NOATTRIBUTE</symbol></term>
3378 <listitem>
3379 <para>
3380 if <parameter>colnum</> contains an invalid column number (less
3381 than or equal to 0 or greater than the number of column in
3382 <parameter>row</>)
3383 </para>
3384 </listitem>
3385 </varlistentry>
3386 </variablelist>
3387 </para>
3388 </refsect1>
3389 </refentry>
3391 <!-- *********************************************** -->
3393 <refentry id="spi-spi-freetuple">
3394 <refmeta>
3395 <refentrytitle>SPI_freetuple</refentrytitle>
3396 </refmeta>
3398 <refnamediv>
3399 <refname>SPI_freetuple</refname>
3400 <refpurpose>free a row allocated in the upper executor context</refpurpose>
3401 </refnamediv>
3403 <indexterm><primary>SPI_freetuple</primary></indexterm>
3405 <refsynopsisdiv>
3406 <synopsis>
3407 void SPI_freetuple(HeapTuple <parameter>row</parameter>)
3408 </synopsis>
3409 </refsynopsisdiv>
3411 <refsect1>
3412 <title>Description</title>
3414 <para>
3415 <function>SPI_freetuple</function> frees a row previously allocated
3416 in the upper executor context.
3417 </para>
3419 <para>
3420 This function is no longer different from plain
3421 <function>heap_freetuple</function>. It's kept just for backward
3422 compatibility of existing code.
3423 </para>
3424 </refsect1>
3426 <refsect1>
3427 <title>Arguments</title>
3429 <variablelist>
3430 <varlistentry>
3431 <term><literal>HeapTuple <parameter>row</parameter></literal></term>
3432 <listitem>
3433 <para>
3434 row to free
3435 </para>
3436 </listitem>
3437 </varlistentry>
3438 </variablelist>
3439 </refsect1>
3440 </refentry>
3442 <!-- *********************************************** -->
3444 <refentry id="spi-spi-freetupletable">
3445 <refmeta>
3446 <refentrytitle>SPI_freetuptable</refentrytitle>
3447 </refmeta>
3449 <refnamediv>
3450 <refname>SPI_freetuptable</refname>
3451 <refpurpose>free a row set created by <function>SPI_execute</> or a similar
3452 function</refpurpose>
3453 </refnamediv>
3455 <indexterm><primary>SPI_freetuptable</primary></indexterm>
3457 <refsynopsisdiv>
3458 <synopsis>
3459 void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)
3460 </synopsis>
3461 </refsynopsisdiv>
3463 <refsect1>
3464 <title>Description</title>
3466 <para>
3467 <function>SPI_freetuptable</function> frees a row set created by a
3468 prior SPI command execution function, such as
3469 <function>SPI_execute</>. Therefore, this function is usually called
3470 with the global variable <varname>SPI_tupletable</varname> as
3471 argument.
3472 </para>
3474 <para>
3475 This function is useful if a SPI procedure needs to execute
3476 multiple commands and does not want to keep the results of earlier
3477 commands around until it ends. Note that any unfreed row sets will
3478 be freed anyway at <function>SPI_finish</>.
3479 </para>
3480 </refsect1>
3482 <refsect1>
3483 <title>Arguments</title>
3485 <variablelist>
3486 <varlistentry>
3487 <term><literal>SPITupleTable * <parameter>tuptable</parameter></literal></term>
3488 <listitem>
3489 <para>
3490 pointer to row set to free
3491 </para>
3492 </listitem>
3493 </varlistentry>
3494 </variablelist>
3495 </refsect1>
3496 </refentry>
3498 <!-- *********************************************** -->
3500 <refentry id="spi-spi-freeplan">
3501 <refmeta>
3502 <refentrytitle>SPI_freeplan</refentrytitle>
3503 </refmeta>
3505 <refnamediv>
3506 <refname>SPI_freeplan</refname>
3507 <refpurpose>free a previously saved plan</refpurpose>
3508 </refnamediv>
3510 <indexterm><primary>SPI_freeplan</primary></indexterm>
3512 <refsynopsisdiv>
3513 <synopsis>
3514 int SPI_freeplan(SPIPlanPtr <parameter>plan</parameter>)
3515 </synopsis>
3516 </refsynopsisdiv>
3518 <refsect1>
3519 <title>Description</title>
3521 <para>
3522 <function>SPI_freeplan</function> releases a command execution plan
3523 previously returned by <function>SPI_prepare</function> or saved by
3524 <function>SPI_saveplan</function>.
3525 </para>
3526 </refsect1>
3528 <refsect1>
3529 <title>Arguments</title>
3531 <variablelist>
3532 <varlistentry>
3533 <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
3534 <listitem>
3535 <para>
3536 pointer to plan to free
3537 </para>
3538 </listitem>
3539 </varlistentry>
3540 </variablelist>
3541 </refsect1>
3543 <refsect1>
3544 <title>Return Value</title>
3546 <para>
3547 <symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>plan</parameter>
3548 is <symbol>NULL</symbol> or invalid
3549 </para>
3550 </refsect1>
3551 </refentry>
3553 </sect1>
3555 <sect1 id="spi-visibility">
3556 <title>Visibility of Data Changes</title>
3558 <para>
3559 The following rules govern the visibility of data changes in
3560 functions that use SPI (or any other C function):
3562 <itemizedlist>
3563 <listitem>
3564 <para>
3565 During the execution of an SQL command, any data changes made by
3566 the command are invisible to the command itself. For
3567 example, in:
3568 <programlisting>
3569 INSERT INTO a SELECT * FROM a;
3570 </programlisting>
3571 the inserted rows are invisible to the <command>SELECT</command>
3572 part.
3573 </para>
3574 </listitem>
3576 <listitem>
3577 <para>
3578 Changes made by a command C are visible to all commands that are
3579 started after C, no matter whether they are started inside C
3580 (during the execution of C) or after C is done.
3581 </para>
3582 </listitem>
3584 <listitem>
3585 <para>
3586 Commands executed via SPI inside a function called by an SQL command
3587 (either an ordinary function or a trigger) follow one or the
3588 other of the above rules depending on the read/write flag passed
3589 to SPI. Commands executed in read-only mode follow the first
3590 rule: they cannot see changes of the calling command. Commands executed
3591 in read-write mode follow the second rule: they can see all changes made
3592 so far.
3593 </para>
3594 </listitem>
3596 <listitem>
3597 <para>
3598 All standard procedural languages set the SPI read-write mode
3599 depending on the volatility attribute of the function. Commands of
3600 <literal>STABLE</> and <literal>IMMUTABLE</> functions are done in
3601 read-only mode, while commands of <literal>VOLATILE</> functions are
3602 done in read-write mode. While authors of C functions are able to
3603 violate this convention, it's unlikely to be a good idea to do so.
3604 </para>
3605 </listitem>
3606 </itemizedlist>
3607 </para>
3609 <para>
3610 The next section contains an example that illustrates the
3611 application of these rules.
3612 </para>
3613 </sect1>
3615 <sect1 id="spi-examples">
3616 <title>Examples</title>
3618 <para>
3619 This section contains a very simple example of SPI usage. The
3620 procedure <function>execq</function> takes an SQL command as its
3621 first argument and a row count as its second, executes the command
3622 using <function>SPI_exec</function> and returns the number of rows
3623 that were processed by the command. You can find more complex
3624 examples for SPI in the source tree in
3625 <filename>src/test/regress/regress.c</filename> and in
3626 <filename>contrib/spi</filename>.
3627 </para>
3629 <programlisting>
3630 #include "postgres.h"
3632 #include "executor/spi.h"
3633 #include "utils/builtins.h"
3635 #ifdef PG_MODULE_MAGIC
3636 PG_MODULE_MAGIC;
3637 #endif
3639 int execq(text *sql, int cnt);
3642 execq(text *sql, int cnt)
3644 char *command;
3645 int ret;
3646 int proc;
3648 /* Convert given text object to a C string */
3649 command = text_to_cstring(sql);
3651 SPI_connect();
3653 ret = SPI_exec(command, cnt);
3655 proc = SPI_processed;
3657 * If some rows were fetched, print them via elog(INFO).
3659 if (ret &gt; 0 &amp;&amp; SPI_tuptable != NULL)
3661 TupleDesc tupdesc = SPI_tuptable-&gt;tupdesc;
3662 SPITupleTable *tuptable = SPI_tuptable;
3663 char buf[8192];
3664 int i, j;
3666 for (j = 0; j &lt; proc; j++)
3668 HeapTuple tuple = tuptable-&gt;vals[j];
3670 for (i = 1, buf[0] = 0; i &lt;= tupdesc-&gt;natts; i++)
3671 snprintf(buf + strlen (buf), sizeof(buf) - strlen(buf), " %s%s",
3672 SPI_getvalue(tuple, tupdesc, i),
3673 (i == tupdesc-&gt;natts) ? " " : " |");
3674 elog(INFO, "EXECQ: %s", buf);
3678 SPI_finish();
3679 pfree(command);
3681 return (proc);
3683 </programlisting>
3685 <para>
3686 (This function uses call convention version 0, to make the example
3687 easier to understand. In real applications you should use the new
3688 version 1 interface.)
3689 </para>
3691 <para>
3692 This is how you declare the function after having compiled it into
3693 a shared library (details are in <xref linkend="dfunc">.):
3695 <programlisting>
3696 CREATE FUNCTION execq(text, integer) RETURNS integer
3697 AS '<replaceable>filename</replaceable>'
3698 LANGUAGE C;
3699 </programlisting>
3700 </para>
3702 <para>
3703 Here is a sample session:
3705 <programlisting>
3706 =&gt; SELECT execq('CREATE TABLE a (x integer)', 0);
3707 execq
3708 -------
3710 (1 row)
3712 =&gt; INSERT INTO a VALUES (execq('INSERT INTO a VALUES (0)', 0));
3713 INSERT 0 1
3714 =&gt; SELECT execq('SELECT * FROM a', 0);
3715 INFO: EXECQ: 0 -- inserted by execq
3716 INFO: EXECQ: 1 -- returned by execq and inserted by upper INSERT
3718 execq
3719 -------
3721 (1 row)
3723 =&gt; SELECT execq('INSERT INTO a SELECT x + 2 FROM a', 1);
3724 execq
3725 -------
3727 (1 row)
3729 =&gt; SELECT execq('SELECT * FROM a', 10);
3730 INFO: EXECQ: 0
3731 INFO: EXECQ: 1
3732 INFO: EXECQ: 2 -- 0 + 2, only one row inserted - as specified
3734 execq
3735 -------
3736 3 -- 10 is the max value only, 3 is the real number of rows
3737 (1 row)
3739 =&gt; DELETE FROM a;
3740 DELETE 3
3741 =&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
3742 INSERT 0 1
3743 =&gt; SELECT * FROM a;
3746 1 -- no rows in a (0) + 1
3747 (1 row)
3749 =&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
3750 INFO: EXECQ: 1
3751 INSERT 0 1
3752 =&gt; SELECT * FROM a;
3756 2 -- there was one row in a + 1
3757 (2 rows)
3759 -- This demonstrates the data changes visibility rule:
3761 =&gt; INSERT INTO a SELECT execq('SELECT * FROM a', 0) * x FROM a;
3762 INFO: EXECQ: 1
3763 INFO: EXECQ: 2
3764 INFO: EXECQ: 1
3765 INFO: EXECQ: 2
3766 INFO: EXECQ: 2
3767 INSERT 0 2
3768 =&gt; SELECT * FROM a;
3773 2 -- 2 rows * 1 (x in first row)
3774 6 -- 3 rows (2 + 1 just inserted) * 2 (x in second row)
3775 (4 rows) ^^^^^^
3776 rows visible to execq() in different invocations
3777 </programlisting>
3778 </para>
3779 </sect1>
3780 </chapter>