# SPI_prepare ## Name SPI_prepare?--?準備一個規劃但不立即執行它 ## Synopsis ``` SPIPlanPtr SPI_prepare(const char * command, int nargs, Oid * argtypes) ``` ## 描述 `SPI_prepare`為聲明的命令創建和返回一個預備語句但是不執行查詢。 該預備語句稍后可以使用`SPI_execute_plan`重復的執行。 如果相同或者類似的查詢要多次重復執行，那么通常只進行一次解析分析應該是更好些， 并且此外可能有利于為該命令重復使用一個執行規劃。`SPI_prepare` 把一個命令字符串轉換成一個封裝解析分析的結果的預備語句。 如果發現為每個執行生成一個自定義規劃沒什么幫助， 那么該預備語句也為緩存一個執行規劃提供位置。 可以把預編寫的查詢通用化，方法是在那些普通查詢里是常量的地方書寫參數 (`$1`, `$2`等等)。參數的數值隨后在調用`SPI_execute_plan` 的時候聲明。這樣就允許已準備的查詢在遠比沒有參數時廣泛得多的場合下使用。 `SPI_prepare`返回的語句只能在當前過程調用中使用， 因為`SPI_finish`釋放為這樣一個語句分配的內存。不過， 一個語句可以用函數`SPI_keepplan`或`SPI_saveplan` 保存更長的時間。 ## 參數 `const char *` `command` 命令字符串 `int` `nargs` 輸入參數的個數(`$1`, `$2`等等) `Oid *` `argtypes` 一個指針，指向包含參數數據類型的OID數組 ## 返回值 `SPI_prepare`返回一個指向一個`SPIPlan`的非空指針， `SPIPlan`是一個表示預備語句的不透明結構。錯誤時將返回`NULL`， 并且`SPI_result`將設置為和`SPI_execute` 使用的同樣錯誤的錯誤代碼，例外是在`command`是 `NULL`的時候，或者是`nargs`小于 0 或者`nargs` 大于 0 并且`argtypes`是`NULL`的時候會被設置成 `SPI_ERROR_ARGUMENT`。 ## 注意 如果沒有定義參數，那么在第一次使用`SPI_execute_plan` 時將創建一個通用規劃，并且也用于所有隨后的執行。如果有參數， 前幾次使用`SPI_execute_plan`將生成特定于提供的參數值的自定義規劃。 相同的預備語句使用足夠多次之后，`SPI_execute_plan` 將建立一個通用規劃，并且如果該通用規劃并不比自定義規劃昂貴的多的話， 它將開始使用該通用規劃而不是每次重新規劃。如果這個缺省行為不合適， 你可以通過傳遞`CURSOR_OPT_GENERIC_PLAN`或`CURSOR_OPT_CUSTOM_PLAN` 標志到`SPI_prepare_cursor`來修改它，分別強制使用通用或自定義規劃。 盡管預備語句的要點是為了避免重復的解析分析和規劃語句， 但是在語句中使用的數據庫對象自上次使用預備語句以來經歷了明確的（DDL） 改變時，PostgreSQL將在使用它之前強制重新分析和重新規劃語句。 另外，如果[search_path](#calibre_link-738)的值在下一次使用時發生了改變時， 該語句將使用新的`search_path`重新解析。（后者的行為是 PostgreSQL 9.3新增的。）參閱[PREPARE](#calibre_link-625) 獲取更多關于預備語句的行為的信息。 這個函數應該只從一個已連接的過程中調用。 `SPIPlanPtr`聲明為一個指針，指向`spi.h`中的一個不透明的結構類型。 嘗試直接訪問它的內容是不明智的，因為那樣會使得你的代碼在未來的 PostgreSQL修訂版本中更容易破裂。 名字`SPIPlanPtr`是歷史用法，因為數據結構不再需要包含一個執行規劃。