| PostgreSQL 7.4.30 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Fast Forward | Next | |
SPI_exec executes the specified
SQL command for count rows.
This function should only be called from a connected procedure. If count is zero then it executes the command for all rows that it applies to. If count is greater than 0, then the number of rows for which the command will be executed is restricted (much like a LIMIT clause). For example,
SPI_exec("INSERT INTO tab SELECT * FROM tab", 5);
will allow at most 5 rows to be inserted into the table.
You may pass multiple commands in one string, and the command
may be rewritten by rules. SPI_exec
returns the result for the command executed last.
The actual number of rows for which the (last) command was executed is returned in the global variable SPI_processed (unless the return value of the function is SPI_OK_UTILITY). If the return value of the function is SPI_OK_SELECT then you may the use global pointer SPITupleTable *SPI_tuptable to access the result rows.
The structure SPITupleTable is defined thus:
typedef struct
{
MemoryContext tuptabcxt; /* memory context of result table */
uint32 alloced; /* number of alloced vals */
uint32 free; /* number of free vals */
TupleDesc tupdesc; /* row descriptor */
HeapTuple *vals; /* rows */
} SPITupleTable;
vals is an array of pointers to rows. (The number of valid entries is given by SPI_processed). tupdesc is a row descriptor which you may pass to SPI functions dealing with rows. tuptabcxt, alloced, and free are internal fields not intended for use by SPI callers.
SPI_finish frees all SPITupleTables allocated during the current
procedure. You can free a particular result table earlier, if you
are done with it, by calling SPI_freetuptable.
string containing command to execute
maximum number of rows to process or return
If the execution of the command was successful then one of the following (nonnegative) values will be returned:
if a SELECT (but not SELECT ... INTO) was executed
if a SELECT ... INTO was executed
if a DELETE was executed
if an INSERT was executed
if an UPDATE was executed
if a utility command (e.g., CREATE TABLE) was executed
On error, one of the following negative values is returned:
if command is NULL or count is less than 0
if COPY TO stdout or COPY FROM stdin was attempted
if DECLARE, CLOSE, or FETCH was attempted
if BEGIN, COMMIT, or ROLLBACK was attempted
if the command type is unknown (shouldn't happen)
if called from an unconnected procedure