SPI_prepare
は指定したコマンド用の実行計画を作成し、それを返します。
しかし、そのコマンドは実行しません。
この関数は接続済のプロシージャからのみ呼び出さなければなりません。
同じ、あるいは類似のコマンドが繰り返し実行される場合、一度だけ計画作成を行うことに利点があります。
SPI_prepare
はコマンド文字列を、SPI_execute_plan
を使用して繰り返し実行することができる実行計画に変換します。
準備されたコマンドは、通常のコマンド内の定数となる場所を($1、$2などの)パラメータで記述することで一般化することができます。
そしてパラメータの実際の値は、SPI_execute_plan
が呼び出される時に指定されます。
これにより、準備されたコマンドは、パラメータがない場合に比べ、より広範な状況で使用できるようになります。
SPI_finish
は計画用に割り当てられたメモリを解放しますので、SPI_prepare
で返される計画は、そのプロシージャの現在の呼び出し内でのみ使用することができます。
しかし、SPI_saveplan
関数を使用して長期間計画を保存することもできます。
SPI_prepare
は、実行計画への非NULLのポインタを返します。
エラーの場合、NULLが返され、SPI_execute
で使用されるエラーコードと同じコードの1つがSPI_resultに設定されます。
しかし、commandがNULLの場合や、nargsが0未満の場合、nargsが0より大きくかつargtypesがNULLの場合は、SPI_ERROR_ARGUMENTに設定されます。