.\\" auto-generated by docbook2man-spec $Revision: 1.2 $
.TH "SPI_execute" "" "2005-01-19" "" "PostgreSQL 8.0.2 文書"
.SH NAME
SPI_execute \- コマンドを実行します。

.SH SYNOPSIS
.sp
.nf
int SPI_execute(const char * \fIcommand\fR, bool \fIread_only\fR, int \fIcount\fR)
.sp
.fi
.SH "説明"
.PP
\fBSPI_execute\fR は指定したSQLコマンドを、\fIcount\fR行分実行します。
\fIread_only\fRがtrueの場合、そのコマンドは読み取りのみでなければなりませんが、多少のオーバヘッドが削減されます。
.PP
この関数は接続済みのプロシージャからのみ呼び出し可能です。
.PP
\fIcount\fRが0の場合、そのコマンドを、適用される全ての行に対して実行します。
\fIcount\fRが0より多ければ、そのコマンドが実行される行数は制限されます。
(ほぼLIMITと似ています。)
例えば、
.sp
.nf
SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
.sp
.fi
は、テーブルに挿入できる行は多くても5行のみです。
.PP
複数のコマンドを1つの文字列として渡すことができます。
\fBSPI_execute\fRは最後に実行したコマンドの結果を返します。
\fIcount\fR制限はそれぞれのコマンドに独立に適用されますが、ルールによって生成される隠れたコマンドには適用されません。
.PP
\fIread_only\fRがfalseの場合、文字列内の各コマンドを実行する前に\fBSPI_execute\fRはコマンドカウンタを増分し、新しい\fIスナップショット\fRを作成します。
このスナップショットは、現在のトランザクション隔離レベルがSERIALIZABLEの場合は変更されません。
しかし、READ COMMITTEDモードでは、このスナップショットは更新され、他のセッションで新しくコミットされたトランザクションの結果を各コマンドから参照できます。
これは、そのコマンドがデータベースを変更する場合、一貫性の維持に重要です。
.PP
\fIread_only\fRがtrueの場合は、\fBSPI_execute\fRはスナップショットもコマンドカウンタも更新しません。
更に、普通の\fBSELECT\fRコマンドのみをコマンド文字列内に記述することができます。
このコマンドは、その前後の問い合わせによって事前に確立済みのスナップショットを使用して実行されます。
この実行モードは読み書きモードよりもコマンド毎のオーバヘッドが省略される分多少高速です。
また、これにより本当に\fI安定(stable)\fRな関数を構築することができます。
つまり、連続した実行は全て同じスナップショットを使用しますので、結果は変わることがないということです。
.PP
一般的に、SPIを使用する1つの関数内で読み取りのみコマンドと読み書きコマンドを混在させることは勧めません。
読み取りのみの問い合わせでは、読み書き問い合わせでなされたデータベースの更新結果を参照されないため、非常に混乱した動作に陥ることがあります。
.PP
(最後の)コマンドが実行した実際の行数は、(関数の戻り値が\fBSPI_OK_UTILITY\fRでない限り)SPI_processedグローバル変数内で渡されます。
関数の戻り値が\fBSPI_OK_SELECT\fRの場合、SPITupleTable *SPI_tuptableグローバルポインタを使用して、結果の行にアクセスすることができます。
.PP
\fBSPITupleTable\fR構造体は以下のように定義されています。
.sp
.nf
typedef struct
{
    MemoryContext tuptabcxt;    /* 結果テーブルのメモリコンテキスト */
    uint32      alloced;        /* 割り当て済みのvalsの数 */
    uint32      free;           /* 解放されたvalsの数 */
    TupleDesc   tupdesc;        /* 行記述子 */
    HeapTuple  *vals;           /* 行 */
} SPITupleTable;
.sp
.fi
\fBvals\fR が行へのポインタの配列です。
(有効な項目数はSPI_processedで判明します。)
\fBtupdesc\fRは、行を扱うSPI関数に渡すことができる行記述子です。
\fBtuptabcxt\fR、\fBalloced\fR、\fBfree\fRはSPI呼び出し元での使用を意図していない内部的なフィールドです。
.PP
\fBSPI_finish\fRは、現在のプロシージャで割り当てられた全ての\fBSPITupleTable\fRを解放します。
\fBSPI_freetuptable\fRを呼び出して解放する場合、特定の結果テーブルを早めに解放することができます。
.SH "引数"
.TP
\fBconst char * \fIcommand\fB\fR
実行するコマンドを含む文字列。
.TP
\fBbool \fIread_only\fB\fR
読み取りのみの実行の場合true。
.TP
\fBint \fIcount\fB\fR
処理される、あるいは、返される行の最大数。
.SH "戻り値"
.PP
コマンドの実行に成功した場合、以下のいずれかの(非負の)値が返されます。
.TP
\fBSPI_OK_SELECT\fR
\fBSELECT\fR (\fBSELECT INTO\fRを除く)が実行された場合。
.TP
\fBSPI_OK_SELINTO\fR
\fBSELECT INTO\fRが実行された場合。
.TP
\fBSPI_OK_DELETE\fR
\fBDELETE\fRが実行された場合。
.TP
\fBSPI_OK_INSERT\fR
\fBINSERT\fRが実行された場合。
.TP
\fBSPI_OK_UPDATE\fR
\fBUPDATE\fRが実行された場合。
.TP
\fBSPI_OK_UTILITY\fR
ユーティリティコマンド(\fBCREATE TABLE\fRなど)が実行された場合。
.PP
.PP
エラーの場合、以下のいずれかの負の値が返されます。
.TP
\fBSPI_ERROR_ARGUMENT\fR
\fIcommand\fRが\fBNULL\fR、あるいは、\fIcount\fRが0未満の場合。
.TP
\fBSPI_ERROR_COPY\fR
\fBCOPY TO stdout\fRあるいは\fBCOPY FROM stdin\fRが試行された場合。
.TP
\fBSPI_ERROR_CURSOR\fR
\fBDECLARE\fR、\fBCLOSE\fR、\fBFETCH\fRが試行された場合。
.TP
\fBSPI_ERROR_TRANSACTION\fR
\fBBEGIN\fR、\fBCOMMIT\fR、\fBROLLBACK\fR が試行された場合。
.TP
\fBSPI_ERROR_OPUNKNOWN\fR
コマンド種類が不明な場合。(起きてはなりません。)
.TP
\fBSPI_ERROR_UNCONNECTED\fR
未接続なプロシージャから呼び出された場合。
.PP
.SH "注意"
.PP
関数\fBSPI_execute\fR、\fBSPI_exec\fR、\fBSPI_execute_plan\fR、\fBSPI_execp\fRはSPI_processedとSPI_tuptable の両方を変更します。(ポインタのみで、構造体の内容は変更しません。)
\fBSPI_exec\fRやその関連する関数の結果テーブルを後の呼び出しで跨ってアクセスしたいのであれば、これら2つのグローバル変数を局所的なプロシージャ変数に保存してください。
