SPI_exec

名前

SPI_exec -- コマンドを実行します。

概要

int SPI_exec(const char * command, int count)

説明

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関数に渡すことができる行記述子です。 tuptabcxtallocedfreeはSPI呼び出し元での使用を意図していない内部的なフィールドです。

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

引数

const char * command

実行するコマンドを含む文字列。

int count

処理される、あるいは、返される行の最大数。

戻り値

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

SPI_OK_SELECT

SELECT (SELECT ... INTOを除く)が実行された場合。

SPI_OK_SELINTO

SELECT ... INTOが実行された場合。

SPI_OK_DELETE

DELETE が実行された場合。

SPI_OK_INSERT

INSERT が実行された場合。

SPI_OK_UPDATE

UPDATE が実行された場合。

SPI_OK_UTILITY

ユーティリティコマンド(CREATE TABLEなど)が実行された場合。

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

SPI_ERROR_ARGUMENT

commandNULL、あるいは、countが0未満の場合。

SPI_ERROR_COPY

COPY TO stdout あるいは COPY FROM stdinが試行された場合。

SPI_ERROR_CURSOR

DECLARECLOSEFETCHが試行された場合。

SPI_ERROR_TRANSACTION

BEGINCOMMITROLLBACK が試行された場合。

SPI_ERROR_OPUNKNOWN

コマンド種類が不明な場合。(起きてはなりません。)

SPI_ERROR_UNCONNECTED

未接続なプロシージャから呼び出された場合。

注意

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