SPI_exec(query, tcount)
| 未接続なプロシージャから呼び出された場合SPI_ERROR_UNCONNECTEDです。 |
| 問い合わせが NULL または、tcount < 0 の場合 SPI_ERROR_ARGUMENTです。 |
| 未接続なプロシージャから呼び出された場合 SPI_ERROR_UNCONNECTEDです。 |
| COPY TO/FROM stdinの場合 SPI_ERROR_COPYです。 |
| DECLARE/CLOSE CURSOR、FETCHの場合 SPI_ERROR_CURSOR です。 |
| BEGIN/ABORT/ENDの場合 SPI_ERROR_TRANSACTION です。 |
| 未知の問い合わせタイプの場合 SPI_ERROR_OPUNKNOWN です。（これは起こるべきではありません） |
| ユーティリティ（たとえばCREATE TABLE ...）が実行された場合 SPI_OK_UTILITY です。 |
| （SELECT ... INTO以外の）SELECTが実行された場合 SPI_OK_SELECTです。 |
| SELECT ... INTOが実行された場合 SPI_OK_SELINTO です。 |
| INSERT（またはINSERT ... SELECT）が実行された場合 SPI_OK_INSERT です。 |
| DELETEが実行された場合 SPI_OK_DELETE です。 |
| UPDATEが実行された場合 SPI_OK_UPDATE です。 |
接続済みのプロシージャからのみこの関数を呼び出してください。 tcountが0ならば、問い合わせスキャンが返したすべてのタプルについて問い合わせを行います。 tcount > 0とすることで、問い合わせの対象となるタプルの数を(LIMIT句とほぼ同様に)制限することができます。たとえば、以下の場合は、最大5個のタプルをテーブルに挿入することができます。
SPI_exec ("INSERT INTO tab SELECT * FROM tab", 5);
問い合わせの実行が成功した場合、負ではない値が返ります。
Note: 1個の文字列の中に複数の問い合わせを入れて渡したり、RULEシステムによって複数の問い合わせに書き換えられる可能性のある文字列を渡しても構いません。 SPI_execは最後に実行された問い合わせの結果を返します。
実際に（最後の）問い合わせの処理対象となったタプルの数は（ SPI_OK_UTILITYでない限り）グローバル変数SPI_processedに設定されます。もしSPI_OK_SELECT が返され、SPI_processed > 0ならば、グローバルなポインタであるSPITupleTable *SPI_tuptableというポインタを使って、結果のタプルにアクセスできます。
SPI_execは次のような（負の）値を返す可能性があります。
| 引数queryがNULLまたは tcount < 0の場合 SPI_ERROR_ARGUMENT です。 |
| 未接続なプロシージャの場合 SPI_ERROR_UNCONNECTED です。 |
| COPY TO/FROM stdinの場合 SPI_ERROR_COPY です。 |
| DECLARE/CLOSE CURSOR、FETCHの場合 SPI_ERROR_CURSOR です。 |
| BEGIN/ABORT/ENDの場合SPI_ERROR_TRANSACTION です。 |
| 未知の問い合わせタイプの場合SPI_ERROR_OPUNKNOWNです。（これは起こるべきではありません） |
もしSPI_OK_SELECTが返され、SPI_processed > 0である場合、グローバルポインタ SPITupleTable *SPI_tuptableを使って選択されたタプルにアクセスすることが可能です。
構造体SPITupleTableはspi.hの中で定義されています。
typedef struct
{
MemoryContext tuptabcxt; /* 結果タプルのメモリコンテキスト */
uint32 alloced; /* 割り当てられた値の数 */
uint32 free; /* 解放された値の数 */
TupleDesc tupdesc; /* タプル記述子 */
HeapTuple *vals; /* タプル */
} SPITupleTable;
vals はタプルへのポインタの配列です(有効なエントリ数は SPI_processed によって与えられます)。TupleDesc tupdescはタプルを扱うSPI関数へ渡すことのできるタプル記述子です。tuptabcxt、alloced、free は内部用のフィールドであり、SPI 呼び出し側での使用を目的としたものではありません。
Note: 関数SPI_exec、SPI_execpおよび SPI_prepareは、SPI_processedとSPI_tuptableの両方を変更します(ポインタのみで、構造体の内容ではありません)。 SPI_exec や SPI_execp の結果を後の呼び出しで使用することが必要ならば、この2つのグローバル変数をプロシージャのローカル変数に保存してください。
SPI_finish は、現在のプロシージャで割り当てられた、全てのSPITupleTablesを解放します。 SPI_freetuptable を呼び出すことで、使用しなくなった、特定の結果テーブルを前もって解放することができます。