SPI_exec

説明

SPI_exec は指定したSQLコマンドを、count行分実行します。

この関数は、接続したプロシージャからのみ呼び出さなければなりません。 countが0の場合、そのコマンドを、適用されるすべての行に対して実行します。 countが0より多ければ、そのコマンドが実行される行数は制限されます。 (ほぼLIMITと似ています。) 例えば、

SPI_exec("INSERT INTO tab SELECT * FROM tab", 5);

は、テーブルに挿入できる行は多くても5行のみです。

複数のコマンドを1つの文字列として渡すことができます。 コマンドはルールによって書き換えられることもあります。 SPI_execは最後に実行したコマンドの結果を返します。

(最後の)コマンドが実行した実際の行数は、(関数の戻り値がSPI_OK_UTILITYでない限り)SPI_processedグローバル変数内で渡されます。 関数の戻り値がSPI_OK_SELECTの場合、 SPITupleTable *SPI_tuptable グローバルポインタを使用して、結果の行にアクセスすることができます。

SPITupleTable構造体は以下のように定義されています。

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 が行へのポインタの配列です。 (有効な項目数はSPI_processedで判明します。) tupdescは、行を扱うSPI関数に渡すことができる行記述子です。 tuptabcxt、alloced、freeはSPI呼び出し元での使用を意図していない内部的なフィールドです。

SPI_finish は、現在のプロシージャで割り当てられたすべてのSPITupleTableを解放します。 SPI_freetuptableを呼び出して解放する場合、特定の結果テーブルを早めに解放することができます。

引数

戻り値

コマンドの実行に成功した場合、以下のいずれかの(非負の)値が返されます。

エラーの場合、以下のいずれかの負の値が返されます。

注意

SPI_exec、SPI_execp、SPI_prepare は SPI_processed と SPI_tuptable の両方を変更します。(ポインタのみで、構造体の内容は変更しません。) SPI_exec もしくは SPI_execp の結果を後の呼び出しと跨ってアクセスしたいのであれば、これら2つのグローバル変数を局所的なプロシージャ変数に保存して下さい。